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.

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.