Python SDK

Python 3.10 or later. Every method carries full type hints and comes in both a synchronous and an asynchronous form, so the SDK fits a script and a high throughput service equally well.

Installation

pip install kintsugi-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), pass it once when you build the client, and every call that accepts it is authenticated:

from kintsugi_tax_platform_sdk import SDK, models

with SDK(
    security=models.Security(
        api_key_header="<YOUR_API_KEY_HERE>",
    ),
) as sdk:

    res = sdk.customers.get(customer_id="cust_abc123")

    # Handle response
    print(res)

The client is a context manager, so with releases the underlying HTTP connection when the block ends. Keeping a long lived client is also fine: call sdk.close() when you are finished with it.

Making a request

Request bodies are keyword arguments, and every enum has a generated type, so misspelled fields and invalid values fail in your editor rather than in production:

from kintsugi_tax_platform_sdk import SDK, models

with SDK(
    security=models.Security(api_key_header="<YOUR_API_KEY_HERE>"),
) as sdk:

    res = sdk.customers.create(
        name="Jane Smith",
        email="jane.smith@example.com",
        external_id="cust_002",
        street_1="456 Elm St",
        city="Metropolis",
        state="NY",
        postal_code="10001",
        country=models.CountryCodeEnum.US,
        status=models.StatusEnum.ACTIVE,
    )

    print(res)

For the exact call on any endpoint, including arguments, enums and the type it returns, open that endpoint in the API reference and select the Python tab.

Async

Every method has an _async counterpart, so calls can run concurrently without tying up a thread:

import asyncio
from kintsugi_tax_platform_sdk import SDK, models

async def main():
    async with SDK(
        security=models.Security(api_key_header="<YOUR_API_KEY_HERE>"),
    ) as sdk:
        res = await sdk.customers.get_async(customer_id="cust_abc123")
        print(res)

asyncio.run(main())

Error handling

errors.SDKError is the base class for HTTP error responses. It carries message, status_code, headers, body and raw_response, and some errors also carry parsed data:

from kintsugi_tax_platform_sdk import SDK, errors, models

with SDK(
    security=models.Security(api_key_header="<YOUR_API_KEY_HERE>"),
) as sdk:
    try:
        res = sdk.customers.get(customer_id="cust_abc123")
        print(res)

    except errors.SDKError as e:
        print(e.status_code)
        print(e.message)
        print(e.body)

        if isinstance(e, errors.ErrorResponse):
            print(e.data.detail)

Operations declare their own error types for validation failures, such as errors.BackendSrcCustomersResponsesValidationErrorResponse for a 422. Each method's error table is in the SDK's docs, and network failures surface as the underlying httpx exceptions.

Error handling covers what the API returns and when a retry is worthwhile.

Retries

Transient failures are retried with backoff. Configure it per call, or once for the whole client:

from kintsugi_tax_platform_sdk import SDK, models
from kintsugi_tax_platform_sdk.utils import BackoffStrategy, RetryConfig

with SDK(
    security=models.Security(api_key_header="<YOUR_API_KEY_HERE>"),
    retry_config=RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False),
) as sdk:

    res = sdk.customers.list(page=1, size=50)
    print(res)

Overriding the server URL

from kintsugi_tax_platform_sdk import SDK, models

with SDK(
    server_url="https://api.trykintsugi.com",
    security=models.Security(api_key_header="<YOUR_API_KEY_HERE>"),
) as sdk:
    ...

Available resources

AddressValidation   search, suggestions
Customers           list, create, get, update, get_by_external_id,
                    get_transactions, create_transaction
Exemptions          list, create, get, upload_certificate, list_attachments
Filings             get_all, get, get_by_registration_id
Nexus               get_physical, create_physical, update_physical_nexus,
                    delete_physical_nexus, get_all
Products            get_products_v1_products_get, create_product_v1_products_post,
                    get_product_categories_v1_products_categories_get,
                    retrieve, update
Registrations       get_all, create, get, update, deregister
TaxEstimation       estimate
Transactions        list, create, get_by_external_id, update, get_by_id,
                    get_by_filing_id, create_credit_note, update_credit_note