README

Cobre Fácil API 集成官方 SDK。
要阅读 API 文档，请访问：https://developers.cobrefacil.com.br

先决条件

1. PHP >= 7.1
2. cURL
3. Composer

安装

安装通过 Composer 命令完成：

composer require cobrefacil/sdk-php

身份验证

为了执行身份验证，需要在 CobreFacil 类的构造函数中提供在您的账户面板中可用的 app_id 和 secret。

use CobreFacil\CobreFacil;

$cobrefacil = new CobreFacil($appId, $secret);

该类负责生成在请求中使用的 token，并简化对可用资源的访问。

默认情况下，该类使用 生产 环境，如果您想使用 沙盒 环境，只需调用 setProduction 方法并传递 false 值。

$cobrefacil = new CobreFacil($appId, $secret, false);
$cobrefacil->setProduction(false);

可用资源

目前我们的 SDK 提供了便于操作 客户、信用卡 和 收款 的方法。要了解应发送和接收哪些数据，请参阅 API 文档。

数据应以关联数组的格式发送

$params = [
    'customer_id' => 'Y73MNPGJ18Y18V5KQODX',
    'payable_with' => 'bankslip',
    //...
];
$response = $cobrefacil->invoice->create($params);

响应也是关联数组的格式，例如使用前一个示例中的 $response 变量

[
    'id' => '2KD9LGERW897NZ6JM5V4',
    'customer_id' => 'Y73MNPGJ18Y18V5KQODX',
    'payable_with' => 'bankslip',
    //...
];

客户

https://developers.cobrefacil.com.br/#clientes

// POST /customers
$cobrefacil->customer->create($params);

// PUT /customers/{id}
$cobrefacil->customer->update($id, $params);

// GET /customers
$cobrefacil->customer->search();

// GET /customers?email=exemplo@mail.com
$cobrefacil->customer->search(['email' => 'exemplo@mail.com']);

// GET /customers/{id}
$cobrefacil->customer->getById($id);

// DELETE /customers/{id}
$cobrefacil->customer->remove($id);

信用卡

https://developers.cobrefacil.com.br/#cartao-de-credito

// POST /cards
$cobrefacil->card->create($params);

// POST /cards/{id}/default
$cobrefacil->card->setDefault($id);

// GET /cards/{id}
$cobrefacil->card->getById($id);

// GET /cards
$cobrefacil->card->search();

// GET /cards?customer_id=Z8J53ROD2JK1PQ47WG0E
$cobrefacil->card->search(['customer_id' => 'Z8J53ROD2JK1PQ47WG0E']);

// DELETE /cards/{id}
$cobrefacil->card->remove($id);

收款

https://developers.cobrefacil.com.br/#cobrancas

// POST /invoices
$cobrefacil->invoice->create($params);

// POST /invoices/{id}/capture
$cobrefacil->invoice->capture($id, $amount);

// GET /invoices
$cobrefacil->invoice->search();

// GET /invoices?status=paid
$cobrefacil->invoice->search(['status' => 'paid']);

// POST /invoices/{id}/refund
$cobrefacil->invoice->refund($id, $amount);

// DELETE /invoices/{id}
$cobrefacil->invoice->cancel($id);

错误处理

https://developers.cobrefacil.com.br/#erros

如果在请求过程中发生错误，将返回一个 exception。

为了简化错误处理，我们提供了 3 个异常，有助于识别错误的类型。

身份验证错误

use CobreFacil\Exceptions\InvalidCredentialsException;

try {
    $cobrefacil = new CobreFacil($appId, $secret);
} catch (InvalidCredentialsException $e) {
    // 401 Unauthorized: As credenciais são inválidas
}

请求错误

use CobreFacil\Exceptions\InvalidParamsException;
use CobreFacil\Exceptions\ResourceNotFoundException;

try {
    $cobrefacil->customer->create($params);
} catch (InvalidParamsException $e) {
    // 400 Bad Request: Algum parâmetro obrigatório não foi enviado ou é inválido
    $e->getErrors();// retorna um array contendo os erros
} catch (ResourceNotFoundException $e) {
    // 404 Not Found: O registro solicitado não existe
}

Webhooks

https://developers.cobrefacil.com.br/#webhooks

为了简化处理接收到的 webhook 事件，我们提供了 WebhookEvent 类。

$receivedEvent = WebhookEvent::createFromJson($json);

使用它，您可以使用方法来辅助读取数据

$receivedEvent->getEvent();// nome do evento recebido, exemplo: invoice.created
$receivedEvent->getData();// dados da cobrança em forma de array associativo

还有方法来进行一些检查

$receivedEvent->isInvoiceCreated();// invoice.created
$receivedEvent->isInvoiceViewed();// invoice.viewed
$receivedEvent->isInvoiceReversed();// invoice.reversed
$receivedEvent->isInvoiceDeclined();// invoice.declined
$receivedEvent->isInvoicePreAuthorized();// invoice.pre_authorized
$receivedEvent->isInvoicePaid();// invoice.paid
$receivedEvent->isInvoiceRefunded();// invoice.refunded
$receivedEvent->isInvoiceCanceled();// invoice.canceled
$receivedEvent->isInvoiceDispute();// invoice.dispute
$receivedEvent->isInvoiceDisputeSucceeded();// invoice.dispute_succeeded
$receivedEvent->isInvoiceDisputeChargedBack();// invoice.charged_back