PHP SDK

PHP 8.2 or later. Requests and responses are typed objects built with named arguments, which keeps calls readable and lets static analysis do its job.

Installation

composer require "kintsugi-tax/tax-platform-sdk"

Authentication

The API authenticates with an API key header. Create a key in the Kintsugi app (see Creating and managing API keys), set it once on the builder, and every call that accepts it is authenticated:

declare(strict_types=1);

require 'vendor/autoload.php';

use KintsugiTax\SDK;
use KintsugiTax\SDK\Models\Components;

$sdk = SDK\SDK::builder()
    ->setSecurity(
        new Components\Security(
            apiKeyHeader: '<YOUR_API_KEY_HERE>',
        )
    )
    ->build();

$response = $sdk->customers->getById(
    customerId: 'cust_abc123'
);

if ($response->customerRead !== null) {
    // handle response
}

Response properties are nullable, so a missing body is a null check rather than an exception.

Making a request

Request bodies are component objects, and enums are generated cases, so a typo surfaces before the request leaves your process:

declare(strict_types=1);

require 'vendor/autoload.php';

use KintsugiTax\SDK;
use KintsugiTax\SDK\Models\Components;

$sdk = SDK\SDK::builder()
    ->setSecurity(
        new Components\Security(
            apiKeyHeader: getenv('KINTSUGI_API_KEY'),
        )
    )
    ->build();

$request = new Components\CustomerCreate(
    name: 'Jane Smith',
    email: 'jane.smith@example.com',
    externalId: 'cust_002',
    street1: '456 Elm St',
    city: 'Metropolis',
    state: 'NY',
    postalCode: '10001',
    country: Components\CountryCodeEnum::Us,
    status: Components\StatusEnum::Active,
);

$response = $sdk->customers->create(
    request: $request
);

For the exact call on any endpoint, including its component type, arguments and the property the response arrives on, open that endpoint in the API reference and select the PHP tab.

Error handling

An API error throws Errors\APIException, carrying $message, $statusCode, $body and $rawResponse. Operations also declare their own typed exceptions:

declare(strict_types=1);

require 'vendor/autoload.php';

use KintsugiTax\SDK;
use KintsugiTax\SDK\Models\Errors;

try {
    $response = $sdk->customers->getById(
        customerId: 'cust_abc123'
    );

    if ($response->customerRead !== null) {
        // handle response
    }
} catch (Errors\ErrorResponseThrowable $e) {
    // Typed API error
    echo $e->getMessage();
} catch (Errors\APIException $e) {
    // Any other HTTP error response
    echo $e->statusCode . ' ' . $e->body;
}

Each method's exception table is in the SDK's docs. Error handling covers what the API returns and when a retry is worthwhile.

Overriding the server URL

$sdk = SDK\SDK::builder()
    ->setServerURL('https://api.trykintsugi.com')
    ->setSecurity(
        new Components\Security(
            apiKeyHeader: getenv('KINTSUGI_API_KEY'),
        )
    )
    ->build();

Available resources

AddressValidation       search, suggestions
Customers               list, create, getById, update, getByExternalId,
                        getTransactions, createTransaction
Exemptions              list, create, getById, uploadCertificate
Exemptions.Attachments  get
Filings                 get, getById, getByRegistrationId
Nexus                   listPhysical, createPhysical, updatePhysical,
                        delete, list
Products                getProductsV1ProductsGet, createProductV1ProductsPost,
                        getProductCategoriesV1ProductsCategoriesGet, get, update
Registrations           list, create, getById, update, deregister
TaxEstimation           estimate
Transactions            list, create, getByExternalId, update, get,
                        getByFilingId, createCreditNote, updateCreditNote