Gönderi oluşturma: tekil, toplu ve Idempotency-Key

Gönderi oluşturma asenkrondur. API isteği doğrular, gönderiyi sıraya alır ve hemen 202 döner. Kargo firmasına iletim arka planda yapılır; sonuç gönderinin state alanına yansır.

• Senkron ret (422): kabulde bilinen kurallar: alan biçimi, sipariş numarasının firmaya uygunluğu, firmaya özel seçenekler, hesap kuralları. Gönderi oluşmaz.
• Asenkron ret (failed): kargo firması gönderiyi kendisi reddederse gönderi failed olur, neden last_error alanına yazılır. Düzeltip yeniden gönderebilirsiniz (İptal ve düzeltme).
• Hesap askıda ya da kapalıysa (403 tenant_not_active): yeni gönderi kabul edilmez; tekil ve toplu oluşturma aynı kodu döner. Gövdede notice (code, reason, action, message) bulunabilir; message kullanıcıya gösterilebilecek açıklamadır.
• Kargo hesabının bilgileri eksikse (422 carrier_account_incomplete): hesabın gönderi için gereken bilgileri henüz dolmamıştır; eksik alanların adları missing'dedir. Bilgiler hesap doğrulandığında gelir; sonra tekrar deneyin.

Tekil gönderi

POST /api/v3/shipments (scope shipments:write)

{
  "reference": "SIP-1001",
  "carrier": "yurtici",
  "carrier_account_id": 12,
  "recipient": {
    "name": "Ayşe Yılmaz",
    "phone": "05321234567",
    "email": "ayse@example.com",
    "address_line": "Atatürk Cad. No: 10 D: 3",
    "neighborhood": "Kızılay Mah.",
    "district": "Çankaya",
    "city": "Ankara",
    "postal_code": "06420"
  },
  "parcels": [{ "weight_grams": 1500, "length_mm": 300, "width_mm": 200, "height_mm": 100, "quantity": 1 }],
  "payer": "sender",
  "cash_on_delivery": { "amount": 149990, "currency": "TRY", "collection_method": "cash" },
  "declared_value": { "amount": 149990, "currency": "TRY" },
  "content_description": "Tekstil ürünü",
  "invoice_number": "ABC2026000001234"
}

Yanıt 202:

{ "data": { "id": "01JB…", "reference": "SIP-1001", "state": "pending", "…": "…" }, "resubmitted": false }

Alanlar

Birimler ve biçimler:

• Para kuruş cinsinden tamsayı ve para birimi: {"amount": 149990, "currency": "TRY"} = 1.499,90 TL.
• Ağırlık gram, ölçüler milimetre.
• Desi ondalık string: "2.5". Sayı değil, yuvarlama farkı olmasın diye metin.
• Telefon: Türkiye numarası; +90, 0 ile ya da 10 hane yazılabilir, API normalleştirir. Yanıtta +905321234567 biçiminde döner.
• İl ve ilçe adı metin olarak gönderilir. API'nin il ve ilçe sözlüğü: GET /api/v3/geo/cities, GET /api/v3/geo/districts.

Aynı sipariş numarası

Sipariş numarası bir kanalda, kargo firması başına tekildir.

• Aynı numarayla aynı firmaya gönderi işlenmekteyse ya da oluşmuşsa: 409 reference_in_use. Problem gövdesinde mevcut gönderinin kimliği ve durumu (shipment_id, shipment_status) döner.
• Aynı numaralı gönderi failed ya da address_review durumundaysa yeni istek onu yeniden kuyruğa alır: yanıt 202 ve resubmitted: true. Böylece başarısız siparişi aynı numarayla yeniden göndermek için önce silmeniz gerekmez.
• Aynı numaralı gönderi kargo firmasında oluşup iptal edildiyse numara aynı firmada yeniden kullanılamaz. İstek kabul edilir (202), ama gönderi failed olur: last_error.code reference_used_at_carrier, retryable: false. Yeniden deneme ya da düzeltme sonucu değiştirmez (düzeltmede sipariş numarası değişmez); siparişi yeni bir numarayla gönderin.

Toplu gönderi

POST /api/v3/shipments/batch (scope shipments:write), gövde {"items": [ … ]}. Her kalem tekil gönderinin gövdesiyle aynıdır. En çok 100 kalem.

Kalemler bağımsızdır: biri reddedilirse diğerleri yine kabul edilir. Yanıt 200:

{
  "data": [
    { "index": 0, "status": "accepted", "shipment": { "id": "01JB…", "state": "pending" }, "resubmitted": false },
    {
      "index": 1,
      "status": "rejected",
      "error": {
        "status": 422,
        "code": "validation_failed",
        "errors": [{ "field": "recipient.phone", "code": "invalid", "detail": "…" }]
      }
    }
  ]
}

• index, isteğinizdeki kalemin sırasıdır (0'dan başlar).
• Reddedilen kalemin error alanı tekil istekteki problem gövdesinin aynısıdır.
• Toplu istek, hız sınırında tek istek sayılır (Hatalar ve sınırlar).

Idempotency-Key

Ağ hatasında isteği güvenle tekrarlamak için Idempotency-Key başlığı gönderin. Oluşturma ve toplu oluşturmada zorunlu değil, önerilir. İptal, yeniden deneme ve düzeltme uçları da bu başlığı kabul eder.

Idempotency-Key: 6f1c2b7e-9d3a-4c1e-8b2f-0a5e7d9c4b11

• 1–255 karakter, yazdırılabilir ASCII. İstek başına benzersiz bir değer üretin (ör. UUID) ve tekrar denemelerde aynı değeri gönderin.
• Anahtar hesabınızın API kanalında (bütün API istemcileriniz için ortak) 24 saat geçerlidir; istemciler arasında çakışmayan anahtarlar kullanın (ör. sipariş numarası + istemci öneki).

• 422 doğrulama hataları saklanmaz: hatayı düzeltip aynı anahtarla tekrar gönderebilirsiniz.
• 200 / 202 yanıtları ve 409 durum hataları saklanır. 5xx saklanmaz.
• Anahtar göndermeseniz de sipariş numarası tekilliği çift gönderiyi önler (409 reference_in_use).

Gönderinin yanıttaki hali

Alıcı bilgileri yalnız tekil getirmede (GET /shipments/{id}) döner. Saklama süresi dolup silinmiş alıcı bilgisi null olur.