Kargo API'si ile gönderi oluşturma: istekten barkoda adım adım

Mağaza yazılımınız bir siparişi kargoya vermek istediğinde API'ye bir gönderi isteği iletir. Bu isteğin kargo firmasında gerçek bir gönderiye, yani barkodu ya da takip numarası olan bir kayda dönüşmesi birkaç adımdan geçer.

Bu yazıda bu adımları sırasıyla ve SiparişTakip'in her adımda ne yaptığıyla birlikte anlatıyoruz.

1. İstek kabul edilir

Mağazanız alıcı bilgilerini (ad, adres, telefon), paket bilgilerini ve hangi kargo firmasıyla gönderileceğini API'ye iletir. İstek kabul edildiğinde gönderi SiparişTakip'te kaydedilir ve işlenmek üzere sıraya alınır.

Kabul, gönderinin kargo firmasında oluştuğu anlamına gelmez. Kargo firmasına iletim arkada yapılır; böylece kargo firmasının sistemi yavaş ya da geçici olarak erişilemez olduğunda mağazanızın sipariş akışı beklemez.

2. Adres kontrolü

Alıcı adresi gönderinin en sık sorun çıkaran bilgisidir. Adreste il ya da ilçe eşleşmiyorsa gönderi kargo firmasına iletilmeden önce incelemeye alınır. İncelemedeki gönderi gönderi hakkı tutmaz; adres düzeltildiğinde işleme devam eder.

3. Gönderi hakkı ayrılır

Gönderi kargo firmasına iletilmeden önce paketinizden bir gönderi hakkı ayrılır (bloke edilir). Sıra şöyledir:

• Paketinizin bu dönemki limitinde yer varsa hak limitten ayrılır.
• Limit dolduysa ve krediniz varsa hak krediden ayrılır (bunu panelden kapatabilirsiniz).
• İkisi de yoksa gönderi "kota bekliyor" durumuna alınır. Gönderi kaybolmaz; kredi aldığınızda, paketinizi yükselttiğinizde ya da yeni dönem başladığında kendiliğinden işlenir. 15 gün içinde hak açılmazsa iptal edilir ve hak tüketmez.

Hak bu aşamada yalnız ayrılır; kesin olarak düşmesi için gönderinin kargo firmasında oluşması gerekir.

4. Kargo firmasında oluşturma

Gönderi, sizin kargo hesabınızla seçtiğiniz firmanın sistemine iletilir. Her firmanın beklediği biçim farklıdır; alan dönüşümleri ve firmaya özgü kurallar bu adımda uygulanır. Örneğin PTT'de barkod, PTT'nin size ayırdığı barkod aralığından sırayla atanır; HepsiJet ise gönderiyle birlikte yazdırılabilir etiketi döner.

Öncelikli işlem olan paketlerde gönderi oluşturma istekleri ayrı bir sırada bekler; yoğun saatlerde barkod daha hızlı çıkar.

5. Sonuç: oluştu, başarısız ya da zaten var

Kargo firmasının yanıtı üç sonuçtan birine dönüşür:

• Oluştu: Gönderi firmada kaydedildi. Barkod ya da takip numarası gönderiye eklenir ve ayrılan hak kesin olarak düşer.
• Başarısız: Firma gönderiyi kabul etmedi (örneğin teslimat bölgesi dışındaki ilçe ya da eksik bilgi). Neden panelde ve API'de görünür; ayrılan hak serbest kalır, yani başarısız gönderi hak tüketmez. Bilgiyi düzeltip yeniden gönderebilirsiniz.
• Zaten var: Aynı gönderi firmada daha önce oluşturulmuşsa ikinci kez oluşturulmaz ve ikinci kez hak düşmez.

Kargo firmasına bağlanırken geçici bir sorun olursa istek, aynı gönderinin iki kez oluşmasına yol açmayacak şekilde yeniden denenir.

6. Takip başlar

Oluşturulan gönderi takibe alınır. Aktif gönderiler kargo firmasından paketinize göre belirlenen aralıklarla sorgulanır; yeni durum panelde ve API'de görünür. Takibin nasıl çalıştığını kargo takip otomasyonu yazısında ayrıntılı anlattık.

Özet

Bir gönderi isteği; kabul, adres kontrolü, hak ayırma, kargo firmasında oluşturma ve takip adımlarından geçer. Hak yalnız gönderi firmada başarıyla oluştuğunda düşer; oluşmayan gönderi hak tüketmez. Kurulum adımları için nasıl çalışır sayfasına bakabilirsiniz.