Skip to content
QuatlasQuatlas Developers

Quickstart

This walk-through uses a test key, so nothing touches real data. Every value in angle brackets, and every ..., is a placeholder.

  1. Get a test key. Your company’s Owner or an Admin creates a test integration in Settings > Integrations with the requests:write, requests:read, deals:read and tracking:read scopes, and copies the key (see Getting access). Keep it in your shell for now:

    Terminal window
    export BASE="https://app.quatlasglobal.com/api/integrations/v1"
    export QUATLAS_KEY="qk_test_..."   # your test key, from your secret store

  2. Create a request. Every create carries an X-Idempotency-Key; externalReference is your own id for the record.

    Terminal window
    curl "$BASE/shipment-requests" \
      -H "Authorization: Bearer $QUATLAS_KEY" \
      -H "Content-Type: application/json" \
      -H "X-Idempotency-Key: QS-0001-create" \
      -d '{
        "externalReference": "QS-0001",
        "origin":      { "countryCode": "TR", "city": "Istanbul" },
        "destination": { "countryCode": "DE", "city": "Hamburg" },
        "transportMode": "Road",
        "cargo": { "description": "12 pallets of spare parts", "weightKg": 8400, "packageCount": 12 },
        "incoterm": "FCA"
      }'

    The answer is 201 Created:

    {
      "id": "<request-id>",
      "externalReference": "QS-0001",
      "status": "Draft",
      "webUrl": "https://app.quatlasglobal.com/settings?section=integrations",
      "publish": { "requested": false, "published": false, "refusalCode": null, "refusalDetail": null },
      "livemode": false
    }

    Keep the id: export REQUEST_ID="<request-id>".

  3. Move it forward. The sandbox-only advance endpoint walks the request through the life a real one has: Published, then BidReceived (as often as you like), Awarded, Delivered.

    Terminal window
    for step in Published BidReceived Awarded Delivered; do
      curl "$BASE/sandbox/shipment-requests/$REQUEST_ID/advance" \
        -H "Authorization: Bearer $QUATLAS_KEY" \
        -H "Content-Type: application/json" \
        -d "{ \"step\": \"$step\" }"
      echo
    done

    Each answer is the request’s status. A step out of order answers 409 (Integration.SandboxTransition).

  4. Read it back, by id or by your own reference:

    Terminal window
    curl "$BASE/shipment-requests/$REQUEST_ID" \
      -H "Authorization: Bearer $QUATLAS_KEY"
    

    curl "$BASE/shipment-requests?externalReference=QS-0001" \
      -H "Authorization: Bearer $QUATLAS_KEY"
    {
      "id": "<request-id>",
      "externalReference": "QS-0001",
      "purchaseOrderNumber": null,
      "costCenter": null,
      "status": "Awarded",
      "createdAt": "2026-10-13T09:15:02Z",
      "publishedAt": "2026-10-13T09:16:40Z",
      "biddingDeadline": null,
      "bidCount": 1,
      "awardedAt": "2026-10-13T09:16:41Z",
      "awardedCarrierName": "Sandbox Carrier",
      "dealId": "<deal-id>",
      "operationStatus": "Delivered",
      "deliveredAt": "2026-10-13T09:16:42Z",
      "cancelledAt": null,
      "webUrl": "https://app.quatlasglobal.com/settings?section=integrations",
      "livemode": false
    }

  5. Read the deal and its operation. After Awarded, the deal routes answer with sandbox data (1000.00 EUR, the “Sandbox Carrier”):

    Terminal window
    curl "$BASE/deals?externalReference=QS-0001" \
      -H "Authorization: Bearer $QUATLAS_KEY"
    

    curl "$BASE/deals/<deal-id>/tracking" \
      -H "Authorization: Bearer $QUATLAS_KEY"

  6. Try a retry. Send step 2 again, unchanged. Nothing new is created: the first answer comes back with an X-Idempotency-Replayed: true header. Send it with a new X-Idempotency-Key but the same externalReference, and the answer is 409 with the first request’s id in requestId. See Idempotency.

Going live

Section titled “Going live”

When your flow works in the sandbox, ask your Owner or Admin for a live integration with the scopes you need, and swap the key. Nothing else changes: the routes, bodies and answers are the same, and answers say "livemode": true. A live create makes a real request in your company, as a draft unless you send "publish": true.