API Dokümantasyonu

Hesap bilgisi ve bakiye sorgula. Yanıttaki defaults bloğu, taşıyıcı seçmeden gönderi açtığınızda hangi firmanın ve hangi çıkış adresinin kullanılacağını gösterir.

Bakiye hareketleri listesi. Parametreler: type, date_from, date_to, per_page

Kayıtlı çıkış (depo) adresleriniz. Gönderi oluştururken sender_address_code alanına buradaki code değerlerini yazarsınız. Yeni depo eklemek için KargoSeç ekibiyle iletişime geçin.

Webhook adresinizi kendiniz tanımlayın. Gövde: url (zorunlu), rotate_secret (opsiyonel boolean).

{
  "success": true,
  "data": {
    "webhook_url": "https://magazam.com/kargosec/webhook",
    "webhook_secret": "aX9...48 karakter",
    "signature_header": "X-KargoSec-Signature",
    "signature_algorithm": "sha256=HMAC_SHA256(raw_body, webhook_secret)"
  }
}

Sır yalnızca bu yanıtta gösterilir, bir daha okunamaz. Güvenli bir yere kaydedin. Kaybederseniz rotate_secret: true ile yenileyin.

Türkiye'deki tüm illeri listele

Belirtilen ile ait ilçeleri listele

Aktif kargo firmalarını listele

Tüm kargo firmalarından fiyat karşılaştırması yap (hesabınızın indirim oranı uygulanmış fiyatlar döner)

{
  "shipment_type": "koli",
  "from_province_id": 34,
  "from_district_id": 450,
  "to_province_id": 6,
  "to_district_id": 780,
  "weight": 5,
  "width": 30,
  "length": 40,
  "height": 20
}

Parametreler

Ölçü (width/length/height), desi ve preset_desi_range alanlarının hiçbiri gönderilmezse fiyat hesaplanamaz. Yanıttaki her sonuçta original_price, discount_rate, discount_amount ve indirim uygulanmış total_price bulunur.

Belirli bir kargo firması için fiyat hesapla. compare ile aynı alanları alır; ek olarak cargo_company_id (zorunlu) ve quantity (opsiyonel, integer, min 1) kabul eder. preset_desi_range bu uçta kullanılmaz. Firma için fiyat bulunamazsa 404 döner.

Gönderi oluştur + ücreti tahsil et + etiketi döndür. Ayrıntılı anlatım için Tek Tuş Etiket bölümüne bakın. Aşağıdaki örnek tüm alanların açıkça verildiği hâldir; pratikte gönderici ve taşıyıcı alanlarını göndermenize gerek yoktur.

{
  "order_reference": "SIP-2026-10428",
  "cargo_company_id": 1,
  "shipment_type": "koli",
  "sender_name": "Ali Veli",
  "sender_phone": "05551234567",
  "sender_address": "Atatürk Cad. No:1",
  "sender_province_id": 34,
  "sender_district_id": 450,
  "receiver_name": "Ayşe Fatma",
  "receiver_phone": "05559876543",
  "receiver_address": "İstiklal Cad. No:2",
  "receiver_province_id": 6,
  "receiver_district_id": 780,
  "weight": 5,
  "width": 30,
  "length": 40,
  "height": 20,
  "quantity": 1,
  "content_description": "Elektronik parçalar"
}

Doğrulama kuralları

* Gönderici alanları ya hiç gönderilmez (kayıtlı depo kullanılır) ya da tamamı birlikte gönderilir. Yarım gönderici ("adı ben verdim, adresi sen tamamla") 422 ile reddedilir; aksi halde etikete birbirine ait olmayan ad ve adres basılır.

Örnek yanıt (201 Created)

{
  "success": true,
  "message": "Gönderi oluşturuldu ve ödemesi alındı.",
  "duplicate": false,
  "data": {
    "id": 123,
    "order_reference": "SIP-2026-10428",
    "tracking_number": "KS80000123",
    "status": "confirmed",
    "cargo_company": { "id": 1, "name": "..." },
    "carrier": { "id": 1, "name": "...", "tracking_number": "KGS000000123", "synced": true },
    "pricing": { "total_price": 128.75, "discount_amount": 14.30 },
    "payment": { "method": "balance", "paid": true, "amount": 128.75, "balance": 1871.25 },
    "label": { "status": "ready", "content_type": "application/pdf", "base64": "...", "url": "...", "expires_at": "..." },
    "payment_status": "paid",
    "payment_method": "api_balance"
  }
}

Gönderileri listele. Filtreler: status, tracking_number, date_from, date_to, per_page

Gönderi detayı. Etiket durumunu buradan da okuyabilirsiniz: label_status (awaiting_payment · pending · ready · unavailable), label_url (yalnızca ready iken dolu, 24 saat geçerli, oturumsuz), carrier_tracking_number (kargo firmasının gerçek barkodu; yoksa null) ve tracking_number_is_carrier. Ayrıntı için yukarıdaki "Etiket kuralı" kutusuna bakın.

{
  "success": true,
  "data": {
    "id": 4821,
    "tracking_number": "KGS000004821",
    "carrier_tracking_number": "KGS000004821",
    "tracking_number_is_carrier": true,
    "label_status": "ready",
    "label_url": "https://kargosec.com/api/v2/shipments/4821/label-download?expires=...&signature=...",
    "payment_status": "paid",
    "...": "diğer alanlar değişmedi"
  }
}

Gönderiyi iptal et. Bakiyeden ödenmişse ücretin tamamı API bakiyenize iade edilir; ödenmemiş gönderide iade yapılmaz ve varsa kart ödeme bağlantısı kapatılır. İsteğe bağlı reason alanı gönderebilirsiniz.

Örnek yanıt (200 OK)

{
  "success": true,
  "message": "Gönderi iptal edildi ve bakiyeniz iade edildi.",
  "data": {
    "refunded_amount": 128.75,
    "new_balance": 1871.25
  }
}

Gönderi takip bilgisi

Kargo etiketini al. Entegrasyonlu taşıyıcılarda (HepsiJet, UPS, Yurtiçi, KolayGelsin, Sürat, PTT) yalnızca kargo firmasının canlı etiketi döner; canlı etiket alınamıyorsa KargoSeç şablonuna düşülmez, 409 döner ve hazır olunca shipment.label_ready gönderilir. KargoSeç şablonu yalnızca entegrasyonsuz (manuel) firmalarda kullanılır.

Örnek yanıt (200 OK)

{
  "success": true,
  "data": {
    "tracking_number": "KS80000123",
    "content_type": "application/pdf",
    "label_base64": "JVBERi0xLjQKJ...",
    "label_url": "https://kargosec.com/api/v2/shipments/123/label-download?expires=...&signature=...",
    "label_url_expires_at": "2026-08-12T09:30:00.000000Z"
  }
}

• label_base64: PDF'in base64 hâli — decode edip doğrudan yazıcıya gönderebilirsiniz, ek istek gerekmez.
• label_url: imzalı ve 24 saat geçerli bağlantı. API anahtarı gerektirmez; depo yazıcınıza veya personelinize doğrudan verebilirsiniz. Süre dolduğunda bağlantı geçersizleşir.
• label_url_expires_at: bağlantının geçerlilik bitiş zamanı (ISO 8601).
• Ödeme yapılmamış gönderide 400 döner.
• Etiket henüz hazır değilse (gönderi taşıyıcıya iletilmemişse) 409 Conflict döner; gönderi taşıyıcıya iletildikten sonra tekrar deneyin.

label_url alanının işaret ettiği uç. PDF'i doğrudan (Content-Type: application/pdf) döner. Kimlik doğrulaması imza iledir, X-Api-Key gönderilmez. Bu adresi kendiniz kurgulamayın; her zaman /label ucundan dönen hazır bağlantıyı kullanın.