Integration playbook

The short list of things that will save you time, distilled from the integrator journey. If you read only one page beyond the quickstart, read this and Deviations.

Build in this order

1. Wire GET /health into your smoke test; pull public/openapi.json for discovery.
2. Get one credential working end-to-end (key or OAuth) before touching products.
3. Confirm a category resolves by doing a real create, don't trust hint lists.
4. Drive the full happy path once by hand, then codify it. Capture productId and passportUid only from documented response fields.
5. Subscribe to webhooks before you build polling, most state you want is pushed.

Idempotency

• Generate one Idempotency-Key (uuid) per logical operation and reuse it on retries.
• Required on publish-dpp and oauth/token; recommended everywhere else.
• Same key + different body → typed conflict. Never recycle a key across different operations.
• Telling a replay from a fresh execution: a response served from a previously completed execution carries the header Idempotency-Status: replayed. The header is absent on a first execution: absence means fresh, and replayed is the only value ever sent. This covers both replay layers on the AIDC surface: the shared Idempotency-Key cache, and the job routes that replay from job state (those also keep their replayed body field). The legacy X-Idempotency-Hit: true header still accompanies cache replays; prefer Idempotency-Status in new integrations.

Correlation & debugging

Attach X-Correlation-Id to every request from day one. It shows up in audit-logs as requestId and ties your call to metrics, it is the fastest way to answer "what happened to my request?".

Versioning, pagination & limits

Sandbox safety

Run everything in sandbox first: no anchoring, no production email, no registry submission, no billing. Treat full isolation as the design contract and verify anything safety-critical yourself while guards are hardened.