API Dokümantasyonu

Hesap bilgisi ve bakiye sorgula

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

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.

Yeni gönderi oluştur (ücret API bakiyenizden otomatik düşülür)

{
  "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ı

Örnek yanıt (201 Created)

{
  "success": true,
  "message": "Gönderi başarıyla oluşturuldu.",
  "data": {
    "id": 123,
    "tracking_number": "KS80000123",
    "status": "confirmed",
    "cargo_company": { "id": 1, "name": "..." },
    "pricing": { "total_price": 128.75, "discount_amount": 14.30 },
    "payment_status": "paid",
    "payment_method": "api_balance"
  }
}

Gönderi payment_status: paid olarak doğar ve arka planda taşıyıcıya iletilir. Bakiyeniz yetmiyorsa ya da ödenmemiş bir ölçü farkı borcunuz varsa 402 döner (bkz. Hata Kodları). Webhook adresiniz tanımlıysa aynı anda shipment.created olayı POST edilir.

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

Gönderi detayı

Gönderiyi iptal et — ücretin tamamı API bakiyenize iade edilir.

Ö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. Etiket, taşıyıcının resmî şablonu varsa o şablondur; yoksa 10x15 KargoSeç etiketidir — panelde bastığınızla birebir aynı kaynaktı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.