İçeriğe geç
KargoKonum
Bu sayfada (Akış başlıkları)

Geliştirici Dokümantasyonu

KargoKonum REST API, desteklenen tüm Türk kargo firmalarını tek bir şema ve KVKK uyumlu maskeli JSON çıktısıyla sorgulamanızı sağlar. Tüm uçlar https://kargokonum.com/v1 kök adresinden sunulur.

OpenAPI 3.1 JSON Ücretsiz Anahtar Al

1. Kimlik doğrulama

Her /v1/* çağrısında API anahtarınızı Authorization: Bearer kk_live_... ya da X-Api-Key HTTP başlığıyla gönderin. Anahtar göndermeyen veya iptal edilmiş anahtarla yapılan istekler 401 Unauthorized döndürür.

HTTP Başlığı 
Authorization: Bearer kk_live_ornek_anahtar
Accept: application/json

2. Hız sınırı ve kota başlıkları

Anahtar başına dakikada 60 istek hız sınırı uygulanır. Yalnızca /v1/track/{takip_no} ucu başarılı kargo sorgularında paket kotanızdan 1 hak düşer; firma tespiti ve şube rehberi uçları kotadan düşmez. Her yanıtta güncel durum aşağıdaki HTTP başlıklarıyla döner:

Yanıt Başlığı Açıklama
X-RateLimit-Limit / X-RateLimit-Remaining Dakikalık toplam istek hakkı (60) ve o dakika içinde kalan istek sayısı.
X-Quota-Limit / X-Quota-Remaining Aktif paketinizin toplam gönderi kotası ve kalan sorgu hakkı (Limitsiz pakette unlimited).
GET

/v1/detect/{takip_no}

Kotadan düşmez

Takip numarasındaki boşluk ve tireleri temizler, barkod yapısına uyan kargo firmalarını sırasıyla listeler. Tek eşleşme varsa doğrudan /v1/track/{takip_no} çağrısına geçebilirsiniz; birden fazla aday dönerse kullanıcıya firma seçtirip ?carrier=slug parametresiyle sorgulayabilirsiniz.

Örnek İstek & Yanıt 
curl -H "Authorization: Bearer kk_live_..." \
     "https://kargokonum.com/v1/detect/4092817368814"

{
  "number": "4092817368814",
  "candidates": [
    {
      "slug": "aras",
      "name": "Aras Kargo",
      "short": "Aras"
    }
  ]
}
GET

/v1/track/{takip_no}

1 kota harcar

Gönderinin normalize edilmiş durum kodunu, son konumunu, kronolojik hareket geçmişini, varsa teslimat şubesinin telefon-adres-koordinat bilgisini ve KVKK uyumlu maskelenmiş alıcı/gönderici bilgisini döndürür. İsteğe bağlı ?carrier=yurtici sorgu parametresiyle firmayı açıkça belirtebilirsiniz.

Parametre Konum Açıklama
takip_no URL yolu (zorunlu) 6 ile 40 karakter arası takip veya barkod numarası.
carrier Query (isteğe bağlı) Firma kısa kodu (aras, yurtici, mng, ptt, hepsijet, surat, kolaygelsin, ups, trendyolexpress, pakettaxi).
Örnek İstek & 200 OK Yanıtı 
curl -H "Authorization: Bearer kk_live_..." \
     "https://kargokonum.com/v1/track/4092817368814?carrier=aras"

{
  "number": "4092817368814",
  "carrier": {
    "slug": "aras",
    "name": "Aras Kargo",
    "phone": "444 25 52"
  },
  "status": "out_for_delivery",
  "status_label": "Dağıtımda",
  "headline": "Kargonuz dağıtımda",
  "sender": "Ör*** Ma***",
  "receiver": "Ah*** Yı***",
  "receiver_phone": "0532 *** ** 45",
  "location": {
    "city": "İstanbul",
    "district": "Kadıköy",
    "label": "Kadıköy Şubesi",
    "lat": 40.9903,
    "lng": 29.0292
  },
  "branch": {
    "name": "Kadıköy Şubesi",
    "address": "Caferağa Mah. Moda Cad. No: 112, Kadıköy / İstanbul",
    "phone": "0216 345 00 00",
    "lat": 40.9903,
    "lng": 29.0292
  },
  "events": [
    {
      "at": "2026-11-06T09:14:00+03:00",
      "title": "Kurye dağıtıma çıktı",
      "place": "Kadıköy / İstanbul"
    }
  ]
}
GET

/v1/branches

Kotadan düşmez

Kargo firması (carrier), il (city), ilçe (district) veya şube adı arama (q) parametreleriyle şubelerin adres, telefon, çalışma saatleri ve harita koordinatlarını listeler.

Örnek İstek 
curl -H "Authorization: Bearer kk_live_..." \
     "https://kargokonum.com/v1/branches?carrier=yurtici&city=İstanbul&district=Kadıköy"
POST

/v1/webhooks

Pro ve Limitsiz

Sürekli polling yapmak yerine takip numarasını ve kendi HTTPS uç noktanızı kaydedin. Gönderinin durumu her değiştiğinde sunucunuza POST isteğiyle güncel gönderi verisi iletilir.

Webhook Kayıt İsteği 
curl -X POST "https://kargokonum.com/v1/webhooks" \
     -H "Authorization: Bearer kk_live_..." \
     -H "Content-Type: application/json" \
     -d '{
       "number": "4092817368814",
       "carrier": "aras",
       "url": "https://magazaniz.com/webhooks/kargo",
       "secret": "whsec_kendi_gizli_anahtariniz"
     }'

HMAC imza doğrulama

KargoKonum, gönderdiği ham JSON gövdesini belirlediğiniz secret ile HMAC-SHA256 algoritmasıyla imzalar ve X-KargoKonum-Signature başlığında iletir: 

$gelenImza = $request->header('X-KargoKonum-Signature');
$beklenen  = hash_hmac('sha256', $request->getContent(), $webhookSecret);

abort_unless(hash_equals($beklenen, (string) $gelenImza), 401);

7. Durum ve hata kodları

Standart gönderi durumları (status)

Kod Anlamı
created Gönderi kaydı açıldı / çıkış şubesinden alındı.
at_transfer Aktarma merkezinde veya şehirler arası transfer sürecinde.
arrived_branch Teslimat şubesine ulaştı, dağıtım hazırlığında.
at_branch Şubede alıcının teslim almasını bekliyor veya adreste ulaşılamadı.
out_for_delivery Kurye dağıtıma çıktı, gün içinde teslim edilecek.
delivered Alıcıya veya teslim noktasına teslim edildi.
returned Göndericiye iade sürecinde veya iade edildi.

HTTP yanıt kodları

HTTP Açıklama
200 / 201 İstek başarılı.
401 API anahtarı eksik, hatalı veya iptal edilmiş.
403 İstenen özellik mevcut paketinize dahil değil (ör. Webhook için Pro/Limitsiz gerekir).
404 Kargo firmasında bu takip numarasıyla kayıt bulunamadı.
422 Firma otomatik tespit edilemedi ya da numara birden fazla firmaya uyuyor (candidates dizisi döner).
429 Dakikalık hız sınırı (60/dk) veya paket gönderi kotası doldu.
501 / 502 İlgili kargo firması geçici olarak yanıt vermiyor (kotadan düşmez).