Geliştiriciler için

İş ortağı API'si

Kendi sisteminden teklif al, gönderi oluştur, listele, durumunu sorgula ve iptal et. Beş uç, tek anahtar, her yanıtta aynı zarf.

Kimlik ve adres

Her istek, firmana özel API anahtarını X-Api-Key başlığında taşır. Onaylı kurumsal hesap yöneticileri anahtarı gönderici panelinden kendileri üretir (en çok 5 etkin anahtar); düz metin yalnız bir kez gösterilir, biz yalnız özetini saklarız. Anahtarı sunucunda tut, uygulamaya ya da tarayıcıya gömme.

Anahtar mı lazım?Panel › Firma › API anahtarları. Hesabın yoksa önce kurumsal başvuru yap.
Anahtar üretBaşvuru yap
Taban adres  https://dronkargom.com/api/partner/v1
Başlıklar    X-Api-Key: dkp_<önek>.<gizli>
             Content-Type: application/json
             Accept: application/json
  • Tüm yanıtlar aynı zarfı kullanır: başarılıysa {"ok": true, "data": …}, değilse {"ok": false, "error": …}.
  • Tutarlar kuruş cinsinden tamsayıdır (KDV dahil); süreler saniye, mesafeler metre.
  • Gönderiler firmanın cari hesabına yazılır; ay sonunda tek fatura kesilir.
POST

/quotes

İki nokta ve paket boyu için Standart ve Ekspres teklif alır. Teklif 5 dakika geçerlidir; gönderi yalnız teklif kimliğiyle oluşturulur, böylece tutar sunucuda sabitlenir. Sözleşme indirimin varsa teklife otomatik uygulanır.

İstek
{
  "from": { "lat": <enlem>, "lng": <boylam>, "label": "Depo" },
  "to":   { "lat": <enlem>, "lng": <boylam>, "label": "Mağaza" },
  "tier": "kucuk"   // zarf · kucuk · orta · buyuk
}
Yanıt · 200
{
  "ok": true,
  "data": {
    "id": <teklif kimliği>,
    "distance_m": <metre>,
    "options": [
      { "service": "standard", "price_kurus": <kuruş>,
        "eta_seconds": <saniye>, "breakdown": [ … ] },
      { "service": "express", … }
    ],
    "expires_at": <ISO 8601>
  }
}
POST

/shipments

Teklifi gönderiye çevirir. Yanıttaki tracking_url alıcıya iletilecek takip bağlantısıdır; delivery_pin ise alıcının teslimde gireceği 4 haneli koddur — yalnız alıcıyla paylaş. reference alanına kendi sipariş numaranı yazabilirsin.

İstek
{
  "quote_id": <teklif kimliği>,
  "service": "standard",      // ya da "express"
  "recipient_name": <alıcı adı>,
  "recipient_phone": <isteğe bağlı>,
  "to_note": <teslim notu, isteğe bağlı>,
  "reference": <sipariş no, isteğe bağlı>,
  "cost_center": <masraf merkezi, isteğe bağlı>
}
Yanıt · 200
{
  "ok": true,
  "data": {
    "code": "DK"<8 karakter>,
    "status": "confirmed",
    "tracking_url": <alıcı takip bağlantısı>,
    "delivery_pin": <4 hane>,
    "price_kurus": <kuruş>,
    "eta_at": <ISO 8601>
  }
}
GET

/shipments

Firmanın tüm gönderileri (panelden, uygulamadan ya da API'den açılmış olsun), yeniden eskiye. Sayfalama imleçle: yanıttaki next_cursor değerini bir sonraki istekte cursor olarak gönder. Süzgeçler: status, reference; limit en çok 100.

GET /shipments?limit=50&status=delivered&reference=<sipariş no>

{
  "ok": true,
  "data": {
    "items": [ { "code": <gönderi kodu>, "status": "delivered", "reference": <sipariş no>, "price_kurus": <kuruş>, … } ],
    "next_cursor": <sayı ya da null>
  }
}
GET

/shipments/{kod}

Firmana ait bir gönderinin durumunu ve hareket geçmişini döner. Yalnız kendi gönderilerini görebilirsin.

{
  "ok": true,
  "data": {
    "code": <gönderi kodu>,
    "status": "in_flight",   // confirmed → assigned → to_pickup → at_pickup → in_flight → arriving → at_dropoff → delivered
    "status_label": "Yolda",
    "eta_at": <ISO 8601>,
    "events": [ { "type": "status", "to": "assigned", "label": "Dron atandı", "at": <ISO 8601> }, … ]
  }
}
POST

/shipments/{kod}/cancel

Gönderiyi iptal eder; kurallar uygulamayla aynıdır: dron atanmadan önce ücretsiz, atandıktan sonra iptal ücreti, paket dronda iken iptal edilemez (DK_CANCEL_NOT_ALLOWED). Gövdede isteğe bağlı reason.

{ "reason": <isteğe bağlı açıklama> }

Hata zarfı

Hatalar her zaman aynı biçimde döner; code alanı makine içindir, message Türkçe ve kullanıcıya gösterilebilir.

{
  "ok": false,
  "error": { "code": "DK_QUOTE_EXPIRED", "message": "Teklifin süresi doldu. Fiyatı yenileyip tekrar dene.", "details": null }
}
KodHTTPNe zaman
AUTH_PARTNER401Anahtar yok, hatalı ya da iptal edilmiş; firma hesabı aktif değil.
VALIDATION422Eksik ya da geçersiz alan; ayrıntı details.errors içinde.
DK_OUT_OF_SERVICE_AREA422Adres planlama bölgesi dışında (details.side: from / to).
DK_NO_FLY_ENDPOINT422Uç nokta uçuşa kapalı bir alanda.
DK_WEATHER_CLOSED409Hava koşulları nedeniyle şu an uçuş açılmıyor.
DK_QUOTE_EXPIRED409Teklifin 5 dakikalık süresi doldu; yeni teklif al.
DK_NO_DRONE_AVAILABLE409Ekspres için boşta dron yok; Standart'ı dene.
DK_CREDIT_LIMIT_EXCEEDED409Firmanın aylık cari limiti doldu.
NOT_FOUND404Teklif ya da gönderi bulunamadı (başka firmanın gönderisi de bu kodu döner).
—429Hız sınırı aşıldı; biraz bekleyip yeniden dene.

Bu arayüz ilk sürümdedir; web kancaları (webhook) sonraki sürümde. Toplu gönderi için gönderici panelindeki CSV yüklemesini kullanabilirsin.

Anahtar mı lazım?

Onaylı kurumsal hesap yöneticileri anahtarı panelden kendileri üretir. Hesabın yoksa önce kurumsal başvurunu bırak.