SDKs

Ruby SDK

Official Ruby SDK. kintsugi_sdk is published on RubyGems and generated from the same OpenAPI spec that produces this API reference, so it stays in step with the API.

Ruby 3.2 or later. Requests are typed objects from the generated Models namespace, so calls read the same way whichever resource you are working with.

The Ruby SDK covers part of the API today: customers, transactions, exemptions, address validation, tax estimation, and some of nexus and products. See Available resources for the current list. For anything outside it, call the endpoint over HTTP. The Ruby tab on those API reference pages shows the Net::HTTP request to send.

Installation

gem install kintsugi_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 construct the client, and every call that accepts it is authenticated:

require 'kintsugi_sdk'

Models = ::KintsugiSDK::Models
s = ::KintsugiSDK::OpenApiSDK.new(
  security: Models::Shared::Security.new(
    api_key_header: '<YOUR_API_KEY_HERE>'
  )
)

req = Models::Ops::GetCustomerByIdV1CustomersCustomerIdGetRequest.new(
  customer_id: 'cust_abc123'
)
res = s.customers.get(request: req)

unless res.nil?
  # handle response
end

Each operation takes a request object from Models::Ops, named after the operation. Bodies and shared models live in Models::Shared.

A handful of operations take credentials per call rather than per client. The code sample on each API reference page shows a security: argument where that applies, using an operation specific type such as Models::Ops::SearchV1AddressValidationSearchPostSecurity.

Making a request

require 'kintsugi_sdk'

Models = ::KintsugiSDK::Models
s = ::KintsugiSDK::OpenApiSDK.new(
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

req = Models::Shared::CustomerCreate.new(
  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::Shared::CountryCodeEnum::US,
  status: Models::Shared::StatusEnum::ACTIVE
)
res = s.customers.create(request: req)

For the exact call on any endpoint, including its request type, arguments and what comes back, open that endpoint in the API reference and select the Ruby tab.

Error handling

An API error raises Models::Errors::APIError, carrying message, status_code, body and raw_response. Operations also declare their own typed errors, so rescue those first and fall back to the base class:

require 'kintsugi_sdk'

Models = ::KintsugiSDK::Models
s = ::KintsugiSDK::OpenApiSDK.new(
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

begin
  req = Models::Ops::GetCustomerByIdV1CustomersCustomerIdGetRequest.new(
    customer_id: 'cust_abc123'
  )
  res = s.customers.get(request: req)

  unless res.nil?
    # handle response
  end
rescue Models::Errors::ErrorResponse => e
  # Typed API error
  raise e
rescue Models::Errors::APIError => e
  # Any other HTTP error response
  puts "#{e.status_code} #{e.body}"
end

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

Debug logging

Pass debug_logging: true to log the full request and response while you are getting an integration working:

s = ::KintsugiSDK::OpenApiSDK.new(
  debug_logging: true,
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

Debug output includes request headers and bodies. Keep it off in production so API keys and customer data never reach your logs.

Overriding the server URL

s = ::KintsugiSDK::OpenApiSDK.new(
  server_url: 'https://api.trykintsugi.com',
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

Available resources

AddressValidation   search, suggestions
Customers           list, create, get, update, get_by_external_id,
                    get_transactions, create_transaction
Exemptions          list, create, get, upload_certificate, get_attachments
Nexus               list
Products            get, update
TaxEstimation       estimate_tax
Transactions        list, create, get_by_external_id, update, get_by_id,
                    get_by_filing_id

Ruby SDK repository

Source, per-method docs, releases and issues

API reference

Every endpoint, with a Ruby sample on each page