Metadata

metadata, şirketinizin bir taşıma talebinde tuttuğu, metin anahtarlardan metin değerlere giden düz bir nesnedir: masraf merkezi, satın alma siparişi, eBA süreç numarası, sistemleriniz talebi neyle anıyorsa. Şirketinizin özel verisidir: okumalarınızda ve şirketinize giden webhook’larda döner, başka hiçbir yerde değil.

Sınırlar

Anahtar sayısı	En fazla 20
Bir anahtar	A-Z, a-z, 0-9, _ ve - karakterlerinden 1 ile 40 karakter
Bir değer	0 ile 500 karakter arası, U+0000 gibi denetim karakteri içermeyen bir metin (sekme, satır sonu ve satır başı olur)
Toplam	8 KB (anahtarlar ve değerler, UTF-8)

Bir sınırı aşmak 400 ve Integration.MetadataInvalid döner. Sınırı aşan anahtar detail içinde ve args.key alanında yazar; hiçbir şey yazılmaz:

{
  "title": "Integration.MetadataInvalid",
  "status": 400,
  "detail": "Metadata holds at most 20 keys; adding 'plant' makes 21.",
  "code": "Integration.MetadataInvalid",
  "args": { "key": "plant" }
}

Oluşturmada verme

{
  "externalReference": "EBA-2026-000123",
  "metadata": { "costCenter": "LOJ-210", "ebaProcess": "P-7781" },
  "...": "oluşturma gövdesinin geri kalanı"
}

Metadata taleple aynı adımda kaydedilir: metadata ile açılan talepte metadata her zaman vardır. Boş bir nesne ya da hiç metadata göndermemek, metadata yok demektir.

Güncellemede değiştirme

PATCH /shipment-requests/{id} gönderdiğinizi mevcut olanla birleştirir; sistemlerinizin API’den açtığı talebin her durumunda çalışır (bkz. Güncelleme ve iptal):

Gönderdiğiniz	Sonuç
"metadata": { "plant": "Gebze" }	plant eklenir ya da değişir; diğer anahtarlar kalır.
"metadata": { "ebaProcess": null }	ebaProcess silinir; diğer anahtarlar kalır.
"metadata": null	Tüm anahtarlar silinir.
metadata alanı yok	Hiçbir şey değişmez.

Sınırlar sonuca uygulanır: zaten 20 anahtarı olan talebe yeni anahtar eklemek reddedilir. Aynı anda gelen iki güncelleme sırayla, her biri ötekinin yazdığının üzerine uygulanır: birinin eklediği anahtar ötekinde asla kaybolmaz.

Okuma

Talebin her okuması metadata taşır; yoksa boş bir nesnedir:

{
  "id": "<talep-kimliği>",
  "externalReference": "EBA-2026-000123",
  "status": "Published",
  "metadata": { "costCenter": "LOJ-210", "plant": "Gebze" },
  "revision": 1,
  "...": "diğer durum alanları"
}

Webhook’larda

Talebin sahibi şirkete giden bir webhook, talepte metadata varsa data.metadata taşır. Başka kimseye gönderilmez: aynı anlaşmanın taşıyıcıya giden teslimatları onu hiç taşımaz. Metadata değişikliği, changedFields içinde metadata ile bir request.updated doğurur.

Kim görür

Yalnız şirketiniz, API üzerinden. Taşıyıcılara, pazar yerine, anlaşmanın karşı tarafına, Qai asistanına ya da başka bir şirkete gösterilmez; bugün uygulamada da gösterilmez. Taleple birlikte, şirketinizin satır güvenliği altında saklanır.

Deneme alanında metadata aynı şekilde çalışır ve deneme talebiyle birlikte 30 gün sonra silinir.