Skip to main content

Integration guide

Go-live checklist — Integrator API

Staging smoke tests and production readiness steps before enabling integrator traffic.

Field-level detail for every endpoint is in the API reference.

Complete this checklist in a non-production environment before you enable production traffic. QueryTek validates integrator releases on staging and local Compose; your team may use staging, a dedicated test tenant, or your own pre-production API base URL.

  • Optional first pass: use the public integrator sandbox workbench (/developer/account signup → JWT in browser only) before wiring production credentials
  • Obtain Keycloak client credentials / user JWT for the target tenant (client_admin or platform_admin as required)
  • Confirm API base URL and TLS
  • GET /v1/health and GET /v1/readyz succeed
  • POST /v1/intake/submit returns 201 with submission id
  • Retry POST /v1/intake/submit with the same Idempotency-Key and body returns the same 201 (no second submission)
  • Same Idempotency-Key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH
  • Retry POST /v1/documents and POST /v1/batches with the same Idempotency-Key and file digest returns the same 201 (no second document or batch)
  • Retry POST /v1/documents/{id}/pay and POST /v1/batches/{id}/pay with the same Idempotency-Key returns the same 200 checkout payload
  • Retry POST /v1/documents/{id}/withdraw and POST /v1/batches/{id}/withdraw with the same Idempotency-Key returns the same 200 (no second purge)
  • Retry POST /v1/documents/{id}/payment/confirm and POST /v1/batches/{id}/payment/confirm with the same Idempotency-Key and transaction_id returns the same 200 (no second paid transition)
  • Retry POST /v1/documents/{id}/payment/sync and POST /v1/batches/{id}/payment/sync with the same Idempotency-Key returns the same 200
  • Retry POST /v1/pay/invite/redeem with the same Idempotency-Key and token returns the same 200 (no second redeem)
  • GET /v1/intake/submissions/{id} returns the submission
  • POST /v1/webhooks/subscriptions with HTTPS FQDN returns 201 and a one-time secret
  • Persist secret offline; confirm GET /v1/webhooks/subscriptions does not return secrets
  • Implement signature verification (see the webhooks guide sample)
  • Confirm 422 on http:// webhook URL and private IP targets
  • Confirm 401 without Bearer token
  • Confirm 429 behavior under load (optional soak)
  • Your client is generated from the current OpenAPI integrator subset
  • Confirm a test event reaches your webhook endpoint and appears as delivered in GET /v1/webhooks/deliveries

Production API must not require /docs — distribute integrator-openapi.json + these guides.