SDK Integration Checklist

Use this checklist to build SDKs or integrations that are consistent across services.

1) Base setup

• Use the custom domain: https://api.g3nretailstack.com/<service>/....
• Always capture and log stats.request_id and stats.build.build_id from responses.
• Read the Common contract before service-specific surfaces.
  • /common/
• Integration checklist (end-to-end): /common/integration-checklist.html

2) Auth and identity placement

• Human auth: x-session-guid header (bearer secret).
• Service auth: x-api-key header (bearer secret).
• Tenancy: x-orgcode header when required by a service.
• Cost attribution: x-cccode header or cccode in body where documented.
• Use the header + identity cheat sheet: /common/headers-identity.html.
• Prefer a single request context object (service + session/apiKey + orgcode/cccode) and let the client shim fan out placement per service.

3) Request semantics (no surprises)

• GET: query params only, no JSON body.
• POST: JSON body for inputs; headers for auth/tenancy (body auth only where documented).
• Canonical per-service patterns: /common/request-builders.html.
• Method guidance: /common/http-methods.html.

4) Retry + idempotency posture

• Default safe retries: GET/list/head only.
• Mutations require expected_revision; handle 409 and 428 by re-reading.
• Use idempotency keys where supported (e.g., MRS idempotency_key).
• See: /common/idempotency-retry.html and /common/rate-limit-timeouts.html.

5) Error handling (anti-enumeration)

• 404 is ambiguous (not found OR not associated). Use the troubleshooting flow.
• 403 org-write-blocked means the org is not verified (or parked/suspended/doomed).
• 409/428 means your local state is stale.
• See: /common/troubleshooting.html.

6) Minimum viable flow

• Follow the minimum viable flow before building deeper integrations:
  • /common/minimum-viable-flow.html
  • Collections: /common/collections/g3nretailstack-minimum-viable-flow.postman_collection.json
  • SDK snippets: /common/sdk-snippets.html

7) MRS presign correctness

• Presign uploads require gzip payloads.
• content_md5 must be the hex MD5 of the gzipped bytes.
• Helpers: /common/snippets/mrs-gzip-md5-node.js and /common/snippets/mrs-gzip-md5-python.py.

8) Client shim (optional but recommended)

• Use the thin client shim to normalize header placement + retry posture.
• Page: /common/client-shim.html

9) Versioning + stability

• Treat docs build IDs as compatibility markers.
• If your SDK depends on a specific behavior, pin the doc build ID you validated against.