Hızlı başlangıç

Bu adımlar bir test anahtarı kullanır; gerçek veriye hiçbir şey dokunmaz. Köşeli parantez içindeki her değer ve her ... bir yer tutucudur.

Test anahtarı alın. Şirketinizin Sahibi ya da bir Yöneticisi Ayarlar > Entegrasyonlar altında requests:write, requests:read, deals:read ve tracking:read kapsamlarıyla bir test entegrasyonu oluşturur ve anahtarı kopyalar (bkz. Erişim). Şimdilik kabuğunuzda tutun:
Terminal window
```
export BASE="https://app.quatlasglobal.com/api/integrations/v1"
export QUATLAS_KEY="qk_test_..."   # test anahtarınız, gizli anahtar kasanızdan
```

Talep oluşturun. Her oluşturma bir X-Idempotency-Key taşır; externalReference kaydın sizdeki numarasıdır.

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 palet yedek parça", "weightKg": 8400, "packageCount": 12 },
    "incoterm": "FCA"
  }'

Yanıt 201 Created:

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

Kimliği saklayın: export REQUEST_ID="<talep-kimliği>".

Talebi ilerletin. Yalnız deneme alanındaki ilerletme uç noktası talebi gerçek bir talebin yaşadığı adımlardan geçirir: Published, sonra BidReceived (istediğiniz kadar), 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
```
Her yanıt talebin durumudur. Sırası gelmemiş bir adım 409 (Integration.SandboxTransition) alır.

Geri okuyun, kimlikle ya da kendi numaranızla:

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

curl "$BASE/shipment-requests?externalReference=QS-0001" \
  -H "Authorization: Bearer $QUATLAS_KEY"

{
  "id": "<talep-kimliği>",
  "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": "<anlaşma-kimliği>",
  "operationStatus": "Delivered",
  "deliveredAt": "2026-10-13T09:16:42Z",
  "cancelledAt": null,
  "webUrl": "https://app.quatlasglobal.com/settings?section=integrations",
  "livemode": false
}

Anlaşmayı ve operasyonu okuyun. Awarded adımından sonra anlaşma rotaları deneme verisi döner (1000.00 EUR, “Sandbox Carrier”):

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

curl "$BASE/deals/<anlaşma-kimliği>/tracking" \
  -H "Authorization: Bearer $QUATLAS_KEY"

Bir tekrarı deneyin. 2. adımı hiç değiştirmeden yeniden gönderin. Yeni bir şey oluşmaz: ilk yanıt X-Idempotency-Replayed: true başlığıyla geri döner. Yeni bir X-Idempotency-Key ama aynı externalReference ile gönderirseniz yanıt 409 olur ve requestId ilk talebin kimliğidir. Bkz. Idempotency.

Canlıya geçiş

Akışınız deneme alanında çalışınca Sahip ya da Yöneticinizden ihtiyacınız olan kapsamlarla bir canlı entegrasyon isteyin ve anahtarı değiştirin. Başka hiçbir şey değişmez: rotalar, gövdeler ve yanıtlar aynıdır, yanıtlarda "livemode": true yazar. Canlı oluşturma şirketinizde gerçek bir talep açar; "publish": true göndermedikçe taslak olarak.