İyi yazılım budur
- Test ve canlı kargo hesaplarını, müşteri kodlarını ve yetkileri ayrı yönetin.
- Gönderi oluşturmada sipariş numarasından türetilen tekil referans kullanın.
- PDF ve ZPL etiketleri yazıcı türüne göre üretin; barkod sonucunu kayıt altına alın.
- Takip durumlarını webhook ve periyodik sorguyla yerel sipariş durumlarına eşleyin.
Kargo firmalarıyla API entegrasyonu nasıl çalışır?
Kargo API entegrasyonu, hazır siparişin alıcı ve paket bilgilerini kargo firmasına iletir; karşılığında gönderi/barkod numarası ve etiket alır. Gönderi hareketleri daha sonra API veya webhook yoluyla sisteme döner ve sipariş hazırlanıyor, kargoya verildi, dağıtımda, teslim edildi ya da iade gibi durumlara güncellenir.
Her kargo firmasının servis adı ve veri biçimi farklı olabilir. Bu nedenle uygulamanın içinde ortak bir kargo modeli, firma bazında ise ayrı adaptörler bulunmalıdır.
Sözleşme ve API bilgileri
API entegrasyonu yapılabilmesi için çoğu kargo firmasında kurumsal müşteri sözleşmesi, müşteri kodu ve web servis yetkisi gerekir. Test ortamı ile canlı ortamın kullanıcı adı, şifre, token, müşteri kodu ve endpoint bilgileri birbirinden ayrı tutulmalıdır.
- Kargo sözleşmesindeki gönderici müşteri kodunu doğrulayın.
- Test ve canlı servis adreslerini ayırın.
- Çıkış IP yetkilendirmesi gerekiyorsa sunucu IP’sini bildirin.
- Etiket, takip, iptal ve iade servislerinin yetkilerini ayrı kontrol edin.
- Şifre ve tokenları yönetim ekranında maskeli ve şifreli saklayın.
- Sözleşme değiştiğinde servis kodlarını güncelleyin.
Ortak gönderi veri modeli oluşturun
Uygulama her kargo firmasının alanlarını doğrudan sipariş tablosuna eklerse bakım zorlaşır. Önce ortak bir gönderi modeli tanımlanmalı, adaptör her firmaya uygun isteği üretmelidir.
| Ortak alan | Açıklama | Kontrol |
|---|---|---|
| shipment_reference | İşletme içi tekil gönderi referansı | Aynı siparişte mükerrer olmamalı |
| order_id | Yerel sipariş bağlantısı | Kısmi gönderide birden fazla olabilir |
| carrier_code/service_code | Kargo ve hizmet türü | Sözleşmedeki kodlarla eşleşmeli |
| recipient | Ad, telefon, adres, il ve ilçe | Zorunlu alanlar normalize edilmeli |
| package | Adet, desi, ağırlık ve içerik | Ondalık ve birim kuralları sabitlenmeli |
| tracking_code | Kargo takip numarası | Kanal ve müşteri bildiriminde kullanılmalı |
| label | PDF, PNG veya ZPL etiket | Format ve yazıcı uyumu kontrol edilmeli |
Adres, desi ve paket doğrulaması
Gönderi oluşturma hatalarının önemli bölümü adres ve paket verisinden kaynaklanır. İl ve ilçe yalnızca serbest metin olarak gönderilmemeli; kargo firmasının kod listesi veya normalize edilmiş şehir/ilçe tablosuyla eşleştirilmelidir.
Adres için temel kontroller
- Alıcı adı ve telefon numarası boş olmamalı.
- Ülke, il, ilçe ve posta kodu ayrı alanlarda tutulmalı.
- Telefon ülke kodu ve baştaki sıfır kuralları normalize edilmeli.
- Çok uzun adres satırları firmanın alan limitine göre bölünmeli.
- Yasaklı karakterler veya emoji temizlenmeli.
Paket için temel kontroller
Desi ve ağırlık ürün kartından, ambalaj tipinden veya paketleme ekranından hesaplanabilir. Bir sipariş birden fazla koliye ayrılıyorsa her koli ayrı paket kaydı ve etiket üretmelidir.
Gönderi oluşturma isteği
- Siparişin kargoya hazır olup olmadığı kontrol edilir.
- Adres ve paket alanları doğrulanır.
- Siparişten türetilen tekil gönderi referansı oluşturulur.
- Kargo adaptörü firma isteğini hazırlar.
- İstek güvenli bağlantıyla gönderilir.
- Dönen takip numarası ve gönderi kimliği kaydedilir.
- Etiket isteği ayrı veya aynı akışta çalıştırılır.
Ağ zaman aşımında aynı gönderinin iki kez açılmaması için kargo referansı tekil olmalı ve tekrar denemeden önce firma tarafında referans sorgulanmalıdır. API destekliyorsa idempotency anahtarı kullanılmalıdır.
PDF ve ZPL etiket farkı
PDF etiket A4 veya standart belge yazıcılarında kolay görüntülenir. ZPL ise Zebra uyumlu termal yazıcılarda doğrudan baskı için kullanılır. ZPL metnini tarayıcıya resim gibi vermek veya PDF’yi termal yazıcıya yanlış ölçekte göndermek okunmayan barkodlara yol açabilir.
Trendyol’un ortak etiket servislerinde barkod ZPL biçiminde dönebilir ve çoklu koliler için birden fazla etiket üretilebilir. Ortak etiket belgesi bu akışın paket bazında izlenmesi gerektiğini gösterir.
Takip durumları ve webhook
Kargo durumları her firmada farklı kodlarla döner. Uygulama bu kodları ortak sipariş durumlarına eşlemelidir; ham durum ve açıklama da ayrıca saklanmalıdır.
| Kargo olayı | Yerel durum | Otomatik işlem |
|---|---|---|
| Gönderi kaydı oluşturuldu | Etiket hazır | Paketleme ekranında barkodu aç |
| Şubede kabul edildi | Kargoya verildi | Müşteriye takip bilgisi gönder |
| Dağıtıma çıktı | Dağıtımda | İsteğe bağlı bildirim |
| Teslim edildi | Teslim edildi | Siparişi kapat ve teslim zamanını kaydet |
| Teslim edilemedi/iade | Sorunlu veya iade | Operasyon görevini aç |
Webhook sunan servislerde olaylar HTTPS adresine gönderilir. Webhook hızlıca 2xx cevap vermeli, ağır işlemler kuyruğa alınmalı ve olay kimliği tekilleştirilmelidir. EasyPost’un resmî webhook rehberi başarısız teslimatların tekrar gönderilebildiğini açıklar. Yine de kaçan olayları bulmak için periyodik takip sorgusu yapılmalıdır.
UPS geliştirici portalı da gönderi etiketi ve takip servislerini ayrı API grupları olarak sunar. UPS Shipping API ileri ve iade etiketleri; takip API’si ise gönderi durumlarını yönetir.
İptal ve iade gönderisi
Etiket basılmış fakat kargo firmasına teslim edilmemiş gönderi API üzerinden iptal edilebilir. Firmaya fiziksel teslim yapıldıktan sonra iptal yerine farklı operasyon gerekebilir. Durum sorgulanmadan “iptal edildi” işareti verilmemelidir.
İade gönderisinde gönderici ve alıcı yönü tersine döner, farklı sözleşme veya hizmet kodu kullanılabilir. Müşteriye gönderilen iade kodu ile kargo firmasındaki iade gönderi kimliği birlikte saklanmalıdır.
Birden fazla kargo firmasını tek panelde yönetme
Ortak adaptör arayüzü; gönderi oluştur, etiket al, takip et, iptal et ve iade oluştur işlemlerini standartlaştırır. Her firma kendi kimlik doğrulaması ve alan eşlemesiyle bu arayüzü uygular.
- İl/ilçe ve desiye göre otomatik kargo seçimi
- Pazaryeri anlaşması ile işletme anlaşmasını ayırma
- Şube, depo veya mağaza bazında gönderici hesabı
- Kargo kesinti durumunda alternatif firma yönlendirmesi
- Kanal bazlı etiket ve takip numarası geri yazma
Güvenlik ve hata yönetimi
- API şifrelerini şifreli saklayın ve günlüklerde göstermeyin.
- Webhook imzası veya kaynak doğrulamasını uygulayın.
- Aynı gönderi referansını ikinci kez oluşturmayı engelleyin.
- 4xx doğrulama hatalarıyla 5xx geçici hataları ayırın.
- Etiket verisini sınırlı erişimle saklayın.
- Her tekrar denemeyi ve kullanıcı müdahalesini kayıt altına alın.
Yaygın sorunlar ve çözüm yönü
| Belirti | Muhtemel neden | Kontrol |
|---|---|---|
| Gönderi oluşmuyor | Adres, ilçe kodu veya müşteri yetkisi hatalı | Firma cevabı ve gönderilen alanlar |
| Aynı siparişe iki takip numarası | Zaman aşımı sonrası kör tekrar | Tekil referans ve firma tarafı sorgu |
| Barkod yazıcıdan boş çıkıyor | ZPL/PDF formatı yanlış işleniyor | Etiket formatı, DPI ve yazıcı sürücüsü |
| Teslim edildi bilgisi panele gelmiyor | Webhook veya durum eşlemesi eksik | Olay günlükleri ve periyodik takip işi |
| İade kodu çalışmıyor | Yanlış hesap/hizmet kodu veya süre | İade sözleşmesi ve firma yanıtı |
Ne zaman teknik destek gerekir?
Birden fazla kargo firması ve depo kullanılacaksa, termal yazıcıya otomatik baskı gerekiyorsa, pazaryeri anlaşmaları ile işletme anlaşmaları karışıyorsa, takip durumları siparişe dönmüyorsa veya mükerrer gönderi oluşuyorsa adaptör, kuyruk ve kimlik modeli birlikte incelenmelidir.
Sık sorulan sorular
Kargo API bilgilerini nereden alırım?
Genellikle sözleşmeli olduğunuz kargo firmasının kurumsal müşteri temsilcisi veya entegrasyon birimi sağlar. Test ve canlı bilgiler ayrı olabilir.
Etiket tarayıcıdan otomatik yazdırılabilir mi?
Standart tarayıcı güvenlik nedeniyle yazdırma penceresi gösterebilir. Kiosk, yerel yazdırma uygulaması veya kontrollü termal yazıcı köprüsü gerekebilir.
Webhook yoksa takip yapılamaz mı?
Yapılabilir. Takip API’si belirli aralıklarla sorgulanır; ancak yüksek hacimde webhook daha hızlı ve verimli olabilir.
Kargo barkodu ve takip süreçlerini otomatikleştirin
Siparişten gönderi oluşturmaya, termal etiketten teslimat takibine kadar kargo firmalarını tek panelde yöneten entegrasyonu kuralım.
Kargo API Entegrasyonu İçin Teklif Alın