Connect your ERP or WMS

REST API for onboarded ERP/WMS partners to push shipments and read public tracking. Integration request bodies use snake_case. Access is invite-only — QuickDex provisions your company API key after onboarding; there is no public signup or self-service key application.

Active base URLhttps://staging.api.quickdex.my/api/v1Staging

Integration endpoints: https://staging.api.quickdex.my/api/v1 (sandbox UAT) · https://api.quickdex.my/api/v1 (production). Staging host: staging.api.quickdex.my.

Preview · subject to change until contract freeze

API access

Integration access is controlled by QuickDex operations — not open for public application. After your company is onboarded as a partner, QuickDex delivers a company-scoped API key through your account manager or integration lead. The full secret is shown once at issuance; store it in your ERP vault immediately.

Partner flow: contact your QuickDex account manager → complete onboarding → receive your qd_live_… key and the staging API base URL for UAT (https://staging.api.quickdex.my/api/v1) before production cutover.

No self-service: this site documents the Integration API only. You cannot register, apply for, or mint API keys here — keys are issued internally by QuickDex after partner onboarding.

Quick start

Receive your company API key from QuickDex after onboarding (see API access).
Configure your ERP with the base URL shown above and send a test shipment on Staging first.
Persist order_no, tracking_no, and parcel waybill_no from the response.
Poll GET /tracking/{order_no} or link customers to https://track.quickdex.my/tracking/{order_no}.

curl -X POST "https://staging.api.quickdex.my/api/v1/integrations/shipments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qd_live_your_key_here" \
  -d '{
    "reference": "ERP-PO-2026-0042",
    "recipient_name": "Ahmad bin Ali",
    "recipient_phone": "+60123456789",
    "recipient_address_line1": "12 Jalan SS15/4",
    "recipient_city": "Subang Jaya",
    "recipient_state": "Selangor",
    "recipient_postcode": "47500",
    "cargo": [{
      "product_type": "general_merchandise",
      "quantity": 1,
      "weight_kg": 2.5,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }]
  }'

Authentication

Integration endpoints require a company-scoped API key. Pass it using either header:

Header	Example
`X-API-Key`	`qd_live_…`
`Authorization`	`Bearer qd_live_…`

Revoked or invalid keys return 401 Unauthorized. Keys are tied to one company — you cannot create shipments for another tenant.

Wire format

Topic	Rule
Integration JSON	`snake_case` field names
Public tracking JSON	`camelCase` inside the standard `{ data, meta }` envelope
Content-Type	`application/json`
Timestamps	ISO 8601 UTC (`created_at`, `updated_at`)

Enums (current)

Values below match the running codebase and docs/openapi-integrations.yaml. They may change before the v1 contract lock.

cargo[].product_type (request)

Required on each cargo line when creating a shipment.

general_merchandisefurnitureappliancebuilding_materialsother

status (integration order response)

Lowercase snake_case on POST /integrations/shipments responses.

createdpicked_updeparturearrivalout_for_deliverycompletedreturn_pendingreturn_initiatedreturncancelledtransfer_pendingtransfer_initiatedfailed_delivery

parcels[].status (integration response)

UPPER_SNAKE on integration responses (Prisma OrderItemStatus).

PENDINGPICKED_UPARRIVED_HUBARRIVED_COLLECT_POINTOUT_FOR_DELIVERYDELIVEREDFAILED_DELIVERYRETURNEDCOLLECTED

Create shipment

POST/integrations/shipments

Creates one shipment and returns order, tracking, and parcel waybill numbers.

Response · 200

{
  "id": "clx…",
  "order_no": "QD826000042",
  "tracking_no": "QD826000042",
  "reference": "ERP-PO-2026-0042",
  "status": "created",
  "parcel_count": 1,
  "parcels": [{
    "waybill_no": "QD826000042-1",
    "item_index": 1,
    "status": "PENDING"
  }],
  "self_collect_code": "QD4X7K",
  "chargeable_weight_kg": 2.5,
  "amount": 18.50,
  "created_at": "2026-07-07T05:00:00.000Z"
}

Batch create

POST/integrations/shipments/batch

Creates multiple shipments in one request. Valid rows succeed; invalid rows are listed in failures with index and message — typical for ERP bulk push jobs.

Request body

{ "shipments": [ /* ExternalCreateShipmentDto[] */ ] }

Print waybill

Requires API key scope print:read. List waybills for an order, then download the A6 PDF for a specific waybill id.

GET/waybills?orderId={order_id}

Returns parent/child waybill records for the order. Use the waybill id in the print step.

GET/waybills/{id}/print

Streams an inline A6 thermal waybill PDF and increments the print counter.

Example

curl "https://staging.api.quickdex.my/api/v1/waybills?orderId={order_id}" \
  -H "X-API-Key: qd_live_your_key_here"

curl "https://staging.api.quickdex.my/api/v1/waybills/{waybill_id}/print" \
  -H "X-API-Key: qd_live_your_key_here" \
  --output waybill.pdf

Public tracking

GET/tracking/{order_no}

No API key required. Returns a public snapshot suitable for customer-facing tracking pages.

Shareable URL: customers can also track at https://track.quickdex.my/tracking/{order_no}.

Errors

Status	Meaning
`400`	Validation failed — check field names (snake_case) and required cargo dimensions
`401`	Missing, invalid, or revoked API key
`409`	Duplicate `reference` for this company
`429`	Rate limited — back off and retry with exponential delay

Smoke test

Run the repo integration smoke script after your integration lead issues a key (internal QuickDex tooling). It checks health, OpenAPI JSON, creates one shipment, then reads public tracking.

INTEGRATION_API_KEY="qd_live_your_key_here" \
pnpm integration:smoke -- --api-base-url https://staging.api.quickdex.my/api/v1

Tracking-only mode: pnpm integration:smoke -- --skip-create --tracking-order-no QD826000042 --api-base-url https://staging.api.quickdex.my/api/v1

OpenAPI reference

Spec via same-origin proxy (/api/openapi/staging) → https://staging.api.quickdex.my/api/docs/integrations-json. Integrations and public tracking only; frozen subset in docs/openapi-integrations.yaml.

Checking live OpenAPI from /api/openapi/staging…

Loading OpenAPI reference…