README

Billie PHP SDK 允许您轻松快速地将 Billie.io API 的 REST API 集成到现有代码库中，并使用它。

要求

PHP 7.4 或更高版本
cURL（包含在标准 PHP 发行版中，并已启用）
OpenSSL（包含在标准 PHP 发行版中，并已启用）

您需要一个Billie 账户来接收必要的凭证。

使用 Composer 安装

您可以使用 Composer（推荐技术）将 Billie PHP SDK 库作为项目依赖项。

如果您尚未安装 Composer，请遵循安装说明。仓库中包含 composer.json 文件，并且它已从 Packagist 引用。

要安装 SDK，只需执行以下命令

composer require billie/api-php-sdk

使用方法

通用使用

对于每个请求都有一个

请求服务（\Billie\Sdk\Service\Request\AbstractRequest 的实例）了解有关请求本身（url、方法、授权）的信息
请求模型（\Billie\Sdk\Model\Response\AbstractRequestModel 的实例）了解有关请求参数的信息，并作为 DTO 将数据提交给请求服务
响应模型（\Billie\Sdk\Model\Response\AbstractResponseModel 的实例）了解有关响应数据的信息，并作为 DTO 从请求服务接收数据注意：在某些情况下没有响应。如果请求成功，则返回 true

获取 `\Billie\Sdk\HttpClient\BillieClient` 实例

使用 \Billie\Sdk\Util\BillieClientFactory 获取新实例。

工厂将自动从网关请求新的认证令牌，并将其（与整个实例一起）存储在静态变量中。因此，如果您请求新的 BillieClient 实例，它不会生成新的请求。

$isSandbox = true;
$billieClient = \Billie\Sdk\Util\BillieClientFactory::getBillieClientInstance('YOUR-CLIENT-ID', 'YOUR-CLIENT-SECRET', $isSandbox);

提供布尔值作为第三个参数以定义请求是否针对沙盒。

获取请求服务的实例

您可以简单地创建相应类的实例。

示例:

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient **/

$requestService = new \Billie\Sdk\Service\Request\Order\CreateOrderRequest($billieClient);

您必须不通过构造函数提供 BillieClient，但在调用请求服务上的 execute 之前应该设置它。

示例:

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient **/

$requestService = new \Billie\Sdk\Service\Request\Order\CreateOrderRequest();
// [...]
$requestService->setClient($billieClient);
// [...]
$requestService->execute(...);

模型

请求模型：验证

请求模型（非响应模型）的每个字段都会在调用其设置器时自动验证。如果您提供错误的值或无效的格式，将抛出 \Billie\Sdk\Exception\Validation\InvalidFieldException。

您可以通过在模型上调用 setValidateOnSet 方法来禁用此自动验证

/** @var \Billie\Sdk\Model\Request\AbstractRequestModel $requestModel */

$requestModel->setValidateOnSet(false);

模型至少由请求服务进行验证，以确保已提供所有数据，并且您将通过网关获得没有验证异常。

响应模型

每个响应模型都设置为只读。

您不能在此模型上设置任何字段。您将获得一个 BadMethodCallException。

请求

本文档不应解释每个请求的整个使用方法。它应仅显示每个请求的主要信息和主要用法。

GetTokenRequest

使用此服务，您可以为您凭据创建新的认证令牌。

当使用\Billie\Sdk\Util\BillieClientFactory获取BillieClient时，该服务会自动被调用。

此请求服务是唯一的，不需要BillieClient实例。

使用方法

$isSandbox = true;
$tokenRequestService = new \Billie\Sdk\Service\Request\Auth\GetTokenRequest($isSandbox);

$requestModel = new \Billie\Sdk\Model\Request\Auth\GetTokenRequestModel();
$requestModel
    ->setClientId('YOUR-CLIENT-ID')
    ->setClientSecret('YOUR-SECRET-ID');
    
/** @var \Billie\Sdk\Model\Response\Auth\GetTokenResponseModel */
$responseModel = $tokenRequestService->execute($requestModel);
$accessToken = $responseModel->getAccessToken(); // use this token for further requests.

ValidateTokenRequest

使用此服务验证您的令牌是否仍然有效。如果令牌无效，您必须请求新的认证令牌。

如果令牌有效，您将收到响应。否则，您将收到一个\Billie\Sdk\Exception\UserNotAuthorizedException。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$validateTokenRequest = new \Billie\Sdk\Service\Request\Auth\ValidateTokenRequest($billieClient);

/** @var \Billie\Sdk\Model\Response\Auth\ValidateTokenResponse $responseModel */
$responseModel = $validateTokenRequest->execute(new \Billie\Sdk\Model\Request\Auth\ValidateTokenRequestModel());

注意：请求模型没有内容。请不要混淆。

RevokeTokenRequest

使用此服务撤销令牌。令牌应已存储在Billie-Client实例中。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$validateTokenRequest = new \Billie\Sdk\Service\Request\Auth\RevokeTokenRequest($billieClient);

/** @var bool $responseModel */
$responseModel = $validateTokenRequest->execute(new \Billie\Sdk\Model\Request\Auth\RevokeTokenRequestModel());

注意：请求模型没有内容。请不要混淆。

CreateSessionRequest

使用此服务在网关为客户创建新的结账会话。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\CheckoutSession\CreateSessionRequest($billieClient);

$requestModel = new \Billie\Sdk\Model\Request\CheckoutSession\CreateSessionRequestModel();
$requestModel->setMerchantCustomerId('THE-NUMBER-OR-ID-OF-THE-CUSTOMER');

/** @var \Billie\Sdk\Model\Response\CreateSessionResponseModel $responseModel */
$responseModel = $requestService->execute($requestModel);

$checkoutSessionId = $responseModel->getCheckoutSessionId(); // use this session ID and submit it to the widget.

CheckoutSessionConfirmRequest

如果用户已确认支付（通过小部件），您可以确认订单。

它将在网关上最终创建一个订单。

注意：请查看每个模型，以确定哪些字段需要提交。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\CheckoutSession\CheckoutSessionConfirmRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\CheckoutSession\CheckoutSessionConfirmRequestModel();
$requestModel
  ->setSessionUuid('CHECKOUT-SESSION-ID')
  ->setCompany(new \Billie\Sdk\Model\Request\CheckoutSession\Confirm\Debtor())
  ->setAmount(new \Billie\Sdk\Model\Amount())
  ->setDuration(14)
  ->setDeliveryAddress(new \Billie\Sdk\Model\Address());
  
/** @var \Billie\Sdk\Model\Order $responseModel */
$responseModel = $requestService->execute($requestModel); // this is the finally created order

GetCheckoutAuthorizationRequest

使用此服务获取当前授权结账会话的详细信息。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\CheckoutSession\GetCheckoutAuthorizationRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\CheckoutSession\GetCheckoutAuthorizationRequestModel();
$requestModel
  ->setSessionUuid('CHECKOUT-SESSION-ID');
  
/** @var \Billie\Sdk\Model\Response\CheckoutSession\GetCheckoutAuthorizationResponseModel $responseModel */
$responseModel = $requestService->execute($requestModel);

CreateOrderRequest

此请求仅应在卖家手动创建订单时（电话、api等）使用

它将创建一个新订单，初始状态为已创建，不显示确认小部件。

注意：请查看每个模型，以确定哪些字段需要提交。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Order\CreateOrderRequest($billieClient);

$requestModel = new \Billie\Sdk\Model\Request\Order\CreateOrderRequestModel();
$requestModel
    ->setAmount(new \Billie\Sdk\Model\Amount())
    ->setDuration(12)
    ->setDebtor(new \Billie\Sdk\Model\Request\Order\CreateOrder\Debtor())
    ->setPerson(new \Billie\Sdk\Model\Person())
    ->setComment('order comment')
    ->setExternalCode('merchant-order-number')
    ->setDeliveryAddress(new \Billie\Sdk\Model\Address())
    ->setLineItems([
        new \Billie\Sdk\Model\LineItem(),
        new \Billie\Sdk\Model\LineItem(),
    ])
    
/** @var \Billie\Sdk\Model\Order $responseModel */
$responseModel = $requestService->execute($requestModel); // this is the finally created order

此服务将抛出以下异常，这些异常应由集成处理

Billie\Sdk\Exception\OrderDecline\DebtorLimitExceededException - 债务人限制已超过。
Billie\Sdk\Exception\OrderDecline\DebtorNotIdentifiedException - 网关无法识别债务人
Billie\Sdk\Exception\OrderDecline\InvalidDebtorAddressException - 网关无法验证地址
Billie\Sdk\Exception\OrderDecline\RiskPolicyDeclinedException - 订单因风险原因被拒绝
Billie\Sdk\Exception\OrderDecline\OrderDeclinedException - 由于其他原因订单被拒绝

UpdateOrderRequest

使用此订单，更新有关订单的信息。请查看API文档，了解哪些字段可更新。请还查看每个模型，以了解此SDK可以处理哪些字段。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Order\UpdateOrderRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\Order\UpdateOrderRequestModel('REFERENCE-ID');
$requestModel
  ->setExternalCode('SHOP-ORDER-NUMBER')
  ->setAmount(new \Billie\Sdk\Model\Amount());
  
/** @var true $success */
$success = $requestService->execute($requestModel); // true if successful

GetOrderRequest

使用此服务检索所有订单信息

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Order\GetOrderRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\OrderRequestModel('REFERENCE-ID');

/** @var \Billie\Sdk\Model\Order $responseModel */
$responseModel = $requestService->execute($requestModel);

CreateInvoiceRequest

使用此服务检索所有订单信息

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\CreateInvoiceRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel();
$requestModel
    ->setOrders(['REFERENCE-ID']) // use this method to set Billie reference-id or merchants order-number
    ->setOrderUuId('REFERENCE-UD') // use this method to set Billie reference-id
    ->setOrderExternalCode('MERCHANT_ORDER_ID') // use this method to set merchants order-number
    // to keep your code clean, only use one of the above methods
    ->setInvoiceNumber('merchant-invoice-number')
    ->setInvoiceUrl('https://public-url.com/to/to/merchant-invoice.pdf')
    ->setAmount(
        (new Amount())
            ->setGross(100)
            ->setTaxRate(19.00)
    )
    // optional parameters:
    ->setLineItems([
        new \Billie\Sdk\Model\Request\Invoice\LineItem('merchant-product-id-2', 1),
        new \Billie\Sdk\Model\Request\Invoice\LineItem('merchant-product-id-1', 2)  
    ])
    ->setShippingInformation(new \Billie\Sdk\Model\ShippingInformation())

/** @var \Billie\Sdk\Model\Response\CreateInvoiceResponseModel $responseModel */
$responseModel = $requestService->execute($requestModel);
$uuid = $responseModel->getUuid(); // uuid of the invoice

GetInvoiceRequest

使用此服务获取发票。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\GetInvoiceRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\InvoiceRequestModel('INVOICE-UUID');

/** @var \Billie\Sdk\Model\Invoice $responseModel */
$responseModel = $requestService->execute($requestModel);

UpdateInvoiceRequest

使用此服务更新发票编号或URL。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\UpdateInvoiceRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\Invoice\UpdateInvoiceRequestModel('INVOICE-REFERENCE-UUID');
$requestModel
    ->setInvoiceNumber('merchant-invoice-number')
    ->setInvoiceUrl('https://public-url.com/to/to/merchant-invoice.pdf');

if ($requestService->execute($requestModel)) {
    // invoice has been updated
}

CancelInvoiceRequest

使用此服务取消发票。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\CancelInvoiceRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\InvoiceRequestModel('INVOICE-REFERENCE-UUID');

if ($requestService->execute($requestModel)) {
    // invoice has been deleted/canceled
}

CreateCreditNoteRequest

使用此服务向发票添加（部分）退款/信用凭证。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\CreateCreditNoteRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\Invoice\CreateCreditNoteRequestModel('INVOICE-UUID', 'MERCHANT/EXTERNAL_CREDIT_NOTE_NUMBER');
$requestModel
    ->setAmount(
        (new Amount())
            ->setGross(100)
            ->setTaxRate(19.00)
    )
    // optional parameters:
    ->setLineItems([
        new \Billie\Sdk\Model\Request\Invoice\LineItem('merchant-product-id-2', 1),
        new \Billie\Sdk\Model\Request\Invoice\LineItem('merchant-product-id-1', 2)  
    ])
    ->setComment('custom comment for refund')

/** @var \Billie\Sdk\Model\Response\CreateInvoiceResponseModel $responseModel */
$responseModel = $requestService->execute($requestModel);
$uuid = $responseModel->getUuid(); // uuid of the invoice

ConfirmPaymentRequest

使用此请求通知网关已收到支付。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Invoice\ConfirmPaymentRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\Invoice\ConfirmPaymentRequestModel('INVOICE-UUID');
$requestModel
    ->setPaidAmount(250);

/** @var true $success */
$success = $requestService->execute($requestModel);

CancelOrderRequest

使用此请求完全取消订单。

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\Order\CancelOrderRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\OrderRequestModel('REFERENCE-ID');

/** @var true $success */
$success = $requestService->execute($requestModel);

GetLegalFormsRequest

使用此请求获取Billie支持的所有法律格式。

注意：此请求始终被缓存。因此，您可以在任何时候使用它而无需对网关发出新请求。缓存将自动刷新。

使用方法

/** @var \Billie\Sdk\HttpClient\BillieClient $billieClient */

$requestService = new \Billie\Sdk\Service\Request\GetLegalFormsRequest($billieClient);
$requestModel = new \Billie\Sdk\Model\Request\GetLegalFormsRequestModel();

/** @var \Billie\Sdk\Model\Response\GetLegalFormsResponseModel $responseModel */
$responseModel = $requestService->execute($requestModel);

注意：请求模型没有内容。请不要混淆。

集成实用工具

AddressHelper

类：\Billie\Util\AddressHelper 使用此类将门牌号从街道名称中分离出来。

使用方法

$streetName = \Billie\Util\AddressHelper::getStreetName('Musterstraße 123'); // will return "Musterstraße"
$houseNumber = \Billie\Util\AddressHelper::getHouseNumber('Musterstraße 123'); // will return "123"

其他功能

自动税额计算

模型：\Billie\Sdk\Model\Amount

该模型有一个名为tax的字段。它包含行项/订单的税额。

为了尽可能简化计算，您可以省略tax参数。因此，您不必提供所有信息。模型将自行计算。

示例 1

$amount = new \Billie\Sdk\Model\Amount();
$amount->setGross(119);
$amount->setNet(100);

$tax = $amount->getTax(); // will return `19`

示例 2

$amount = new \Billie\Sdk\Model\Amount();
$amount->setGross(119);
$amount->setTaxRate(19);

$tax = $amount->getTax(); // will return `19`

示例 3

$amount = new \Billie\Sdk\Model\Amount();
$amount->setNet(100);
$amount->setTaxRate(19);

$tax = $amount->getTax(); // will return `19`
$gross = $amount->getGross(); // will return `119`

示例 4

$amount = new \Billie\Sdk\Model\Amount();
$amount->setGross(119);
$amount->setTaxRate(19);

$tax = $amount->getTax(); // will return `19`
$net = $amount->getNet(); // will return `100`

示例 4（错误用法）

如果您手动设置tax，模型将不会计算值。它将提交您提供的值。

最终结果将是网关会给你一个错误，因为数据无效。

$amount = new \Billie\Sdk\Model\Amount();
$amount->setGross(119);
$amount->setNet(30);
$amount->setTax(40);

$amount->getGross(); // will return `119`
$amount->getNet(); // will return `30`
$amount->getTax(); // will return `40`

Symfony服务

如果你使用基于Symfony的系统，你可以将请求服务作为服务使用。因此，你可以非常容易地注入它。只需在你的services.xml（或yaml）中注册请求服务

<?xml version="1.0" ?>
<container xmlns="https://symfony.com.cn/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://symfony.com.cn/schema/dic/services https://symfony.com.cn/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="Billie\Sdk\Service\Request\CheckoutSession\CreateSessionRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\Order\CancelOrderRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\CheckoutSession\CheckoutSessionConfirmRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\Order\CreateOrderRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\GetLegalFormsRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\GetOrderRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\Order\UpdateOrderRequest" autowire="true"/>
        <service id="Billie\Sdk\Service\Request\ConfirmPaymentRequest" autowire="true"/>
    </services>
</container>

你只需将请求服务注入到你的类中。

示例

<?php
namespace YourNamespace;

class MyClass
{

    /**
     * @var \Billie\Sdk\Service\Request\AbstractRequest
     */
    private $requestService;
    
    public function __construct(\Billie\Sdk\Service\Request\AbstractRequest $requestService) 
    {
        $this->requestService = $requestService;
    }
    
    public function process()
    {
        $response = $this->requestService->execute(...);
    }
}

通过工厂创建BillieClient

不要忘记为你的\Billie\Sdk\HttpClient\BillieClient实例定义一个工厂，以便将客户端注入到请求服务中

<?xml version="1.0" ?>
<container xmlns="https://symfony.com.cn/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://symfony.com.cn/schema/dic/services https://symfony.com.cn/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="YourNamespace\BillieClientFactory"/>
        <service id="Billie\Sdk\HttpClient\BillieClient">
            <factory service="YourNamespace\BillieClientFactory" method="createBillieClient"/>
        </service>
    </services>
</container>

<?php
namespace YourNamespace;

class BillieClientFactory
{
    public function createBillieClient()
    {
        $isSandbox = true;
        return \Billie\Sdk\Util\BillieClientFactory::getBillieClientInstance(
            'YOUR-CLIENT-ID',
            'YOUR-CLIENT-SECRET',
            $isSandbox
        );
    }
}

通过setter提供BillieClient

如果你不能使用工厂创建\Billie\Sdk\HttpClient\BillieClient的实例，你也可以手动将BillieClient设置到请求服务中

/* @var \Billie\Sdk\Service\Request\AbstractRequest $requestService */
$isSandbox = true;
$requestService->setClient(new \Billie\Sdk\HttpClient\BillieClient('YOUR-CLIENT-ID', 'YOUR-CLIENT-SECRET', $isSandbox));

billie / api-php-sdk

维护者

详细信息

README

要求

使用 Composer 安装

使用方法

通用使用

获取 `\Billie\Sdk\HttpClient\BillieClient` 实例

获取请求服务的实例

模型

请求模型：验证

响应模型

请求

GetTokenRequest

ValidateTokenRequest

RevokeTokenRequest

CreateSessionRequest

CheckoutSessionConfirmRequest

GetCheckoutAuthorizationRequest

CreateOrderRequest

UpdateOrderRequest

GetOrderRequest

CreateInvoiceRequest

GetInvoiceRequest

UpdateInvoiceRequest

CancelInvoiceRequest

CreateCreditNoteRequest

ConfirmPaymentRequest

CancelOrderRequest

GetLegalFormsRequest

集成实用工具

AddressHelper

其他功能

自动税额计算

Symfony服务

通过工厂创建BillieClient

通过setter提供BillieClient

billie / api-php-sdk

维护者

详细信息

README

要求

使用 Composer 安装

使用方法

通用使用

获取 \Billie\Sdk\HttpClient\BillieClient 实例

获取请求服务的实例

模型

请求模型：验证

响应模型

请求

GetTokenRequest

ValidateTokenRequest

RevokeTokenRequest

CreateSessionRequest

CheckoutSessionConfirmRequest

GetCheckoutAuthorizationRequest

CreateOrderRequest

UpdateOrderRequest

GetOrderRequest

CreateInvoiceRequest

GetInvoiceRequest

UpdateInvoiceRequest

CancelInvoiceRequest

CreateCreditNoteRequest

ConfirmPaymentRequest

CancelOrderRequest

GetLegalFormsRequest

集成实用工具

AddressHelper

其他功能

自动税额计算

Symfony服务

通过工厂创建BillieClient

通过setter提供BillieClient

获取 `\Billie\Sdk\HttpClient\BillieClient` 实例