Developers

Go-live checklist

From a working sandbox integration to the production app that real sellers connect.

How going live works

  1. Your integration works end to end on the sandbox with your own sandbox app and your test seller — orders walked through every step with the advance helper and their webhooks received and verified.
  2. You contact ColiSwift to go to production. Send your app name, logo, the scopes you need, your production redirect URIs (HTTPS), your webhook URL (HTTPS, public), your event filter if any, whether you need the COD Drop catalogue synchronisation (off unless ColiSwift enables it) and whether you need internal order details (orders:details) or internal product details (products:details) — both restricted, granted only on a stated need; see Apps and credentials.
  3. ColiSwift reviews the integration with you: the scopes requested, the redirect URIs, the webhook endpoint and the points of this checklist.
  4. ColiSwift creates your production app and hands you its client_id, client_secret and webhook secret (each shown once). Webhook deliveries to your URL start as soon as a seller connects.
  5. Each real seller connects your app from your product: they are sent to https://coliswift.com/oauth/authorize, sign in and approve. Every seller authorizes for themselves — nobody can approve on their behalf.

Security

  • Client secret, webhook secret and every token are stored server-side, encrypted at rest, never logged, never sent to a browser or a mobile app.
  • A fresh random state and PKCE verifier per authorization, checked on the callback.
  • Production redirect URIs are HTTPS and registered exactly (no trailing-slash surprises).
  • Every webhook signature is verified on the raw body with a constant-time comparison before anything is parsed.
  • You request the smallest set of scopes you use.

Tokens

  • Access tokens are refreshed before expires_in runs out, and on a 401 INVALID_TOKEN.
  • Refreshes are serialised per seller, and the new refresh token is saved before the new access token is used (a reused refresh token revokes the connection).
  • invalid_grant on refresh and 401 after refresh are handled as « disconnected »: stop calling, show the seller a « Reconnect ColiSwift » action.
  • Disconnecting in your product calls /api/oauth/revoke.

API use

  • All money is sent as decimal strings; no amount is ever recomputed from ColiSwift figures.
  • externalId is stable per order so retries are safe; duplicate: true is handled as success.
  • Countries come from GET /me → seller.countries.
  • You honour 429 and the RateLimit-* headers (600 requests per minute per connection).
  • Pagination follows nextCursor until hasMore is false; cursors are never built by hand.

Webhooks

  • The endpoint answers 2xx within 10 seconds and does the work asynchronously.
  • Events are de-duplicated on event_id and ordered with sequence; older states are not applied over newer ones.
  • Unknown event types are acknowledged and ignored, so new events never break you.
  • A nightly read-back (GET /orders?updatedSince=…, GET /products?updatedSince=…) repairs anything missed during an outage.

Operations

  • You log the X-Coliswift-Delivery id and the event_id of every delivery you receive, to trace a problem with ColiSwift.
  • You tell ColiSwift who to contact when your endpoint is down; dead deliveries are announced to the seller and to ColiSwift and can be replayed.