# Order Source Certification Checklist Record each item as `CONFORMANT`, `NON-CONFORMANT`, `NOT IMPLEMENTED`, `NOT APPLICABLE`, or `NOT VERIFIED`, with a one-line note of the evidence (a request/response pair, log line, or screenshot — sanitized, no real credentials or customer data). `certification/certify.py` automates the items marked **(auto)** and writes a machine-readable result file; everything else is verified by manual inspection of your own integration. ## 1. Authentication and isolation - [ ] A request with a valid `X-Api-Key` succeeds. **(auto)** - [ ] A request with a missing `X-Api-Key` returns `401` with an empty body. **(auto)** - [ ] A request with a malformed/unknown `X-Api-Key` returns `401` with an empty body. **(auto)** - [ ] The raw API key and webhook secret are never logged or written to disk in plaintext by your integration. - [ ] Staging and production credentials are stored in clearly separate configuration. ## 2. Create and idempotency - [ ] A minimal valid Create request returns `201` with the documented response shape. **(auto)** - [ ] A full Create request (every optional field populated) returns `201`. **(auto)** - [ ] Replaying the same `Idempotency-Key` with the identical body returns the same `platformOrderId`. **(auto)** - [ ] Replaying the same `Idempotency-Key` with a **different** body still returns the original, unchanged order — your integration does not assume a conflict error exists. **(auto)** - [ ] Omitting `Idempotency-Key` and reusing the same `externalOrderId` also resolves to the original order. **(auto)** - [ ] An invalid Create (bad coordinates, bad enum, missing required field) returns the documented `400` + `errorCode`, and your integration surfaces `errorCode`/`detail` usefully rather than a generic failure. **(auto, several cases)** ## 3. Update, status, tracking, cancel, return - [ ] Update with a partial body only changes the fields sent (Section 11.1 of the guide) — verified by observing an unrelated field is untouched after a narrow PATCH. **(auto)** - [ ] Update's per-field propagation result (`Propagated`/`NotSupportedByProvider`/ `PropagationFailed`/`NotApplicable`) is handled without crashing regardless of which value is returned. - [ ] Update on a final order returns `409 ORDER_ALREADY_FINAL`, and your integration treats this as "no further changes possible," not a transient error to retry. - [ ] `GetStatus`, `GetTracking`, `GetTrackingHistory` are all null-safe in your parsing — every tracking field is nullable and frequently absent. **(auto)** - [ ] Cancel before dispatch returns `outcome: "Cancelled"` immediately. **(auto)** - [ ] Cancel after acceptance (where reachable in your staging setup) returns `outcome: "ConfirmationPending"` and your integration waits for the `delivery.cancelled` webhook rather than assuming immediate cancellation. - [ ] A repeat Cancel call on an already-cancelled order is handled gracefully (your integration treats `409 ORDER_ALREADY_FINAL` here as "already cancelled"). - [ ] Your integration does not attempt to call any return/resolution endpoint — return handling is fully passive (status + webhooks only), per Section 18 of the guide. ## 4. Webhooks and convergence - [ ] `POST /api/v1/webhooks/test` successfully reaches your registered endpoint and your signature verification accepts it. - [ ] Your webhook signature verification uses the **raw** request body, not a re-serialized parsed object (Section 10.4 of the guide) — verified by testing against a request where JSON key order or number formatting could plausibly differ. - [ ] Your webhook handler deduplicates on `eventId` — sending the same payload/headers twice does not double-process. - [ ] Your webhook handler tolerates an unrecognized `eventType` without crashing (forward compatibility, Section 21 of the guide). - [ ] Your webhook handler correctly parses `webhook.test`'s distinct flat payload shape (Section 9.9), not just the main event schema. - [ ] Your webhook handler responds `2xx` quickly and processes asynchronously if its own work is slow (the 15-second timeout in Section 9.3). - [ ] Temporarily breaking your endpoint and confirming FleetBridge retries per the documented schedule (Section 9.4), then recovering it and confirming the delivery eventually succeeds (or requesting a manual resend from FleetBridge if it had already exhausted). ## 5. Errors, limits, and capability declaration - [ ] Your integration logs `correlationId` from error responses for support conversations. - [ ] Your integration does not blindly retry every `5xx` with a brand-new (non-idempotent) request — Create retries always reuse the same `Idempotency-Key` (Section 16.2 of the guide). - [ ] A `429` response is handled by waiting `Retry-After` before retrying, not a fixed/guessed delay. - [ ] Your integration does not assume a per-tenant or per-key order-creation quota beyond the documented flat 300 req/min per-IP guard (Section 22 of the guide). ## 6. Sign-off - [ ] All items above are `CONFORMANT` or explicitly `NOT APPLICABLE` with a stated reason. - [ ] `certification/certify.py` result file attached to your certification request. - [ ] Staging Base URL, API key prefix (never the raw key), and webhook endpoint URL confirmed with FleetBridge ahead of production activation.