externalReference

externalReference, talebin geldiği kaydın sizdeki numarasıdır; örneğin eBA kayıt numarası ya da bir ERP sipariş numarası. Quatlas onu talebin yanında, yalnız şirketinizin görebileceği şekilde tutar.

Kurallar

• Her oluşturmada zorunlu, en fazla 100 karakter. Baştaki ve sondaki boşluklar atılır.
• Şirketiniz içinde tekil. Aynı numara asla ikinci bir talep açmaz: yanıt 409 ve Integration.DuplicateExternalReference olur, gövde numarayı zaten taşıyan talebi gösterir.
• Moda göre ayrı. Canlı ve deneme alanı ayrıdır: test anahtarının numaraları canlı olanlarla çakışmaz. Deneme talebi, numarasıyla birlikte, 30 gün sonra silinir.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Integration.DuplicateExternalReference",
  "status": 409,
  "detail": "This externalReference was already used: the existing request is returned.",
  "code": "Integration.DuplicateExternalReference",
  "requestId": "<talep-kimliği>",
  "requestStatus": "Draft",
  "webUrl": "https://app.quatlasglobal.com/shipments/<talep-kimliği>",
  "livemode": true
}

status sorunun HTTP durum kodudur; requestStatus mevcut talebin kendi durumudur. Tekrar, istese bile talebi yeniden yayınlamaz.

Talebi kendi numaranızla bulma

Quatlas kimliğini saklamanız gerekmez:

curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests?externalReference=EBA-2026-000123" \
  -H "Authorization: Bearer $QUATLAS_KEY"

Yanıt GET /shipment-requests/{id} ile aynı durum gövdesidir. Parametre yoksa 400 (Integration.ExternalReferenceRequired); şirketinizin kullanmadığı bir numara için 404 döner.

Bir talepten doğan anlaşmalar da numaranızla listelenebilir:

curl "https://app.quatlasglobal.com/api/integrations/v1/deals?externalReference=EBA-2026-000123" \
  -H "Authorization: Bearer $QUATLAS_KEY"

Orada externalReference ya da shipmentRequestId alanlarından tam olarak birini gönderin; yoksa yanıt 400 (Integration.DealFilterRequired) olur.

Webhook’larda

Webhook gövdeleri, talebin sahibi şirketinizse (gönderici taraf) externalReference taşır. Anlaşmanın taşıyıcı tarafı null alır: numara, onu veren şirkete aittir.

Satın alma siparişi ve masraf merkezi

purchaseOrderNumber ve costCenter isteğe bağlıdır, her biri en fazla 100 karakter; taleple birlikte tutulur ve yalnız şirketinizce görülür. Her durum okumasında geri döner. externalReference’tan farklı olarak tekil olmaları gerekmez.