kargoDİ API dokümantasyonu

Sürüm: v2 · Bu sayfa herkese açıktır.

API, kurumsal (işletme) hesaplar içindir. Kendi yazılımınızdan kargo fiyatı sorabilir, gönderi açabilir ve durumunu izleyebilirsiniz. Tüm istekler ve yanıtlar UTF-8 kodlu JSON’dur. Adresler https://mail.kargodi.com/api/v2/ ile başlar.

• Kimlik doğrulama
• Fiyat sorgulama
• Hızlı karşılaştırma
• Gönderi oluşturma
• Gönderi durumu
• Taşıyıcı durumu
• Ürünler
• Webhook
• Yalnız panelden yapılanlar
• Hata kodları

Kimlik doğrulama

Her istekte iki başlık gönderilir:

X-API-Key: ANAHTARINIZ
X-API-Secret: GIZLI_ANAHTARINIZ

Anahtar çiftini kurumsal panelde Ayarlar → API ekranından oluşturursunuz. Gizli anahtar yalnız oluşturulduğu anda gösterilir; kaydedin. Yeniden oluşturursanız eski çift geçersiz olur. Anahtarı tarayıcıda veya mobil uygulamada saklamayın, yalnız sunucunuzdan kullanın.

Anahtar eksik ya da yanlışsa 401, hesap kurumsal değilse 403 döner.

Fiyat sorgulama

POST /api/v2/get_shipping_cost.php

Gönderinin ölçü, şehir ve ödeme türünü alır; hesabınıza göre hesaplanmış kargo seçeneklerini ucuzdan pahalıya döndürür. Fiyat, hesabınızın ön ödemeli ya da paket modeline göre değişir. Paketi olmayan paketli bir hesap için seçenek dönmez.

{
  "product_weight": 2,
  "package_width": 20, "package_height": 15, "package_length": 25,
  "product_quantity": 1,
  "sender_city": "Bursa", "sender_country": "Türkiye",
  "receiver_city": "İstanbul", "receiver_country": "Türkiye",
  "payment_type": "prepaid"
}

Yanıt (kısaltılmış):

{
  "status": "success",
  "message": "Shipping options calculated.",
  "data": {
    "options": [
      {
        "cargo_id": 18, "cargo_name": "Sendeo",
        "base_price": 99.75, "tax_amount": 23.34,
        "final_charge": 140.05,
        "desi": 2.5, "effective_weight": 2.5,
        "service_area": "intercity",
        "supports_cod": true, "applied_cod_fee": 0,
        "supports_kontrollu_kargo": false, "kontrollu_kargo_fee": 0
      }
    ],
    "desi": 2.5, "effective_weight": 2.5,
    "service_area": "intercity", "pricing_model": "prepaid"
  }
}

final_charge KDV ve hizmet bedeli dahil, ödeyeceğiniz tutardır. Kapıda ödeme ve kontrollü kargo gibi ek hizmet ücretleri taşıyıcıya göre değişir; her seçenekte ayrı alanlarla gelir.

Hızlı karşılaştırma

POST /api/v2/compare_rates.php

Panelde kayıtlı bir kargo şablonu için en uygun seçeneği tek satırda döndürür.

{ "pickup_location": "Bursa", "delivery_location": "İstanbul", "cargo_template_id": 1 }

{ "status": "success", "message": "Rates compared successfully.",
  "data": { "best_cargo_company_id": 18, "cargo_company_name": "Sendeo", "final_rate": 392.14, "delivery_charge": 392.14 } }

Gönderi oluşturma

POST /api/v2/create_order.php

Gönderiyi açar, ücreti hesabınızdan düşer (paket modelinde paketten gönderi hakkı kullanır) ve kargo kodunu almaya çalışır. Kendi kargo anlaşmanız varsa kayıt açılır; firma bağlantısı yoksa gönderi firmaya iletilmez.

{
  "ecommerce_order_id": "SIP-1001",
  "product_name": "Kulaklık", "product_price": 150.00,
  "product_quantity": 1, "product_weight": 1.2,
  "product_width": 20, "product_height": 15, "product_length": 25,
  "pickup_address_id": 1,
  "customer_name": "Ayşe Yılmaz", "customer_phone": "05320000000",
  "customer_address": "Örnek Mah. Örnek Sk. No:1",
  "customer_city": "İstanbul", "customer_state": "Kadıköy",
  "customer_country": "Türkiye", "customer_postcode": "34710",
  "payment_type": "cod"
}

HTTP 201
{ "success": true, "idempotent_replay": false, "message": "Order created successfully.",
  "order_id": 12345, "tracking_number": "TRK123456789",
  "delivery_charge": "140.05", "payment_status": "paid_from_balance", "cargo_company_id": 18 }

Aynı ecommerce_order_id tekrar gönderilirse HTTP 200 ve "idempotent_replay": true döner; ücret ikinci kez alınmaz. Bu sayede zaman aşımında isteği güvenle tekrarlayabilirsiniz.

tracking_number boş gelebilir; kod sonradan oluşur ve durum sorgusu ya da webhook ile iletilir. Bakiye yetersizse ya da paketli hesapta aktif paket yoksa 403/409 ile açıklama döner.

Gönderi durumu

GET /api/v2/get_order_status.php?order_id=SIP-1001

order_id, gönderi açarken verdiğiniz ecommerce_order_id değeridir.

{ "success": true, "message": "Order status retrieved successfully.",
  "status": "on_the_way", "tracking_number": "TRK123456789", "last_update": "2026-10-07 10:30:00" }

Ödeme aşamasındaki gönderilerde processing_payment, paid_from_balance, paid_by_sender ya da unpaid değerleri de görülebilir; bunları “henüz yola çıkmadı” olarak değerlendirin.

Taşıyıcı durumu

POST /api/v2/request_delivery_status.php

{ "order_id": 12345 }

order_id burada kargoDİ gönderi numarasıdır (create_order yanıtındaki order_id). Bağlantısı açık taşıyıcılarda taşıyıcının kendi durum metni de carrier_status olarak eklenir; diğerlerinde yalnız kargoDİ’deki durum döner.

{ "status": "success", "message": "Delivery status retrieved successfully.",
  "data": { "delivery_status": "on_the_way", "carrier_status": "Dağıtımda" } }

Ürünler

GET /api/v2/get_products.php — Panelde kayıtlı ürünlerinizi döndürür. İsteğe bağlı last_updated_at (YYYY-AA-GG SS:DD:ss) verirseniz yalnız o tarihten sonra değişenler gelir.

{ "success": true, "message": "Products retrieved successfully.",
  "products": [ { "id": 1, "name": "Kulaklık", "sku": "KLK-1", "price": "150.00",
    "weight_kg": "0.50", "width_cm": "10", "height_cm": "10", "length_cm": "10",
    "category": "Elektronik", "brand": "Marka", "stock_count": 50, "cover_image": null } ] }

Webhook

Gönderi durumu değiştiğinde kargoDİ sizin sisteminize haber verebilir. Adresi panelde Ayarlar → Hesap araçları → Webhook ekranından eklersiniz (en fazla 3 adres). Özellik yönetici tarafından kapatılmışsa ekranda kapalı görünür.

• İstek POST, gövde JSON’dur.
• Authorization: Bearer GIZLI başlığı gelir. Gizli değer, adresi eklediğinizde ekranda bir kez gösterilen imza anahtarıdır; kaydedin ve sunucunuzda doğrulayın.
• Yalnız herkese açık HTTPS (443 portu) adreslere gönderilir. Yönlendirme izlenmez.
• 2xx yanıt kabul sayılır. Başarısız gönderim yeniden denenmez; son sonuç panelde görünür. Bu yüzden bir olayı kaçırdıysanız durum sorgusunu kullanın.

{
  "event": "shipment.status",
  "order_id": "SIP-1001",
  "status": "completed",
  "tracking_number": "TRK123456789",
  "sent_at": "2026-10-07T10:30:00+03:00"
}

Yalnız panelden yapılanlar

Şu işlemler için şimdilik API ucu yoktur; kurumsal panelden yapılır: gönderi iptali, iade kodu oluşturma, etiket yazdırma, bakiye yükleme, fatura ve raporlar. Bu sayfada olmayan bir ucu çağırmayın; çalışacağı garanti edilmez.

Hata kodları

Hata yanıtı { "success": false, "message": "..." } ya da { "status": "error", "message": "..." } biçimindedir. message metni İngilizcedir ve yazılım tarafından eşleştirilmemelidir; HTTP kodunu esas alın.

Örnek

curl -X POST https://mail.kargodi.com/api/v2/get_shipping_cost.php \
  -H "X-API-Key: ANAHTARINIZ" -H "X-API-Secret: GIZLI_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{"product_weight":2,"sender_city":"Bursa","sender_country":"Türkiye","receiver_city":"İstanbul","receiver_country":"Türkiye","payment_type":"prepaid"}'