tilta-io/tilta-php-sdk

SDK PHP for Tilta API

2.0.0 2024-11-28 14:36 UTC

Requires

• php: ^8.1
• 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

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

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

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

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')
    ->setRegisteredAt((new DateTime())->setDate(2000, 2, 12))
    ->setIncorporatedAt((new DateTime())->setDate(2002, 5, 30))
    ->setContactPersons(new \Tilta\Sdk\Model\ContactPerson())
    ->setBusinessIdentifiers([
        new \Tilta\Sdk\Model\Buyer\BusinessIdentifier()
    ])
    ->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

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

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

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

CreateOrderRequest

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

GetOrderDetailsRequest

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

GetOrderListRequest

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

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

CancelOrderRequest

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

GetPaymentTermsRequest

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

AddOrdersToBuyerRequest

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

CreateInvoiceRequest

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

GetInvoiceRequest

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

GetInvoiceRequestModel

Use this service to fetch all invoices. Optional: You can filter by the buyer-id

Usage

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

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

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

CreateCreditNoteRequest

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

CreateSepaMandateRequest

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

GetSepaMandateListRequest

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

GetLegalFormsRequest

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