TRAQ

Overview

TRAQ External Client Integration API allows third-party applications, ecommerce platforms, and external business systems to connect directly with the TRAQ delivery platform.

Using secure API authentication, external systems can automatically:

Create customers
Create delivery orders
Sync delivery information
Receive real-time webhook updates
Track order delivery status
Automate delivery workflows

This integration system is mainly designed for ecommerce platforms, POS systems, logistics partners, and external software providers who need delivery management integration with TRAQ.

The API supports secure backend communication using Bearer Token authentication and JSON-based request/response handling.

Workflow

Think in two layers: first save your integration token in TRAQ so your server is allowed to call the API; then create data in a fixed order — driver, customer, order.

Step 1: Save your integration token

Admin: Settings → Driver → “External client API (integration)”.
Paste a long random value in Integration API token, save. Your backend must send that same value as Authorization: Bearer on every REST or GraphQL call.
Optional: set order-completed webhook URL and signing secret in the same block for delivery callbacks.

If the token is empty, TRAQ returns HTTP 503 for integration calls until you save one.

Step 2: Create driver, customer, then order

Use the same sequence whether you call REST or GraphQL:

Diagram reads left to right (technical flow stays LTR even on RTL pages).

Token in admin

Create driver

Create customer

Create order

Driver — open Create driver when you need a driver user id to assign from your system.
Customer — open Create customer to register the buyer and keep the returned customer id.
Order — open Create order with items and delivery address (pass driver id only if you already created one).

If drivers are created only inside TRAQ by staff, you may skip the driver API step and start with customer.

Authentication

Send the token on every request.

Method	Header
Bearer	`Authorization: Bearer <token>`

401 — wrong or missing token. 503 — token not configured in settings.

Headers

Authorization: Bearer YOUR_INTEGRATION_TOKEN
Accept: application/json
Content-Type: application/json

GraphQL API

One URL for all integration mutations. Send JSON with query and optional variables. Same Bearer token as REST.

POST https://gotraq.com/api/v1/driver/integration/graphql

Supported operations

query { ping } — health check
createCustomer — CreateCustomerInput
createOrder — CreateOrderInput (uses address, product qty)
createDriver — CreateDriverInput

GraphQL may return HTTP 200 with errors in the body; always check the payload.

cURL (ping)

curl -sS -X POST "https://gotraq.com/api/v1/driver/integration/graphql" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { ping }"}'

Example mutation bodies (JSON POST)

createCustomer

{
  "query": "mutation CreateCustomer($input: CreateCustomerInput!) { createCustomer(input: $input) { success message data { id name email phone default_address { id address_name block } } } }",
  "variables": {
    "input": {
      "name": "Partner User",
      "email": "[email protected]",
      "phone": "+96550000000",
      "customer_address": {
        "name": "Partner User",
        "phone": "+96550000000",
        "email": "[email protected]",
        "country": "KW",
        "state": "Area",
        "city": "City",
        "block": "1",
        "street": "Example Street"
      }
    }
  }
}

createOrder

{
  "query": "mutation CreateOrder($input: CreateOrderInput!) { createOrder(input: $input) { success message data { id status amount } } }",
  "variables": {
    "input": {
      "customer_id": "1",
      "external_reference": "SHOP-ORDER-1001",
      "driver_id": "2",
      "products": [{ "id": "1", "qty": 1 }],
      "address": {
        "name": "Recipient",
        "phone": "+96550000000",
        "email": "[email protected]",
        "country": "KW",
        "state": "Area",
        "city": "City",
        "address": "Block 1, Street 2, Building 3"
      }
    }
  }
}

createDriver

{
  "query": "mutation CreateDriver($input: CreateDriverInput!) { createDriver(input: $input) { success message data { id first_name last_name email phone client_driver_id civil_id license_no driver_type } } }",
  "variables": {
    "input": {
      "first_name": "API",
      "last_name": "Driver",
      "email": "[email protected]",
      "phone": "+96550000001",
      "password": "change-me-in-production",
      "civil_id": "CIV-123456",
      "license_no": "LIC-12345",
      "driver_type": "full_time",
      "client_driver_id": "EXT-DRV-001"
    }
  }
}

Browser GraphQL tester

Send test requests

Pick a tab, edit the JSON body if needed, then send. Every request is an HTTP POST to the GraphQL URL below with Content-Type: application/json. Use the same integration token as REST.

GraphQL endpoint URL

Request URL (POST)

POST https://gotraq.com/api/v1/driver/integration/graphql

Headers (template matches the active tab)

Header template

Authorization: Bearer YOUR_INTEGRATION_SECRET
Accept: application/json
Content-Type: application/json

Use the same token you saved in TRAQ admin. Send adds Authorization and your token for you.

Your integration token

Request body (JSON)

Response

Request body (JSON)

Response

Request body (JSON)

{
    "query": "mutation CreateCustomer($input: CreateCustomerInput!) { createCustomer(input: $input) { success message data { id name email phone default_address { id address_name block } } } }",
    "variables": {
        "input": {
            "name": "API doc test user",
            "email": "api-doc-773783122710@example.test",
            "phone": "+96550000000",
            "customer_address": {
                "name": "API doc test user",
                "email": "api-doc-773783122710@example.test",
                "phone": "+96550000000",
                "latitude": 29.3759,
                "longitude": 47.9774,
                "country": "KW",
                "state": "State",
                "city": "City",
                "block": "1",
                "street": "Test Street",
                "avenue": "Avenue 12",
                "house_no": "15",
                "building_no": "B-7",
                "floor": "3",
                "apartment_no": "12",
                "direction": "Ring bell twice; delivery dock at rear.",
                "paci_number": "PACI-00000000",
                "address_type": "apartment"
            }
        }
    }
}

Response

Request body (JSON)

{
    "query": "mutation CreateOrder($input: CreateOrderInput!) { createOrder(input: $input) { success message data { id status amount } } }",
    "variables": {
        "input": {
            "customer_id": "1",
            "driver_id": "1",
            "payment_method": "cod",
            "payment_status": "pending",
            "external_reference": "DOC-TEST-001",
            "products": [
                {
                    "id": "",
                    "qty": 2,
                    "name": "External Rest Product",
                    "sku": "EXT-PROD-REST",
                    "price": 20,
                    "weight": 1.5,
                    "tax_amount": 12,
                    "discount_amount": 1,
                    "serial_number": "12345",
                    "product_image": "https://traq.ae/storage/uploads/product/08b502543e6a50622351_2026-05-06-6638553990668.jpg"
                }
            ],
            "address": {
                "name": "API doc test user",
                "phone": "+96550000000",
                "email": "api-doc-773783122710@example.test",
                "country": "KW",
                "state": "State",
                "city": "City",
                "address": "1, Test Street"
            }
        }
    }
}

Response

Create customer

POST /api/v1/traq/integration/customers

Request body

Field	Req	Notes
`name`	Yes	string, max 255
`email`	Yes	valid email, unique
`phone`	No	store phone rules
`password`	No	min 6; random if omitted
`dob`	No	date
`customer_address`	No	object; when present, saves one default address on `ec_customer_addresses`. Omit entirely if you only need the customer record.
`customer_address.name`	Yes*	string, max 255 — *required when `customer_address` is sent
`customer_address.phone`	Yes*	string, max 255
`customer_address.email`	No	email, max 255; defaults from top-level `email` if omitted
`customer_address.latitude`	No	numeric −90…90 (optional; not stored on all DB variants)
`customer_address.longitude`	No	numeric −180…180
`customer_address.country` / `state` / `city`	No	string, max 255
`customer_address.block` / `street` / `avenue`	No	string, max 255
`customer_address.house_no` / `building_no` / `floor` / `apartment_no`	No	string, max 255
`customer_address.direction`	No	string, max 2000
`customer_address.paci_number`	No	string, max 255
`customer_address.address_type`	No	`house`, `office`, or `apartment` (default `house`)
`customer_address.office_no` / `office_name` / `building_name`	No	string

cURL

curl -sS -X POST "https://gotraq.com/api/v1/traq/integration/customers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"API doc test user","email":"[email protected]","phone":"+96550000000","customer_address":{"name":"API doc test user","email":"[email protected]","phone":"+96550000000","latitude":29.3759,"longitude":47.9774,"country":"KW","state":"State","city":"City","block":"1","street":"Test Street","avenue":"Avenue 12","house_no":"15","building_no":"B-7","floor":"3","apartment_no":"12","direction":"Ring bell twice; delivery dock at rear.","paci_number":"PACI-00000000","address_type":"apartment"}}'

Create order

POST /api/v1/traq/integration/orders

Request body

Field	Req	Notes
`external_reference`	No	string, max 255 — used for webhook correlation
`driver_id`	No	existing driver user id; auto-assigns the order
`products`	Yes	array, min 1 item
`products.*.id`	No	internal product id (or omit and pass `sku`)
`products.*.sku`	No	string, max 255 — resolved to product id when `id` is missing
`products.*.name`	No	string, max 255
`products.*.quantity`	Yes	integer, min 1
`products.*.price`	No	numeric, min 0
`products.*.weight`	No	numeric, min 0
`customer_address`	Yes	object
`customer_address.name`	Yes	string, max 255
`customer_address.phone`	Yes	string, max 255
`customer_address.email`	No	valid email, max 255
`customer_address.latitude`	Yes	numeric, between -90 and 90
`customer_address.longitude`	Yes	numeric, between -180 and 180
`customer_address.country / state / city`	No	string, max 255
`customer_address.block / street / avenue`	No	string, max 255
`customer_address.house_no / building_no / floor / apartment_no`	No	string, max 255
`customer_address.direction`	No	string, max 2000
`customer_address.paci_number`	No	string, max 255
`sub_total / tax_amount / shipping_amount / discount_amount / amount`	No	numeric, min 0 (computed if omitted)
`serial_number`	No	string — attached to the first order line

cURL

curl -sS -X POST "https://gotraq.com/api/v1/traq/integration/orders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 1,
    "external_reference": "PART-101",
    "products": [{"id": 10, "quantity": 1, "price": 0}],
    "customer_address": {
      "name": "Test User",
      "email": "[email protected]",
      "phone": "+96550000000",
      "latitude": 29.3759, "longitude": 47.9774,
      "country": "KW", "state": "State", "city": "City",
      "block": "1", "street": "Main"
    }
  }'

Response models

422 — business / duplicate (example)

{
  "success": false,
  "message": "Product is out of stock!"
}

Create driver

POST /api/v1/traq/integration/drivers

Request body

Field	Req	Notes
`first_name`	Yes	string, max 255
`last_name`	Yes	string, max 255
`email`	Yes	valid email, unique in `users.email`
`phone`	Yes	unique in `users.phone`; obeys platform phone rules
`password`	Yes	string, min 6
`civil_id`	Yes	string, max 100, unique in `am_drivers_profiles.civilian_id`
`license_no`	Yes	string, max 255
`driver_type`	Yes	one of `full_time`, `part_time`, `contract`
`client_driver_id`	No	string, max 255 — your external driver reference
`shifts[]`	No	array of `{ shift_start, shift_end }` (strings, max 32)
`duty_shift / duty_start_time / duty_end_time`	No	string

cURL

curl -sS -X POST "https://gotraq.com/api/v1/traq/integration/drivers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Driver",
    "email": "[email protected]",
    "phone": "+96550000001",
    "password": "secret123",
    "civil_id": "CIV-123456",
    "license_no": "LIC-7788",
    "driver_type": "full_time",
    "client_driver_id": "EXT-DRV-001"
  }'

Browser API tester

Send test requests

Pick a tab to try creating a customer, driver, or order, or to load your drivers. Calls go from your browser to the address below (usually this TRAQ site). For the first three tabs, edit the sample JSON if needed, then click send. For drivers, you can add optional filters, then send.

Where requests are sent (base address)

Full request address (changes when you change tab)

POST https://gotraq.com/api/v1/traq/integration/customers

Headers (template matches the active tab)

Header template

Authorization: Bearer YOUR_INTEGRATION_SECRET
Accept: application/json
Content-Type: application/json

Use the same token you saved in TRAQ admin. Send adds Authorization and your token for you. The drivers tab loads data without a JSON body, so the sample headers do not include Content-Type.

Your integration token

Request body (JSON)

Response

Request body (JSON)

Response

Request body (JSON)

Response

Loads your driver list from TRAQ (the address above updates when you open this tab). Optional: add filters after the address, for example ?search=john or ?status=active.

Filters (optional)

Response

Webhook

POST Your configured webhook URL

When an order reaches completed, we POST JSON to your URL.

Headers

`Content-Type`	application/json
`X-Driver-Webhook-Id`	UUID
`X-Driver-Webhook-Signature`	HMAC-SHA256 (hex) of raw body

JSON body

{
  "event": "order.completed",
  "order": {
    "id": 1,
    "code": "ORD-1",
    "status": "completed",
    "external_reference": null
  },
  "customer": { "id": 1, "name": "Name" },
  "products": [{ "product_id": 10, "qty": 1 }]
}

Errors

HTTP Status	Typical Cause
401	Invalid or missing integration token
422	Validation or order error (email, stock, address, …)
503	Token not set; ecommerce off; no admin user