tilta-io/tilta-php-sdk

SDK PHP for Tilta API

1.0.0 2023-12-12 10:49 UTC

Requires

• php: ^7.4 || ^8.0
• ext-curl: *
• ext-json: *
• ext-mbstring: *

Requires (Dev)

• jasny/phpdoc-parser: ^1.0
• monolog/monolog: >=2.9
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.6
• ramsey/uuid: ^3.9 || ^4.7
• rector/rector: ^0.17
• symplify/easy-coding-standard: 11.3.*

Suggests

• psr/log: If a PSR-3 Logger is installed, you can enable logging for all tilta api requests. You can use all loggers which also implement PSR-3. e.g. monolog/monolog

MIT

• Tilta Fintech GmbH
• WEBiDEA

README

General usage

For every request there is a

• request service (instance of \Tilta\Sdk\Service\Request\AbstractRequest) Knows anything about the request itself (url, method, authorization)
• request model (instance of \Tilta\Sdk\Model\Response\AbstractRequestModel) Knows anything about the parameters of the request, and acts as DTO to submit the data to the request service
• response model (instance of \Tilta\Sdk\Model\Response\AbstractResponseModel) Knows anything about the response data, and acts as DTO to receives the data from the request service Note: in some cases there is not response. Just a true got returned from the RequestService if the request was successful.

Get a \Tilta\Sdk\HttpClient\TiltaClient-instance

Use the \Tilta\Sdk\Util\TiltaClientFactory to get a new instance.

The factory will store the generated TiltaClient-instance in a static variable. So it will not produce a new request, if you request a new TiltaClient-instance.

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

Provide a boolean as second parameter to define if the request goes against the sandbox or not.

Get an instance of a request service

You can simply create a new instance of the corresponding service.

Example:

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

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

You must not provide the TiltaClient via the constructor, but you should set it, before calling execute on the request service.

Example:

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

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

Models

Request models: Validation

Every field of a request model (not response models) will be validated automatically, during calling its setter. If you provide a wrong value or in an invalid format, an \Tilta\Sdk\Exception\Validation\InvalidFieldException will be thrown.

You can disable this automatic validation, by calling the method setValidateOnSet on the model:

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

$requestModel->setValidateOnSet(false);

The model got validate at least by the request service, to make sure that all data has been provided, and you will get no validation exception through the gateway.

Response models

Every response model is set to be read-only.

You can not set any fields on this model. You will get a BadMethodCallException.

Requests

This documentation should not explain the whole usage of each request. It should only show the main information about each request, and the main usage.

Please have a look into the corresponding documentation of each API Request.

GetBuyerAuthTokenRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Buyer\GetBuyerAuthTokenRequest
Request model	\Tilta\Sdk\Model\Request\Buyer\GetBuyerAuthTokenRequestModel
Response model	\Tilta\Sdk\Model\Response\Buyer\GetBuyerAuthTokenResponseModel

Use this service to generate JWT token for the buyer, so he can use the buyer-onboarding requests.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Buyer\GetBuyerDetailsRequest
Request model	\Tilta\Sdk\Model\Request\Buyer\GetBuyerDetailsRequestModel
Response model	\Tilta\Sdk\Model\Buyer

Use this service to fetch a buyer from the gateway by its external-id (of the merchant)

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Buyer\GetBuyerListRequest
Request model	\Tilta\Sdk\Model\Request\Buyer\GetBuyersListRequestModel
Response model	\Tilta\Sdk\Model\Response\Buyer\GetBuyersListResponseModel

Use this service to get all buyers. Use limit & offset to navigate through the pages.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Buyer\CreateBuyerRequest
Request model	\Tilta\Sdk\Model\Buyer
Response model	true

Use this service to create a new buyer.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Buyer\UpdateBuyerRequest
Request model	\Tilta\Sdk\Model\Request\Buyer\UpdateBuyerRequestModel
Response model	true

Use this service to update buyers data.

You must not provide all buyers data, just these data, which you want to update. If you want to update a sub-object ( e.g. contactPersons or businessAddress), you have to provide all data (of the sub-object), to prevent validation issues. This behaviour may change in the future.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Facility\CreateFacilityRequest
Request model	\Tilta\Sdk\Model\Request\Facility\CreateFacilityRequestModel
Response model	true

Use this service to create a new facility for a buyer.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Facility\GetFacilityRequest
Request model	\Tilta\Sdk\Model\Request\Facility\GetFacilityRequestModel
Response model	\Tilta\Sdk\Model\Response\Facility\GetFacilityResponseModel

Use this service to get the active facility for a buyer.

Usage

/** @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();
[...]

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\Facility\NoActiveFacilityFoundException	if the buyer does not have an active facility
Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the buyer does not exist.

CreateOrderRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\CreateOrderRequest
Request model	\Tilta\Sdk\Model\Request\Order\CreateOrderRequestModel
Response model	\Tilta\Sdk\Model\Order

Use this service to create a new order for a buyer.

Usage

/** @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();
[...]

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the buyer does not exist.
\Tilta\Sdk\Exception\GatewayException\Facility\NoActiveFacilityFoundException	if the buyer does not have an active facility.
\Tilta\Sdk\Exception\GatewayException\Facility\FacilityExceededException	if the buyer have an active facility but the order would exceed the limit.
\Tilta\Sdk\Exception\GatewayException\NotFoundException\MerchantNotFoundException	if the provided merchant does not exist.

GetOrderDetailsRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\GetOrderDetailsRequest
Request model	\Tilta\Sdk\Model\Request\Order\GetOrderDetailsRequestModel
Response model	\Tilta\Sdk\Model\Order

Use this service to fetch order by the external-id.

Usage

/** @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();
[...]

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\OrderNotFoundException	if the order does not exist.

GetOrderListRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\GetOrderListRequest
Request model	\Tilta\Sdk\Model\Request\Order\GetOrderListRequestModel
Response model	\Tilta\Sdk\Model\Response\Order\GetOrderListResponseModel

Use this service to fetch all orders.

Usage

/** @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

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\CancelOrderRequest
Request model	\Tilta\Sdk\Model\Request\Order\CancelOrderRequestModel
Response model	\Tilta\Sdk\Model\Order

Use this service to cancel the order (if it hasn't been invoiced yet).

Please note: If the request was successful, an order-object is returned, instead of a boolean!

Usage

/** @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
[...]

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\OrderNotFoundException	if the order does not exist.
\Tilta\Sdk\Exception\GatewayException\NotFoundException\OrderIsCanceledException	if the order has been already canceled.

CancelOrderRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\GetOrderListForBuyerRequest
Request model	\Tilta\Sdk\Model\Request\Order\GetOrderListForBuyerRequestModel
Response model	\Tilta\Sdk\Model\Response\Order\GetOrderListForBuyerResponseModel

Use this service to fetch all orders for given buyer.

Usage

/** @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();

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.

GetPaymentTermsRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\PaymentTerm\GetPaymentTermsRequest
Request model	\Tilta\Sdk\Model\Request\PaymentTerm\GetPaymentTermsRequestModel
Response model	\Tilta\Sdk\Model\Response\PaymentTerm\GetPaymentTermsResponseModel

Use this service to get the payment terms for an order, which would/may be placed.

Usage

/** @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);

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.
\Tilta\Sdk\Exception\GatewayException\NotFoundException\MerchantNotFoundException	if the given merchant does not exist.
\Tilta\Sdk\Exception\GatewayException\Facility\FacilityExceededException	if the buyer have an active facility but the order would exceed the limit.

AddOrdersToBuyerRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Order\AddOrdersToBuyerRequest
Request model	\Tilta\Sdk\Model\Request\Order\AddOrdersToBuyerRequestModel
Response model	\Tilta\Sdk\Model\Response\Order\AddOrdersToBuyerResponseModel

Use this service to add existing orders, which are not processed by Tilta, to the buyer debtor.

Please note: The ExistingOrder-Model is just a subclass of the Order-Model. The difference is, that you can not set the buyerExternalId for the order, because this value has to be set on the request-model (once). So please make sure that you only provide orders, for one single buyer.

Usage

/** @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();

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.
\Tilta\Sdk\Exception\GatewayException\NotFoundException\MerchantNotFoundException	if the given merchant for at least one order does not exist.

CreateInvoiceRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Invoice\CreateInvoiceRequest
Request model	\Tilta\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel
Response model	\Tilta\Sdk\Model\Invoice

Use this service to create a new invoice for (multiple) orders.

Please note: In most cases, the invoice_number is the same as the external_id. The invoice_number is the official printed number on the invoice document, while the external_id is the internal identifier of the invoice in your system. You may submit the invoice_number as the external_id as well if you don't want to submit a separate number.

However, please remember that you always have to use the external_id in future requests as reference to the invoice. So if you are using the invoice_number as the external_id, you have to submit the "invoice number" as the external_id.

Usage

/** @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);

Expected exceptions thrown by service

TODO	TODO
TODO	TODO

GetInvoiceRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Invoice\CreateInvoiceRequest
Request model	\Tilta\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel
Response model	\Tilta\Sdk\Model\Invoice

Use this service to fetch a single invoice.

Usage

/** @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);

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\InvoiceNotFoundException	if the invoice does not exist.

GetInvoiceRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Invoice\CreateInvoiceRequest
Request model	\Tilta\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel
Response model	\Tilta\Sdk\Model\Response\Invoice\GetInvoiceListResponseModel

Use this service to fetch all invoices.

Usage

/** @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();

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\MerchantNotFoundException	if the given merchant does not exist.

CreateCreditNoteRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\CreditNote\CreateCreditNoteRequest
Request model	\Tilta\Sdk\Model\Request\CreditNote\CreateCreditNoteRequestModel
Response model	\Tilta\Sdk\Model\CreditNote

Use this service to create a new credit note for a buyer

Usage

/** @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);

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.
\Tilta\Sdk\Exception\GatewayException\InvoiceForCreditNoteNotFound	if order(s) got not found or order(s) does not have an invoice.

CreateSepaMandateRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\SepaMandate\GetSepaMandateListRequest
Request model	\Tilta\Sdk\Model\Request\SepaMandate\GetSepaMandateListRequestModel
Response model	\Tilta\Sdk\Model\Response\SepaMandate\GetSepaMandateListResponseModel

Use this service to list all sepa mandates of a buyer.

Usage

/** @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()

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.
\Tilta\Sdk\Exception\GatewayException\SepaMandate\DuplicateSepaMandateException	if a SEPA mandate with the same Iban does already exist
\Tilta\Sdk\Exception\GatewayException\SepaMandate\InvalidIbanException	if the iban is not valid

GetSepaMandateListRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\SepaMandate\CreateSepaMandateRequest
Request model	\Tilta\Sdk\Model\Request\SepaMandate\CreateSepaMandateRequestModel
Response model	\Tilta\Sdk\Model\Response\SepaMandate

Use this service to create a SEPA mandate for the given buyer

Usage

/** @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();

Expected exceptions thrown by service

\Tilta\Sdk\Exception\GatewayException\NotFoundException\BuyerNotFoundException	if the given buyer does not exist.

GetLegalFormsRequest

Api documentation	Link
Request service	\Tilta\Sdk\Service\Request\Util\GetLegalFormsRequest
Request model	\Tilta\Sdk\Model\Request\Util\GetLegalFormsRequestModel
Response model	\Tilta\Sdk\Model\Response\Util\GetLegalFormsResponseModel

Use this service to fetch all legal forms, which would be available for given country.

Usage

/** @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

Expected exceptions thrown by service

Please note: This service will handle automatically the error if the country code is unknown/invalid. It will return empty item-list.

Additional features

Logging

you can enable logging all API Requests. (maybe we will log other things in the future, too).

You just have to give us an instance of \Psr\Log\LoggerInterface. This could be a logger of the popular monolog/monolog package.

Please note, you can only pass a logger of the mentioned interface. If you have a custom logger, you have to implement the interface. Do not forget to install the package psr/log.

Please note: you should not set a debug-logger in production, because this will log all requests (successful and failed). If you only set a ERROR-Handler it will only log all failed requests.

Example:

$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);