İptal, yeniden deneme ve düzeltme

Başarısız ya da yanlış oluşturulmuş bir gönderiyi kurtarmanın dört yolu var. Hepsi Idempotency-Key başlığını kabul eder (Gönderi oluşturma).

Bir işlemin şu an yapılıp yapılamayacağını gönderinin capabilities alanı söyler: cancel, retry, correct (düzeltme), choose_district (ilçe seçimi), stop_tracking (takibi durdurma). Düğmelerinizi bu alana göre gösterin; kuralı state'ten kendiniz türetmeyin. Değer yanıt anındaki görüntüdür: arada durum değişmişse uç yine 409 döner.

İptal

POST /api/v3/shipments/{id}/cancel (scope shipments:cancel), gövdesiz.

409 shipment_not_cancelable gövdesinde gönderinin durumu döner: shipment_status (state) ve tracking_status (kargo firmasındaki durum). Gönderinin capabilities.cancel alanı aynı kuralla false'tur; düğmenizi bu alana göre gizlerseniz uç da aynı cevabı verir.

Açık bir iptal talebi varken de capabilities.cancel false'tur, ama tekrarlanan istek (ör. iki sekmeden) 409 değil, aynı 202 yanıtını alır.

Kargo hesabına göre iptal

Kargo firmasında oluşmuş gönderinin iptali kargo hesabına bağlıdır. Hesabın desteği GET /api/v3/carrier-accounts yanıtındaki capabilities.cancel alanındadır:

carrier ve local hesapta iptal 202 ile istenir ve sonucu asenkrondur. Değer firmaya değil hesaba bağlıdır ve değişebilir; firmaya göre sabit bir liste tutmayın. Tek bir gönderi için gönderinin capabilities.cancel alanına, hesap için hesabın capabilities.cancel alanına bakın. Kargo firmasına henüz gitmemiş gönderi her hesapta iptal edilebilir.

İptal sonucu

202'den sonra gönderiyi GET /api/v3/shipments/{id} ile okuyun (ya da listeyi updated_since ile izleyin):

cancel_unconfirmed sonrasında: gönderi ne iptal ne yolda sayılır; beklemeniz gerekmez. Aynı iptal isteğini tekrarlamayın, aynı sonuç döner. Gerekirse destekle görüşün. Gönderi sonradan kargo firmasında iptal edilirse takip durumu tracking_status: "canceled_by_carrier" olur; bu durumda yeni bir iptal isteği hemen 200 ve state: "canceled" döner.

Red sonrası yeni istek: not_cancelable ya da cancel_unconfirmed sonrasında talep kapanmıştır (cancel_requested: false). Yeni bir iptal isteği iptal kuralıyla yeniden değerlendirilir:

• Teslim ya da iade edilmiş gönderi: 409 shipment_not_cancelable.
• Hesapta cancel: local ise kargo firmasının teslim aldığı ya da hareket görmüş gönderi de 409 shipment_not_cancelable alır.
• Diğer durumlarda yeniden 202. Hesapta cancel: carrier ise yoldaki gönderinin iptali de yeniden istenebilir; kararı kargo firması verir, yine reddederse last_error.code yeniden not_cancelable olur.

Yeniden istemeden önce gönderinin capabilities.cancel alanına bakın; false ise uç 409 döner.

last_error kodlarının tam listesi API referansında (x-last-error-codes).

Yeniden deneme

POST /api/v3/shipments/{id}/retry, gövdesiz. Yalnız failed gönderide çalışır ve veriyi değiştirmeden yeniden sıraya alır: örneğin kargo hesabı bilgilerinizi düzelttikten sonra. Başka durumda 409 shipment_not_retryable (gövdede gönderinin durumu shipment_status).

Aynı sipariş numarasıyla yeni bir oluşturma isteği göndermek de failed gönderiyi yeniden sıraya alır (resubmitted: true).

Düzeltme

PATCH /api/v3/shipments/{id}: failed ya da address_review durumundaki gönderinin alanlarını değiştirip yeniden gönderir (capabilities.correct). Gövde oluşturma gövdesinin alanlarını alır, hepsi isteğe bağlıdır ve JSON Merge Patch (RFC 7396) kuralıyla gönderinin bugünkü verisine uygulanır:

• Yalnız gönderdiğiniz alanlar değişir.
• recipient ve options alan alan birleşir: recipient.phone gönderirseniz alıcının yalnız telefonu değişir.
• Bir alana null göndermek onu siler. Zorunlu bir alan silinirse 422.
• parcels gönderilirse koli listesinin tamamı yenisiyle değişir.

curl -X PATCH https://api.siparistakip.com/api/v3/shipments/01JB… \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"recipient": {"phone": "5321234567", "address_line": "Atatürk Cad. No: 12 D: 3"}}'

Birleşen veri oluşturmadaki kurallarla yeniden doğrulanır: alan kuralları ve kargo hesabının gönderi formu (Firma notları). Yanıt 202, state: "pending"; varış adresi yeniden çözülür, çözülemezse gönderi address_review olur.

Yalnız API kanalınızdaki gönderiyi düzeltebilirsiniz; panelden ya da eklentiden açılan gönderi 404 döner. Düzeltme, ilçe seçimi ve yeniden deneme yeni kredi harcamaz.

Çift gönderi koruması

Kargo firmasında oluşmuş (created) ya da sipariş numarası serbest kalmış gönderi hiçbir yoldan yeniden gönderilmez: yeniden deneme 409 shipment_not_retryable, düzeltme 409 shipment_not_correctable, aynı numarayla oluşturma 409 reference_in_use döner. Gönderinin capabilities.retry ve capabilities.correct alanları bu durumda false'tur.

İptal edilen gönderinin numarası serbest kalır, ama aynı kargo firmasında yeniden kullanılamaz: aynı firmaya bu numarayla açılan yeni gönderi failed olur (reference_used_at_carrier). Yeni bir numara kullanın (Aynı sipariş numarası).

Adres incelemesi ve ilçe seçimi

Gönderi address_review durumundaysa address_review alanı nedeni ve aday ilçeleri taşır:

{
  "address_review": {
    "reason": "ambiguous",
    "candidates": [{ "district_id": 1234, "district": "Çankaya", "city": "Ankara" }]
  }
}

Adaylardan birini ya da ilçe sözlüğünden (GET /api/v3/geo/districts) doğru ilçeyi seçip gönderin:

curl -X PATCH https://api.siparistakip.com/api/v3/shipments/01JB…/address \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"district_id": 1234}'

Aday listesi boş olsa da ilçe seçebilirsiniz: seçim adaylarla sınırlı değildir, ilçe sözlüğündeki herhangi bir ilçe olabilir. Yanıt 202; gönderi yeniden sıraya alınır. Seçim yalnız bu gönderiye uygulanır.

İlçe sözlüğünde olmayan district_id 422; address_review dışındaki gönderi 409 shipment_not_correctable. Content-Type, shipment_busy ve Idempotency-Key düzeltmedeki gibidir.

carrier_mapping_missing'de ilçe seçimi yapılamaz (capabilities.choose_district: false) ve uç 409 address_issue_on_platform döner. Seçtiğiniz ilçenin kargo firması karşılığı eksikse de aynı kod döner.

Takibi durdurma

POST /api/v3/shipments/{id}/stop-tracking (scope shipments:write), gövdesiz; Idempotency-Key isteğe bağlıdır. Kargo firmasında oluşmuş (created) bir gönderinin takibini kapatır; yanıt 200 ve gönderinin güncel hali. Yalnız API istemcinizin kanalındaki gönderiler durdurulabilir: başka kanalın gönderisi okuma uçlarındaki gibi 404 not_found döner (Tekil gönderi).

• İptal değildir: kargo firmasına istek gitmez, durdurma yalnız SiparişTakip'te kaydedilir; gönderi kargo firmasında olduğu gibi kalır. Gönderiyi iptal etmek için İptal ucunu kullanın.
• Geri alınmaz: takibi durdurulan gönderinin takibi yeniden açılamaz.
• Durdurulduktan sonra yeni takip hareketi gelmez; teslim ya da iade bilgisi de gelmez.
• Takip süren gönderide takip durur, stop_reason customer olur.
• Takip kalıcı olmayan bir sebeple durmuşsa (not_found, not_picked_up, untrackable) çağrı sebebi customer'a çevirir; stopped_at değişmez. Böylece takip sonradan kendiliğinden yeniden başlamaz.
• Sebep zaten customer ya da carrier_final ise (ya da başka kalıcı bir sebepse) 200 döner, gönderi değişmez. Aynı istek tekrarlanırsa da aynı 200 yanıtı döner.
• Gönderi kargo firmasında oluşmamışsa (created dışında her durum) 409 shipment_not_trackable. Gönderinin capabilities.stop_tracking alanı aynı kuralla false'tur.

Gönderinin tracking alanı her zaman bir nesnedir, kendisi hiçbir zaman null olmaz:

Takip sürerken ya da gönderi henüz kargo firmasında oluşmamışken (pending, failed…) iki alan da null'dır. Kalıcı olmayan bir sebeple duran takip yeniden başlarsa iki alan yeniden null olur.

Listeye ileride yeni değer eklenebilir; tanımadığınız bir değeri other gibi ele alın.