Yurtiçi Kargo işlemleri

Genel akış

Eklenti ve REST API'miz, Yurtiçi Kargo SOAP servislerini doğrudan çağırmaz. Tüm istekler önce WP Entegrasyon relay katmanından geçer. Relay; XML zarfını oluşturur, yanıttaki PII alanlarını maskeler ve hata akışını standart bir JSON yanıtına çevirir.

Desteklenen eylemler

queryShipment (gönderi sorgulama)

Bir veya birden fazla kargo takip kodunun güncel durumunu sorgular. Yanıt; takip kodu, durum, son hareket tarihi ve teslim eden şube bilgilerini içerir. Bu eylem panelden veya POST /v1/relay/yurtici/queryShipment uç noktasıyla çağrılabilir.

getShipmentInfo (gönderi detayı)

Tek bir gönderinin alıcı, gönderici, hareket geçmişi ve faturalandırma detaylarını döndürür. Operasyon ekibinizin müşteri sorularını cevaplaması için uygundur.

createShipment (gönderi oluşturma)

Yeni bir kargo barkodu oluşturur. WP Entegrasyon, alıcı telefon numarasını otomatik olarak normalize eder, eksik şehir/ilçe bilgilerini Yurtiçi Kargo şehir kodu sözlüğüyle eşleştirir. YanıttacargoKey ve barcode alanları döner; bunları WooCommerce siparişine bağlamak eklentinin sorumluluğundadır.

cancelShipment (gönderi iptali)

Henüz teslim edilmemiş bir gönderiyi iptal eder. Yurtiçi Kargo, bazı durumlarda (gönderi şubeden çıktıysa) iptali reddedebilir; bu durumda relay SOAP_FAULT hatasını sade bir JSON nesnesine dönüştürür.

Hata yönetimi

Tüm hatalar tek bir şemada döner:

{
  "error": {
    "code": "SOAP_FAULT",
    "message": "Gönderi iptal edilemez",
    "details": { "yurticiCode": "GE-1023" }
  }
}

Sık karşılaşılan kodlar:

• VALIDATION_ERROR — istemci tarafında doğrulama hatası.
• SOAP_FAULT — Yurtiçi Kargo SOAP yanıtında hata.
• UPSTREAM_TIMEOUT — Yurtiçi Kargo servisi 30 saniye içinde yanıt vermedi.
• UNAUTHORIZED — API anahtarı geçersiz veya kapsamı yetersiz.

Hız limitleri

Hesabınız başına dakikada 60 yazma (createShipment, cancelShipment) ve dakikada 240 okuma (queryShipment, getShipmentInfo) isteğine kadar destek veriyoruz. Bu limitlerin üzerine çıkmanız gerekiyorsa Kurumsal plan ile özel limit ayarlayabiliriz.

PII maskeleme

Yanıtlardaki alıcı telefon ve e-posta alanları operasyon panelinde ve loglarda otomatik olarak maskelenir. Tam veri, yalnızca SMS gönderimi veya barkod yaratma sırasında geçici olarak işlenir.