Going live
Go through this list before your integration reports facts from production. Each item links to the guide that explains it.
API keys
- Every system has its own production key, and no system uses the test tenant's key in production. See Getting started.
- Keys are kept on your servers, in a secret store or the environment, never in a browser, an app, a repository or a log.
- Your calls never log the
X-Api-Keyheader. - You know how to replace a key: ask OrderEx for a new key, deploy it, and ask OrderEx to revoke the old one once nothing uses it.
- If a key may have leaked, ask OrderEx to revoke it at once, and replace it. A revoked key gets
401on every call. - Your integration treats a
401as an alert to a person, not as something to retry.
Sending facts
- Every fact carries your own id, from the system where it happened. See A reliable integration.
- Every create sends an
Idempotency-Key, or an order has achanneland anexternalOrderNumberthat make a second create a 409order-already-exists. - Your retries resend the same body with the same key, wait longer each time and stop after a limit.
- A fact rejected because another fact has not arrived yet is kept and sent again later.
- Every time has an offset, and your servers' clocks are synchronized.
- Amounts are whole numbers in minor units, and every line has a
vatRate. See Core concepts. - No card number is ever sent. See Payment facts.
Errors
- Your client acts on a problem's
typeand handles atypeit does not know by its status code. See Errors. - Your logs keep a failed call's
correlationIdandtraceId, so you can quote them.
Webhooks
- Every call's
X-OrderEx-Signatureis verified on the raw body before anything else. See Webhooks. - Duplicates are skipped by
X-OrderEx-Event-Id. - Your receiver answers within 30 seconds and processes afterwards.
- You check
GET /api/v1/webhooks/{webhookId}/deliveriesfor deliveries that failed.
Changes to the API
- Your client ignores fields it does not know and treats an unknown enum value as other, as the versioning policy asks.
- Your client logs and alerts on a response with the
Deprecationheader.Sunsetgives the date the endpoint closes, andLinkwithrel="deprecation"points at the entry that says what to use instead. - Someone in your team follows the change list, where every change to the API is announced.
- Your integration does not call
PATCH /api/v1/orders/{id}/lines/{lineId}/quantitiesto report cancelled, shipped, delivered or returned quantities. See The order lifecycle.