Gönderileri izleme: durumlar, liste ve takip hareketleri

Bir gönderinin iki durum alanı vardır:

• state: SiparişTakip'teki işlem durumu (kargo firmasına iletildi mi, hata var mı).
• tracking_status: kargo firmasındaki taşıma durumu. Gönderi created olduktan sonra dolar.

V1'de webhook yoktur. Değişiklikleri listeleme ucuyla düzenli aralıklarla çekersiniz (aşağıda).

İşlem durumları (state)

API yalnız eklemeyle değişir: yeni bir değer eklenebilir, var olan değerin anlamı değişmez. Tanımadığınız bir değer gelirse hata vermeyin.

needs_reconciliation'da SiparişTakip sonucu kargo firmasıyla kendisi netleştirir; gönderi created ya da failed olur. Bu durumda yeniden deneme ya da yeni gönderi açmayın. 24 saati aşarsa destekle görüşün.

Hesap kapatılırsa kargo firmasına henüz gönderilmemiş gönderiler failed olur, last_error.code tenant_closed.

Taşıma durumları (tracking_status)

Gönderi created olduktan sonra dolar. Bütün kargo firmalarında aynı değer kümesi kullanılır:

Teslim alınma zamanı (picked_up_at)

picked_up_at, kargo firmasının paketi fiziksel olarak teslim aldığı andır (firmanın bildirdiği hareket zamanı). İlk teslim alma hareketinde bir kez dolar, sonradan değişmez.

Mağazanızda "Kargoya verildi" bilgisini göstermek istiyorsanız ölçüt picked_up_at'in dolmasıdır, tracking_status değil. Gönderi ilk sorguda doğrudan in_transit görünebilir; picked_up değerini hiç görmeyebilirsiniz.

• Takip numarasının ya da barkodun atanması paketin teslim alındığı anlamına gelmez.
• Teslim alma bilgisi takip aralığına bağlı olarak gecikmeli gelir. Gece kargo firmasına sorgu yapılmaz; gece teslim alınan paket sabah yansır.
• Takip yapılamayan gönderide (tracking.stop_reason: untrackable) picked_up_at hiç dolmayabilir (Takibi durdurma).

Değişen gönderileri çekme

GET /api/v3/shipments (scope shipments:read)

Sonuçlar updated_at, ardından id sırasıyla eskiden yeniye döner. Bu sıra eşzamanlamayı güvenli kılar: araya giren bir değişiklik kaybolmaz.

{
  "data": [
    {
      "id": "01JB…",
      "reference": "SIP-1001",
      "carrier": "yurtici",
      "state": "created",
      "tracking_status": "info_received",
      "tracking_number": "…",
      "channel": "api",
      "capabilities": { "cancel": true, "retry": false, "correct": false, "choose_district": false },
      "recipient_city": "Ankara",
      "recipient_district": "Çankaya",
      "updated_at": "2026-11-03T09:20:11Z"
    }
  ],
  "meta": { "next_cursor": "eyJ1IjoiMjAy…", "has_more": false }
}

Önerilen döngü:

1. İlk çağrıda updated_since ile başlayın (ör. entegrasyonu açtığınız an).
2. Yanıttaki gönderileri işleyin, meta.next_cursor'ı saklayın. next_cursor son sayfada da doludur: kaldığınız yerin imlecidir.
3. meta.has_more true ise hemen sonraki sayfayı cursor ile isteyin. false ise bekleyin; sonraki çağrıda aynı cursor'la yeni değişiklikleri alırsınız.
4. Bekleme aralığı olarak 5 dakika önerilir; en sık dakikada bir çağırın.

Liste yanıtında alıcının kişisel bilgileri yoktur; yalnız il ve ilçe (recipient_city, recipient_district) döner. Alıcı bilgisi gerekirse tekil getirmeyi kullanın.

Tekil gönderi

GET /api/v3/shipments/{id} (scope shipments:read) gönderinin tamamını, alıcı bilgileriyle birlikte döner. Başka bir API istemcisinin gönderisi 404 not_found döner.

Gönderide (listede de) iki yardımcı alan vardır:

• channel: gönderinin geldiği kanal: api, panel, legacy_v2, woocommerce, opencart.
• capabilities: şu an hangi işlemi gösterebileceğiniz: cancel, retry, correct, choose_district, stop_tracking (İptal ve düzeltme). Bunu sunucu hesaplar; düğmelerinizi state'ten kendiniz türetmeyin, bu alana bakın.

Takip hareketleri

GET /api/v3/shipments/{id}/events (scope shipments:read): kargo firmasından gelen hareketler, eskiden yeniye. Sayfalama yoktur. Takibi durdurulan gönderiye (tracking.stopped_at dolu) yeni hareket eklenmez (Takibi durdurma).

{
  "data": [
    {
      "status": "info_received",
      "occurred_at": "2026-11-03T10:02:00Z",
      "precision": "datetime",
      "location": "Ankara",
      "raw_text": "…",
      "source": "carrier"
    }
  ]
}