İş 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.
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.
/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.
{
"from": { "lat": <enlem>, "lng": <boylam>, "label": "Depo" },
"to": { "lat": <enlem>, "lng": <boylam>, "label": "Mağaza" },
"tier": "kucuk" // zarf · kucuk · orta · buyuk
}{
"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>
}
}/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.
{
"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ı>
}{
"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>
}
}/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>
}
}
/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> }, … ]
}
}
/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 }
}
| Kod | HTTP | Ne zaman |
|---|---|---|
AUTH_PARTNER | 401 | Anahtar yok, hatalı ya da iptal edilmiş; firma hesabı aktif değil. |
VALIDATION | 422 | Eksik ya da geçersiz alan; ayrıntı details.errors içinde. |
DK_OUT_OF_SERVICE_AREA | 422 | Adres planlama bölgesi dışında (details.side: from / to). |
DK_NO_FLY_ENDPOINT | 422 | Uç nokta uçuşa kapalı bir alanda. |
DK_WEATHER_CLOSED | 409 | Hava koşulları nedeniyle şu an uçuş açılmıyor. |
DK_QUOTE_EXPIRED | 409 | Teklifin 5 dakikalık süresi doldu; yeni teklif al. |
DK_NO_DRONE_AVAILABLE | 409 | Ekspres için boşta dron yok; Standart'ı dene. |
DK_CREDIT_LIMIT_EXCEEDED | 409 | Firmanın aylık cari limiti doldu. |
NOT_FOUND | 404 | Teklif ya da gönderi bulunamadı (başka firmanın gönderisi de bu kodu döner). |
| — | 429 | Hı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.