Overview

Quatlas Integration API v1

Create shipment requests from your own systems, update and cancel the requests created through the API where the app’s rules allow, keep your own metadata on them, and follow them; read the deals your company is a party to (the deal, its documents, its operation and its costs, as your company sees them in the app) and upload documents to them; and hear about what happens through signed webhooks (see the webhooks section). Authenticate every call with your company’s integration key, ‘Authorization: Bearer qk_…’, or, where your security policy wants a short-lived credential, with an access token from POST /api/integrations/v1/oauth/token (OAuth 2.0 client credentials: the client id is the key’s prefix, the secret is the key; tokens live 15 minutes and die with the key). A key acts as its integration’s own service identity, limited to its scopes (requests:read, requests:write, deals:read, tracking:read, documents:read, documents:write, costs:read), to its company’s calls a minute per key (60 on Exchange, 300 on Enterprise by default), and to its IP allowlist when it has one; every key expires within 12 months and can be rotated. A test key (qk_test_…) works the same way against a sandbox of your own and never touches real data: its answers say livemode: false. Send an X-Idempotency-Key header with every write (create, update, cancel, upload); repeat the same key to retry safely. Reads of a request carry an ETag; send it as If-Match on an update or a cancel to refuse the write (412) if the request changed in between. Webhooks: Every delivery is a POST with a JSON body and four headers: Quatlas-Event-Id (the event’s id; dedupe on it, a delivery can arrive more than once), Quatlas-Event-Type, Quatlas-Timestamp (Unix seconds) and Quatlas-Signature: v1=, the lowercase hex HMAC-SHA256 of “.” keyed with your subscription’s signing secret (whsec_…). During a secret rotation the header carries one v1= value per valid secret, comma-separated; accept the delivery when any one matches. Compute the HMAC over the raw bytes you received, compare in constant time, and refuse a timestamp more than 5 minutes from your clock (replay). Answer any 2xx within 10 seconds to acknowledge; anything else, a redirect included, is retried after 1 minute, 5, 30, 2 hours, 6 and 12. After 20 failures in a row the subscription is switched off. Bodies are thin on purpose: fetch the details through the read API with your key’s scopes.

Information

OpenAPI version: 3.1.1

Authentication

IntegrationClient

The token endpoint’s client authentication (client_secret_basic): the key’s prefix as the user name and the key as the password. Or send client_id and client_secret in the form (client_secret_post), never both.

Security scheme type: http

IntegrationKey

Your company’s integration key (qk_… or, for the sandbox, qk_test_…), or an access token the token endpoint issued for it. Send as ‘Authorization: Bearer …’.

Security scheme type: http

IntegrationOAuth

OAuth 2.0 client credentials. Access tokens live 15 minutes; revoking the key refuses them at once.

Security scheme type: oauth2

Flow type: clientCredentials

Token URL: /api/integrations/v1/oauth/token

Scopes:

costs:read - Read a deal's additional costs and statement totals.
deals:read - Read the deals your company is a party to.
documents:read - List a deal's documents and download clean ones.
documents:write - Upload documents to the deals your company is a party to, under the app's upload rules.
requests:read - Read your shipment requests' status.
requests:write - Create, update and cancel your shipment requests.
tracking:read - Read a deal's milestones, planned and current ETA and delivery.