Gönderi oluşturma

Amaç

Sevkora'nın taşıyıcı hesabında tenant adına doğrudan gönderi açmak (Hepsijet akışı; DEC-180 saf bayi). Gönderici bilgisi warehouse_idden kopyalanır, taşıyıcıya oluşturma ANINDA iletilir; ayrı "hazır hale getirme" adımı yoktur.

Göç İNDİ (TASK-243; DEC-185/4 köprüsü)

carrier_account_id girdisi BAYİ taşıyıcılarda bir TAŞIYICI İPUCUSUDUR, kimlik taşımaz. Sunucu ipucundan yalnız taşıyıcı kodunu + ortam niyetini okur, kimliği SİSTEM hesabından çözer ve gönderiyi sistem satırına bağlar; emekli (disabled) hesap geçerli ipucu kalır. Taşıyıcının sistem hesabı yapılandırılmamışsa istek fail-closed 422 errors.carrier_account_id döner (taşıyıcıya istek çıkmaz).

Satırın İKİNCİ okuması (TASK-412; DEC-361/363)

kendi-hesap modeline AÇIK bir taşıyıcıda aynı alan bir ipucu değil AÇIK SEÇİMDİR. Satırın KENDİSİ kimliktir: gönderi tenant'ın kendi taşıyıcı hesabıyla çıkar, Sevkora ücret ALMAZ ve gönderi billing_mode=carrier_direct olarak damgalanır. Ayrımı satırın durumu değil TAŞIYICI KODU yapar. Satır sevk edilebilir değilse (doğrulanmamış, doğrulaması düşmüş ya da devre dışı) istek 422 errors.carrier_account_id alır ve BAYİ YOLUNA DÜŞMEZ: sessiz düşüş, tenant kendi hesabını kastederken bakiyesinden para kesilmesi anlamına gelirdi.

Alan OPSİYONELLEŞTİ ve İNDİ (TASK-244; DEC-181/DEC-186/DEC-187)

alan gövdede HİÇ YOKKEN gönderi DRAFT doğar; taşıyıcıya SIFIR istek çıkar, ücret kesilmez; yanıt 201 status=DRAFT + carrier_account/barcode/tracking_url null, meta.carrier_capabilities boş (hesap bağı yok = fail-closed). delivery_no yine üretilir ve ilk olay DRAFT (source=system) yazılır. VARKEN bugünkü tek çağrılı davranış AYNEN korunur; mevcut tüketici kırılmaz (expand adımı). İki fazlı akış PA-18/PA-19 ile sürer. Sinyal ALANIN YOKLUĞUDUR (DEC-187): açık null (ya da metin olmayan bir değer) GEÇERSİZDİR ve 422 errors.carrier_account_id döner; alanın yokluğu ile geçersiz bir değer AYNI ŞEY DEĞİLDİR (PA-06 desi alanındaki DEC-175 ayrımıyla aynı). /api/v2'de alan kalkar (contract).

Yetki

Bearer anahtar; warehouse_id ve carrier_account_id YALNIZ anahtarın tenant'ında aranır; başka tenant'ın kimliği "yok" muamelesi görür (422). İpucu semantiği bu sınırı DEĞİŞTİRMEZ: tenant yalnız kendi görebildiği hesap kimliğiyle işaret edebilir.

Başlık

Idempotency-Key ZORUNLU (Temel model bölümündeki sözleşme).

İstek gövdesi

(Sevkora'nın fiili doğrulama kuralları):

Başarı 201

{data, meta.carrier_capabilities}; detay gövdesiyle aynı biçim (alan SETİ taslakta da BİREBİR aynıdır; yeni alan sızmaz). Taşıyıcılı yolda delivery_no/barcode/tracking_url sunucu/taşıyıcı üretimidir ve ilk olay CREATED (source=system) yazılmıştır; taslak yolda yalnız delivery_no üretilir, barcode/tracking_url null kalır ve ilk olay DRAFT (source=system) olur.

Ücret ön kontrolü (DEC-566)

carrier_account_id gönderildiğinde gönderi, taşıyıcıya iletilmeden ÖNCE etiket anındaki ücret hesabından geçer. Bu hesabın fiyatlayamadığı gönderi, örneğin Yurtiçi'nin tek parçada kabul ettiği 201 kg'yi aşan ağırlıkta ya da tarifenin kapanış kademesini aşan ölçüde kolisi olan gönderi, PA-06 etiket ucundaki ücret reddiyle aynı yanıtı alır: 422 {message}. Taşıyıcıya istek çıkmaz; gönderi, koli ve barkod oluşmaz, ücret kesilmez. Gönderi tenant'ın kendi taşıyıcı hesabıyla oluşturuluyorsa Sevkora ücret almadığı için bu kontrol yapılmaz.

Bakiye ön kontrolü

carrier_account_id gönderildiğinde ve gönderi Sevkora hesabıyla çıkacaksa, taşıyıcıya iletilmeden ÖNCE cüzdan bakiyesinin bu gönderinin etiket ücretini (KDV dahil) karşılayıp karşılamadığı da sorulur. Karşılamıyorsa istek PA-06 etiket ucundaki yetersiz bakiye reddiyle aynı yanıtı alır: 422 {message}. Taşıyıcıya istek çıkmaz; gönderi, koli ve barkod oluşmaz. Ön kontrol bakiyeyi değiştirmez ve tutarı ayırmaz; ücret yine etiket anında (PA-06) kesilir. Bu yüzden oluşturma ile etiket arasında aynı cüzdandan başka bir harcama yapılırsa etiket isteği yine yetersiz bakiye nedeniyle 422 alabilir; bakiye yüklendikten sonra etiket yeniden istenebilir ya da gönderi PA-05 ile iptal edilebilir. Gönderi tenant'ın kendi taşıyıcı hesabıyla oluşturuluyorsa bu kontrol de yapılmaz.

Hatalar

401, 409 (Idempotency-Key çakışması / işlem sürüyor), 422 alan hataları (errors{alan}; Idempotency-Key başlığı eksikse errors.idempotency_key; başka tenant'ın ya da olmayan kimlik errors.warehouse_id / errors.carrier_account_id alan hatası olarak döner, varlık sızdırılmaz), 422 errors.carrier_account_id (taşıyıcı createShipment desteklemiyor; örn. tex hesabı; adaptör hiç kurulmaz, DEC-014 guard'ı), 422 {message} (taşıyıcı reddi: validation/business_rule/conflict/not_found), 422 {message} (ücret ya da bakiye ön kontrolü reddi; taşıyıcıya istek çıkmaz), 429, 502 (taşıyıcıya ulaşılamıyor; kayıt oluşmadı, yanıt idempotency deposuna YAZILMAZ; yeniden denenebilir). Taşıyıcı conflict tekrarında çift kayıt oluşmaz; mevcut kayıt döner (idempotensi, 09-integrations).

curl -X POST "{{base_url}}/shipments" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEVKORA_API_ANAHTARINIZ" \
  -H "Idempotency-Key: 6f1c1c9e-ornek-istemci-anahtari" \
  -d '{
    "warehouse_id": "01K1ADRS000000000000000001",
    "carrier_account_id": "01K1TSYC000000000000000001",
    "buyer_name": "Ornek Alici",
    "buyer_phone": "5550000000",
    "buyer_address": "Ornek Mah. Deneme Cad. No:1",
    "buyer_city": "Istanbul",
    "buyer_district": "Kadikoy",
    "parcels": [{"desi": 2.5}]
  }'