README

通用用法

对于每个请求，都有一个

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

获取 \Tilta\Sdk\HttpClient\TiltaClient 实例

使用 \Tilta\Sdk\Util\TiltaClientFactory 获取新实例。

工厂将生成的 TiltaClient 实例存储在静态变量中。因此，如果您请求新的 TiltaClient 实例，它将不会产生新的请求。

$isSandbox = true;
$tiltaClient = \Tilta\Sdk\Util\TiltaClientFactory::getClientInstance('YOUR_TOKEN', $isSandbox);

将布尔值作为第二个参数提供，以定义请求是否针对沙箱。

获取请求服务的实例

您可以直接创建对应服务的新的实例。

示例:

/** @var \Tilta\Sdk\HttpClient\TiltaClient $tiltaClient **/

$requestService = new \Tilta\Sdk\Service\Request\RequestServiceClass($tiltaClient);

您不得通过构造函数提供 TiltaClient，但您应该在调用请求服务的 execute 方法之前设置它。

示例:

/** @var \Tilta\Sdk\HttpClient\TiltaClient $tiltaClient **/

$requestService = new \Tilta\Sdk\Service\Request\RequestServiceClass();
// [...]
$requestService->setClient($tiltaClient);
// [...]
$requestService->execute(...);

模型

请求模型：验证

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

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

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

$requestModel->setValidateOnSet(false);

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

响应模型

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

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

请求

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

请参阅每个 API 请求的相应文档。

GetBuyerAuthTokenRequest

使用此服务为买家生成 JWT 令牌，以便他可以使用买家注册请求。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$tokenRequestService = new \Tilta\Sdk\Service\Request\Buyer\GetBuyerAuthTokenRequest($client);

$requestModel = new \Tilta\Sdk\Model\Request\Buyer\GetBuyerAuthTokenRequestModel('EXTERNAL-MERCHANT-ID');

/** @var \Tilta\Sdk\Model\Response\Buyer\GetBuyerAuthTokenResponseModel */
$responseModel = $tokenRequestService->execute($requestModel);
$accessToken = $responseModel->getBuyerAuthToken();

GetBuyerDetailsRequest

使用此服务通过其外部 ID（商家的 ID）从网关获取买家。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$tokenRequestService = new \Tilta\Sdk\Service\Request\Buyer\GetBuyerDetailsRequest($client);

$requestModel = new \Tilta\Sdk\Model\Request\Buyer\GetBuyerDetailsRequestModel('EXTERNAL-MERCHANT-ID');

/** @var \Tilta\Sdk\Model\Buyer */
$responseModel = $tokenRequestService->execute($requestModel);
$externalId = $responseModel->getExternalId();
$legalName = $responseModel->getLegalName();
[...]

GetBuyerListRequest

使用此服务获取所有买家。使用 limit 和 offset 导航页面。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$tokenRequestService = new \Tilta\Sdk\Service\Request\Buyer\GetBuyerListRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Buyer\GetBuyersListRequestModel())
    // optional parameters
    ->setLimit(10)
    ->setOffset(0);

/** @var \Tilta\Sdk\Model\Response\Buyer\GetBuyersListResponseModel */
$responseModel = $tokenRequestService->execute($requestModel);
$limit = $responseModel->getLimit();
$limit = $responseModel->getOffset();
$limit = $responseModel->getTotal();
/** @var \Tilta\Sdk\Model\Buyer[] $items */
$items = $responseModel->getItems();
$legalNameOfCompany1 = $items[0]->getLegalName();
$legalNameOfCompany2 = $items[1]->getLegalName();
[...]

CreateBuyerRequest

使用此服务创建新的买家。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Buyer\CreateBuyerRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Buyer())
    ->setExternalId('EXTERNAL_MERCHANT_ID')
    ->setTradingName('Trading name')
    ->setLegalForm('DE_GMBH')
    ->setLegalName('Legal name')
    ->setTaxId('DE123456')
    ->setRegisteredAt((new DateTime())->setDate(2000, 2, 12))
    ->setIncorporatedAt((new DateTime())->setDate(2002, 5, 30))
    ->setContactPersons(new \Tilta\Sdk\Model\ContactPerson())
    ->setBusinessAddress(new \Tilta\Sdk\Model\Address())
    ->setCustomData([
        'custom-key' => 'custom-value1',
        'custom-key2' => 'custom-value2'
    ]);

/** @var boolean $response */
$response = $requestService->execute($requestModel); // true if successfully

UpdateBuyerRequest

使用此服务更新买家数据。

您不必提供所有买家数据，只需提供您想要更新的这些数据。如果您想更新子对象（例如 contactPersons 或 businessAddress），您必须提供该子对象的全部数据，以防止验证问题。此行为可能会在未来发生变化。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Buyer\UpdateBuyerRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Buyer\UpdateBuyerRequestModel('EXTERNAL_MERCHANT_ID'))
    // same methods as in the \Tilta\Sdk\Model\Buyer model. You must provide all data, just these data, which should be updated.
    ->setTradingName('Trading name')
    ->setCustomData([
        'custom-key' => 'custom-value1',
        'custom-key2' => 'custom-value2'
    ]);

/** @var boolean $response */
$response = $requestService->execute($requestModel); // true if successfully

CreateFacilityRequest

使用此服务为买家创建新的设施。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Facility\CreateFacilityRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Facility\CreateFacilityRequestModel('EXTERNAL_MERCHANT_ID'));

/** @var boolean $response */
$response = $requestService->execute($requestModel); // true if successfully

GetFacilityRequest

使用此服务获取买家的活动设施。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Facility\GetFacilityRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Facility\GetFacilityRequestModel('EXTERNAL_MERCHANT_ID'));

/** @var \Tilta\Sdk\Model\Response\Facility\GetFacilityResponseModel $response */
$response = $requestService->execute($requestModel);
$response->getBuyerExternalId();
$response->getAvailableAmount();
[...]

服务可能抛出的预期异常

CreateOrderRequest

使用此服务为买家创建新订单。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\CreateOrderRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\CreateOrderRequestModel())
            ->setOrderExternalId('order-external-id')
            ->setBuyerExternalId('buyer-external-id')
            ->setMerchantExternalId('merchant-external-id')
            ->setAmount(new \Tilta\Sdk\Model\Amount())
            ->setComment('order-comment')
            ->setOrderedAt((new DateTime()))
            ->setPaymentMethod(\Tilta\Sdk\Enum\PaymentMethodEnum::TRANSFER)
            ->setPaymentTerm(\Tilta\Sdk\Enum\PaymentTermEnum::BNPL30)
            ->setDeliveryAddress(new \Tilta\Sdk\Model\Address()))
            ->setLineItems([
                new \Tilta\Sdk\Model\Order\LineItem(),
                new \Tilta\Sdk\Model\Order\LineItem(),
                new \Tilta\Sdk\Model\Order\LineItem(),
            ]);

/** @var \Tilta\Sdk\Model\Order $response */
$response = $requestService->execute($requestModel);
$orderStatus = $response->getStatus();
[...]

服务可能抛出的预期异常

GetOrderDetailsRequest

使用此服务通过外部-id获取订单。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\GetOrderDetailsRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\GetOrderDetailsRequestModel('order-external-id'));

/** @var \Tilta\Sdk\Model\Order $response */
$response = $requestService->execute($requestModel);
$externalId = $response->getOrderExternalId();
$orderStatus = $response->getStatus();
[...]

服务可能抛出的预期异常

GetOrderListRequest

使用此服务获取所有订单。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\GetOrderListRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\GetOrderListRequestModel())
    // optional for pagination:
    ->setOffset(150)
    ->setLimit(50)
    // optional search-parameters
    ->setMerchantExternalId('merchant-external-id')
    ->setPaymentMethod(\Tilta\Sdk\Enum\PaymentMethodEnum::TRANSFER)
    ->setPaymentTerm(\Tilta\Sdk\Enum\PaymentTermEnum::BNPL30);

/** @var \Tilta\Sdk\Model\Response\Order\GetOrderListResponseModel $response */
$response = $requestService->execute($requestModel);
$totalItemCount = $response->getTotal();
/** @var Tilta\Sdk\Model\Order[] $items */
$items = $response->getItems();
[...]

CancelOrderRequest

使用此服务取消订单（如果尚未开具发票）。

请注意：如果请求成功，则返回一个订单对象，而不是布尔值！

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\CancelOrderRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\CancelOrderRequestModel('order-external-id'));

/** @var \Tilta\Sdk\Model\Order $response */
$response = $requestService->execute($requestModel);
$externalId = $response->getOrderExternalId();
$response->getStatus() === \Tilta\Sdk\Enum\OrderStatusEnum::CANCELED; // true
[...]

服务可能抛出的预期异常

CancelOrderRequest

使用此服务获取给定买家的所有订单。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\GetOrderListForBuyerRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\GetOrderListForBuyerRequestModel('buyer-external-id'));

/** @var \Tilta\Sdk\Model\Response\Order\GetOrderListForBuyerResponseModel $response */
$response = $requestService->execute($requestModel);
/** @var \Tilta\Sdk\Model\Order[] $items */
$items = $response->getItems();

服务可能抛出的预期异常

GetPaymentTermsRequest

使用此服务获取即将/可能创建的订单的付款条款。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\GetPaymentTermsRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\PaymentTerm\GetPaymentTermsRequestModel())
    ->setMerchantExternalId('merchant-external-id')
    ->setBuyerExternalId('buyer-external-id')
    ->setAmount(new \Tilta\Sdk\Model\Amount());

/** @var \Tilta\Sdk\Model\Response\PaymentTerm\GetPaymentTermsResponseModel $response */
$response = $requestService->execute($requestModel);

服务可能抛出的预期异常

AddOrdersToBuyerRequest

使用此服务将未由Tilta处理的现有订单添加到买家债务方。

请注意： ExistingOrder 模型只是 Order 模型的子类。区别在于，您不能设置订单的 buyerExternalId，因为这个值必须设置在请求模型中（一次）。所以请确保您只提供单一买家的订单。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Order\AddOrdersToBuyerRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Order\AddOrdersToBuyerRequestModel('buyer-external-id'))
    ->setItems([
        new \Tilta\Sdk\Model\Request\Order\AddOrdersToBuyer\ExistingOrder('oder-id-1'),
        new \Tilta\Sdk\Model\Request\Order\AddOrdersToBuyer\ExistingOrder('oder-id-2'),
        new \Tilta\Sdk\Model\Request\Order\AddOrdersToBuyer\ExistingOrder('oder-id-3')
    ])
    ->addOrderItem(new \Tilta\Sdk\Model\Request\Order\AddOrdersToBuyer\ExistingOrder('oder-id-4'));

/** @var \Tilta\Sdk\Model\Response\Order\AddOrdersToBuyerResponseModel $response */
$response = $requestService->execute($requestModel);
/** @var \Tilta\Sdk\Model\Order[] $items */
$items = $response->getItems();

服务可能抛出的预期异常

CreateInvoiceRequest

使用此服务为（多个）订单创建新发票。

请注意：在大多数情况下，invoice_number 与 external_id 相同。 invoice_number 是发票文件上官方打印的号码，而 external_id 是您系统中发票的内部标识符。如果您不想提交单独的号码，也可以将 invoice_number 作为 external_id 提交。

然而，请记住，您在未来的请求中始终必须使用 external_id 作为对发票的引用。所以如果您使用 invoice_number 作为 external_id，您必须将“发票号码”作为 external_id 提交。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Invoice\CreateInvoiceRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel())
    ->setInvoiceExternalId('invoice-external-id')
    ->setInvoiceNumber('invoice-number')
    ->setOrderExternalIds(['order-external-id-1', 'order-external-id-2']) // just provide an array with one value, if you create an invoice for a single order.
    ->setAmount(new \Tilta\Sdk\Model\Amount())
    ->setBillingAddress(new \Tilta\Sdk\Model\Address())
    ->setLineItems([
      new \Tilta\Sdk\Model\Order\LineItem(),
      new \Tilta\Sdk\Model\Order\LineItem(),
      new \Tilta\Sdk\Model\Order\LineItem(),
      new \Tilta\Sdk\Model\Order\LineItem(),
    ]);

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

服务可能抛出的预期异常

GetInvoiceRequest

使用此服务获取单个发票。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Invoice\GetInvoiceRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Invoice\GetInvoiceRequestModel('invoice-external-id'));

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

服务可能抛出的预期异常

GetInvoiceRequest

使用此服务获取所有发票。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Invoice\GetInvoiceListRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\Invoice\GetInvoiceListRequestModel())
    // optional for pagination:
    ->setOffset(150)
    ->setLimit(50)
    ->setMerchantExternalId('merchant-external-id');

/** @var \Tilta\Sdk\Model\Response\Invoice\GetInvoiceListResponseModel $response */
$response = $requestService->execute($requestModel);
$totalItemCount = $response->getTotal();
/** @var \Tilta\Sdk\Model\Invoice[] $items */
$items = $response->getItems();

服务可能抛出的预期异常

CreateCreditNoteRequest

使用此服务为买家创建新信用凭证。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\CreditNote\CreateCreditNoteRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\CreditNote\CreateCreditNoteRequestModel())
    ->setCreditNoteExternalId('credit-note-external-id')
    ->setBuyerExternalId('buyer-external-id')
    ->setInvoicedAt(new DateTime())
    ->setAmount(new \Tilta\Sdk\Model\Amount())
    ->setBillingAddress(new \Tilta\Sdk\Model\Address())
    ->setLineItems([
        new \Tilta\Sdk\Model\Order\LineItem(),
        new \Tilta\Sdk\Model\Order\LineItem(),
        new \Tilta\Sdk\Model\Order\LineItem(),
    ])
    ->setOrderExternalIds(['order-external-id-1', 'order-external-id-2']); // just provide an array with one value, if you create a credit-node for a single order.

/** @var \Tilta\Sdk\Model\CreditNote $response */
$response = $requestService->execute($requestModel);

服务可能抛出的预期异常

CreateSepaMandateRequest

使用此服务列出买家的所有SEPA授权。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\SepaMandate\GetSepaMandateListRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\SepaMandate\GetSepaMandateListRequestModel('buyer-external-id'))
    // optional for pagination:
    ->setOffset(150)
    ->setLimit(50)

/** @var \Tilta\Sdk\Model\Response\SepaMandate\GetSepaMandateListResponseModel $response */
$response = $requestService->execute($requestModel);
/** @var \Tilta\Sdk\Model\Response\SepaMandate[] $items */
$items = $response->getItems()

服务可能抛出的预期异常

GetSepaMandateListRequest

使用此服务为给定买家创建SEPA授权。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\SepaMandate\CreateSepaMandateRequest($client);

$requestModel = (new \Tilta\Sdk\Model\Request\SepaMandate\CreateSepaMandateRequestModel('buyer-external-id'))
    ->setIban('DE123456789987654')

/** @var \Tilta\Sdk\Model\Response\SepaMandate $response */
$response = $requestService->execute($requestModel);
$response->getIban();
$response->getMandateId();

服务可能抛出的预期异常

GetLegalFormsRequest

使用此服务获取给定国家可用的所有法律形式。

用法

/** @var \Tilta\Sdk\HttpClient\TiltaClient $client */
$requestService = new \Tilta\Sdk\Service\Request\Util\GetLegalFormsRequest($client);

// DE = requested country
$requestModel = (new \Tilta\Sdk\Model\Request\Util\GetLegalFormsRequestModel('DE'));

/** @var \Tilta\Sdk\Model\Response\Util\GetLegalFormsResponseModel $response */
$response = $requestService->execute($requestModel);

/* $items would be key-value pairs:
 *  e.g. [
 *      'DE_GMBH' => 'Gesellschaft mit beschränkter Haftung',
 *      'DE_AG' => 'Aktiengesellschaft'
 * ]
 */
$items = $response->getItems();
$response->getDisplayName('DE'); // = Gesellschaft mit beschränkter Haftung

服务可能抛出的预期异常

请注意：此服务将自动处理未知/无效国家代码的错误。它将返回空项目列表。

附加功能

日志记录

您可以启用记录所有API请求。 (也许我们将来也会记录其他内容)。

您只需要提供 \Psr\Log\LoggerInterface 的实例。这可以是流行的 monolog/monolog 包的记录器。

请注意：您只能传递所述接口的记录器。如果您有自定义记录器，您必须实现接口。不要忘记安装包 psr/log。

请注意：在生产环境中不应设置调试记录器，因为这会将所有请求（成功和失败）记录下来。如果您只设置错误处理程序，它将只记录所有失败的请求。

示例

$logFile = '/path/to/your/logfile.log';
$logger = new \Monolog\Logger('name-for-the-logger');

$handlerDebug = new \Monolog\Handler\StreamHandler('/path/to/your/log-file.debug.log', LogLevel::DEBUG);
$logger->pushHandler($handlerDebug);
$handlerError = new \Monolog\Handler\StreamHandler('/path/to/your/log-file.error.log', LogLevel::ERROR);
$logger->pushHandler($handlerError);

\Tilta\Sdk\Util\Logging::setPsr3Logger($logger);
// call this if you want to log the request-headers too
\Tilta\Sdk\Util\Logging::setLogHeaders(true);