Güncelleme ve iptal

Sistemlerinizin API’den açtığı bir talep, API’den, uygulamanın talep sahibine uyguladığı kurallarla birebir aynı şekilde değiştirilir ve iptal edilir. API uygulamanın kendi komutlarına açılan bir kapıdır, ikinci bir kural kitabı değildir: uygulamanın reddettiğini API de aynı kodla reddeder.

İki çağrı da requests:write kapsamı ve bir X-Idempotency-Key ister (bkz. Idempotency). Şirketinizin sahibi olmadığı bir talep 404 döner.

Not

Yalnız API’den açılan talepler. Bir anahtar yalnız şirketinin sistemlerinin POST /shipment-requests ile (bir externalReference vererek) açtığı talepleri değiştirir. Uygulamada bir kişinin açtığı talep API’den her talep gibi okunur, ama yalnız uygulamada değiştirilir ve iptal edilir: güncelleme ve iptal 409 ve Integration.RequestNotCreatedViaApi döner, hiçbir şey yazılmaz.

Talebi güncelleme

PATCH /shipment-requests/{id} bir JSON merge patch (RFC 7396) alır; application/merge-patch+json ya da application/json olarak gönderin:

• Göndermediğiniz alan olduğu gibi kalır.
• null verilen alan, uygulama talep sahibinin onu silmesine izin veriyorsa temizlenir (aşağıdaki tablo). İzin vermiyorsa yanıt 400 ve Integration.FieldNotClearable olur; alan args.field içinde yazar.
• Talepte olmayan bir alan (yazım hatası) 400 ve Integration.UnknownField, externalReference ya da status gibi salt okunur bir alan 400 ve Integration.FieldNotUpdatable döner. Hiçbir şey sessizce yok sayılmaz.
• Metin denetim karakteri (U+0000 ve benzerleri; sekme, satır sonu ve satır başı olur) ya da bozuk bir surrogate kaçışı ("\ud800" gibi) içeremez: 400 ve Integration.InvalidBody döner, alan args.field içinde yazar; metadata değerinde Integration.MetadataInvalid döner, anahtar args.key içinde yazar.
• Gövde en fazla 64 KB’tır; daha büyüğü 413 ve Integration.BodyTooLarge döner.

curl -X PATCH "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests/<talep-kimliği>" \
  -H "Authorization: Bearer $QUATLAS_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H "X-Idempotency-Key: EBA-2026-000123-update-1" \
  -H 'If-Match: "<etag>"' \
  -d '{
    "cargo": { "weightKg": 9100, "packageCount": 14 },
    "notes": null,
    "reason": "İki palet eklendi",
    "metadata": { "costCenter": "LOJ-215" }
  }'

Yanıt 200’dür; gövde GET /shipment-requests/{id} ile aynıdır ve talebin yeni ETag değerini taşır.

Ne, ne zaman değişir

Talebin kendi alanları (ilanı) uygulamadaki gibi yalnız talep Published iken değişir: taslak, yayınlanmadan önce uygulamada düzenlenir; teklif süresi kapanmış bir ilan önce uygulamada yeniden açılır; verilmiş ya da iptal edilmiş talep kapanmıştır. Kendi kayıtlarınız her durumda değişir.

Durum	İlan alanları	metadata, purchaseOrderNumber, costCenter
Draft	409 ShipmentRequest.InvalidTransition	Evet
Published, teklif yok	Evet	Evet
Published, teklif var	Evet; fiyatı etkileyen değişiklik her teklifi taşıyıcısının yeniden onayına bağlar	Evet
BiddingClosed	409 ShipmentRequest.InvalidTransition	Evet
Awarded	409 ShipmentRequest.InvalidTransition	Evet
Cancelled	409 ShipmentRequest.InvalidTransition	Evet

Bir istek tek bir işlemde yazılır ya da hiç yazılmaz: herhangi bir parçası reddedilirse (yanlış durumda ilan değişikliği, metadata sınırı, eski bir If-Match) hiçbir parçası, kayıtlarınız da dahil, yazılmaz.

Yayındaki talepte teklifler

Güzergâh, mod, yük, takvim ya da Incoterm değişikliği fiyatı etkiler; bu yüzden her bekleyen teklif, taşıyıcısı onu yeniden onaylayana, fiyatını değiştirene ya da geri çekene kadar bekletilir ve o arada kabul edilemez. Taşıyıcılar yanıt verebilsin diye teklif süresi en az 12 saat daha açık kalır. Yalnız notların değişmesi fiyatı etkilemez. reason (isteğe bağlı, en fazla 500 karakter) yeniden bakması istenen taşıyıcılara gösterilir; talebin alanlarına yazılmaz. Taşıyıcılar değişikliği ancak güncellemenizin her parçası yazıldıktan sonra duyar; fiyatı etkileyen değişiklik onlara ulaşamazsa hiçbir şey uygulanmaz (503, ShipmentRequest.AmendmentNotDelivered) ve yeniden deneyebilirsiniz.

Her alanda ilanla aynı olan bir istek hiçbir şeyi değiştirmez ve yeni bir revizyon açmaz. Gövdedeki revision, ilanın uygulamada ya da API’den kaç kez değiştiğini sayar.

Alanlar ve null

Alan	null
origin, destination (nesnenin kendisi)	Reddedilir. İçindeki değişen alanları gönderin.
origin.countryCode, destination.countryCode	Reddedilir.
origin ya da destination içinde city, locationType, unLocode, addressLine, postalCode, contactName, contactPhone, handling	Temizler.
windowFrom, windowTo	Reddedilir.
transportMode	Reddedilir: modu açık bırakmak için "modePolicy": "Open" gönderin.
modePolicy	Reddedilir. Open modu temizler; Required bir mod ister.
cargo (nesnenin kendisi), cargo.description	Reddedilir.
cargo.standardType, cargo.dimensions	Temizler.
cargo.maxStackLayers, cargo.maxTopLoadKg	İstif sınırlarının ikisini birden temizler: uygulama onları birlikte tutar ya da bırakır.
cargo.weightKg, volumeM3, packageCount, temperatureMinC, temperatureMaxC	Reddedilir.
cargo.hazardous, stackable, fragile, exceedsStandard, outOfGauge	Reddedilir: true ya da false gönderin.
preferredPickupDate, preferredDeliveryDate, preferredDeliveryTime, isFlexibleSchedule	Reddedilir.
incoterm	Reddedilir.
notes	Temizler ("" de temizler).
purchaseOrderNumber, costCenter	Temizler.
metadata	Tüm anahtarları siler. Bkz. Metadata.
reason	Göndermemekle aynıdır.

Alan değerleri oluşturmanın kurallarına ve sözcüklerine uyar (transportMode Road, Sea, …; incoterm FCA, …). Kurala uymayan alan 422 döner; errors alanın yoluyla, örneğin cargo.description, gelir.

İyimser eşzamanlılık: ETag ve If-Match

Bir talebin her okuması (GET /shipment-requests/{id}, externalReference ile bulma, güncelleme ve iptal yanıtları) bir ETag başlığı taşır: talebin sürümü. Güncellemede ya da iptalde onu If-Match olarak geri gönderin; talep siz okuduktan sonra değiştiyse yazma 412 ile reddedilir ve aradaki bir uygulama değişikliğini asla ezmezsiniz.

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "title": "Integration.PreconditionFailed",
  "status": 412,
  "detail": "The request changed since you read it: If-Match does not match its current ETag. Read it again, then retry.",
  "code": "Integration.PreconditionFailed"
}

• If-Match isteğe bağlıdır. Gönderilmezse yazma gerçekleşir.
• Etiket, talebin kilidi altındaki hâliyle, yazmayla aynı işlemde karşılaştırılır: aynı anda aynı etiketi gönderen iki yazardan ikisi birden kazanamaz; ikincisi 412 alır.
• Sürüm, talebin durumu, ilanı, iptali ya da kendi kayıtlarınız değişince değişir. Yeni bir teklif geldiğinde değişmez: pazar talebin kendisi değildir.
• If-Match: * her talebe uyar. Zayıf bir etiket (W/"...") hiçbir zaman uymaz.
• Tekrar edilen yanıt (aynı X-Idempotency-Key) ilkiyle aynı ETag değerini taşır.
• 412 hiçbir zaman tekrar edilmez: talebi yeniden okuyun ve yeni If-Match ile yeniden deneyin; aynı X-Idempotency-Key olur ve yeniden deneme gerçekten çalışır.

Talebi iptal etme

POST /shipment-requests/{id}/cancel, isteğe bağlı bir reason ile (en fazla 500 karakter):

curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests/<talep-kimliği>/cancel" \
  -H "Authorization: Bearer $QUATLAS_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: EBA-2026-000123-cancel" \
  -d '{ "reason": "eBA sürecinde iptal edildi" }'

• API’den açılmış talepte, uygulamanın talep sahibine izin verdiği yerde çalışır: Draft, Published ya da BiddingClosed talep. İptal kaydedildikten sonra bekleyen teklifler düşer ve taşıyıcılara uygulamadaki gibi bildirilir (bu adım yarıda kalırsa kısa süre sonra: tamamlanana kadar, bir kez, yeniden denenir); başarısız bir iptal kimseye bildirilmez.
• İptal edilmiş talebi yeniden iptal etmek aynı talebi döner (200); ilk iptal zamanı ve gerekçesi korunur.
• Yanıt okumayla aynı gövde ve yeni ETag’tir. If-Match güncellemedeki gibi çalışır.

Verilmiş talep bir anlaşmadır. Kapanış odasında anlaşmadan çekilmek ya da canlıya geçmiş operasyonu iptal etmek ayrı akışlardır ve uygulamada kalır. API 409 döner ve anlaşmayı gösterir:

{
  "title": "Integration.RequestAwarded",
  "status": 409,
  "detail": "This request was awarded and is a deal now. The API does not cancel deals: withdrawing a deal in the closing room, or cancelling its operation once it is live, is done in the app.",
  "code": "Integration.RequestAwarded",
  "dealId": "<anlaşma-kimliği>",
  "args": { "dealId": "<anlaşma-kimliği>" }
}

Webhook’lar

• request.updated, talebin sahibine talebin değiştiğini söyler: ilanı (uygulamada ya da API’den) ya da kendi kayıtları (API’den). data.changedFields değişen grupları (origin, destination, transportMode, modePolicy, cargo, schedule, incoterm, notes, purchaseOrderNumber, costCenter, metadata), data.revision ilanın revizyonunu verir. Bir PATCH tam olarak bir request.updated doğurur ve değiştirdiği her şeyi sayar; hiçbir şeyi değiştirmeyen istek olay doğurmaz.
• request.cancelled, talep sahibinin reason değerini (ya da null) taşır.

Bkz. Olaylar.

Not

Deneme alanında güncelleme ve iptal aynı durum kurallarına ve alan denetimlerine uyar. Deneme alanı ilanı saklamaz; bu yüzden gönderdiğiniz her ilan alanı changedFields içinde değişmiş sayılır. Bkz. Deneme alanı.