paketpaket

Kurye API Dokümantasyonu

Harici kurye yazılımları bu API ile paketleri listeler, kabul eder, teslim alır ve teslim eder; konum bildirimi ile canlı takip çalışır. Sipariş işletme tarafında kabul edildiğinde paket otomatik olarak en yakın müsait kuryeye teklif edilir.

İşletme API'si mi arıyorsunuz? İşletme API dokümantasyonu

Dış yazılım firmasına iletebileceğiniz tek dosyalık kılavuz (HTML — PDF olarak da kaydedilebilir)

Kimlik doğrulama

Her istek x-api-key başlığıyla gönderilir. Anahtar yönetici tarafından Kurye API ekranından kurye başına üretilir ve yalnızca o kuryenin paketlerine erişir. Anahtar pasifleştirilirse istekler 401 döner.

x-api-key: ppc_2f8a1c…9d31

Uçlar

MetotAdresAçıklama
GET/api/kurye/paketlerBekleyen teklifler ve üzerinizdeki aktif paketler
POST/api/kurye/paketPaketi kabul et, reddet, teslim al veya teslim et
POST/api/kurye/konumKurye konumunu bildir (canlı takip + varış kontrolü)
GET/api/kurye/durumMüsaitlik durumunuzu ve onay bilgisini okur
POST/api/kurye/durumMüsait / meşgul / kapalı durumunu ayarlar

Paket listesi

musait_paketler yanıtlamayı bekleyen tekliflerdir; son_yanit alanı teklifin son geçerlilik saatidir. aktif_paketler üzerinizdeki paketlerdir. Listeyi 10-20 saniyede bir yenileyin.

curl -H "x-api-key: <KURYE_ANAHTARINIZ>" \ https://paketpaket.base44.app/api/kurye/paketler # Yanıt { "kurye": { "kurye_id": "6a1f…", "ad": "Mehmet K.", "durum": "available", "onayli": true }, "es_zamanli_limit": 5, "musait_paketler": [ { "teklif_id": "9c2ab7…", "siparis_id": "5f0c12…", "siparis_no": "PK8K2M4Q", "durum": "preparing", "durum_etiketi": "Hazırlanıyor", "isletme": { "ad": "Moda Pizza", "adres": "Caferağa Mah. Moda Cad. No: 12, Kadıköy", "enlem": 40.9876, "boylam": 29.0254 }, "musteri": { "ad": "Ayşe Yılmaz", "telefon": "055 *** 33" }, "teslimat_adresi": "Osmanağa Mah. Söğütlüçeşme Cad. No: 5 D:7", "teslimat_konum": { "enlem": 40.9901, "boylam": 29.0287 }, "tutar": 245.5, "odeme": { "yontem": "cash", "durum": "pending", "kapida_tahsilat": true }, "kalem_sayisi": 2, "kalemler": [{ "ad": "Karışık Pizza", "adet": 1, "secenekler": ["İnce Hamur"] }], "not": "Kapı zilini çalmayın", "hazir_saat": "2026-11-12T13:25:00.000Z", "mesafe_km": 1.8, "son_yanit": "2026-11-12T13:15:00.000Z" } ], "aktif_paketler": [] }
  • Müşteri telefonu gizlilik gereği maskeli döner (055 *** 33).
  • odeme.kapida_tahsilat true ise tutar kapıda tahsil edilir.
  • hazir_saat: paketin işletmede hazır olacağı saat.
  • Aynı anda taşınabilecek paket sayısı es_zamanli_limit alanındadır.

Paket işlemleri

Kabul ve red teklif_id ile; teslim alma ve teslim etme siparis_no veya siparis_id ile yapılır. Teslim alındığında sipariş “Yolda” olur, teslim edildiğinde kapanır ve müşteriye bilgi gider.

# Paketi kabul et (teklif_id ile) curl -X POST https://paketpaket.base44.app/api/kurye/paket \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "islem": "kabul", "teklif_id": "9c2ab7…" }' # Paketi reddet — sıradaki kuryeye aktarılır curl -X POST https://paketpaket.base44.app/api/kurye/paket \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "islem": "red", "teklif_id": "9c2ab7…" }' # Paketi işletmeden teslim al (sipariş "Yolda" olur) curl -X POST https://paketpaket.base44.app/api/kurye/paket \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "islem": "teslim_al", "siparis_no": "PK8K2M4Q" }' # Paketi teslim et curl -X POST https://paketpaket.base44.app/api/kurye/paket \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "islem": "teslim", "siparis_no": "PK8K2M4Q" }'

Konum bildirimi

Kurye konumu canlı takip ekranında gösterilir. Konum, teslim adresine 100 m yaklaştığında varış damgalanır; 3 dakika içinde teslim edilmezse sipariş otomatik olarak teslim edildi sayılır.

# Konum bildirimi — 15-30 saniyede bir gönderin curl -X POST https://paketpaket.base44.app/api/kurye/konum \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "enlem": 40.9901, "boylam": 29.0287, "hassasiyet": 12 }' # Yanıt: { "basarili": true, "kayit_zamani": "…", "otomatik_teslim": [] }

Müsaitlik durumu

Teklifler yalnızca müsait kuryelere gönderilir. Yönetici onayı bekleyen kurye müsait olamaz.

# Müsait ol (paket teklifi almak için) curl -X POST https://paketpaket.base44.app/api/kurye/durum \ -H "Content-Type: application/json" \ -H "x-api-key: <KURYE_ANAHTARINIZ>" \ -d '{ "durum": "musait" }' # Diğer değerler: "mesgul", "kapali"

Yeni paket webhook'u

Kuryeye yeni paket teklif edildiğinde, panelde tanımlı webhook adresine imzalı bir gönderim yapılır (paket.yeni). Adres yönetici tarafından Kurye API ekranından anahtarın yanındaki webhook düğmesiyle tanımlanır. Gönderim 8 saniye içinde yanıtlanmazsa başarısız sayılır; paket akışı bundan etkilenmez ve son gönderim sonucu panelde görünür.

POST https://kurye.sirketim.com/paketpaket Content-Type: application/json x-pp-event: paket.yeni x-pp-signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 x-pp-delivery: 4f1c1a1e-8f0e-4a3f-9a1f-2c5a1e6b7d10 { "olay": "paket.yeni", "gonderim_zamani": "2026-11-12T13:14:02.000Z", "veri": { "teklif_id": "9c2ab7…", "siparis_no": "PK8K2M4Q", "durum": "preparing", "isletme": { "ad": "Moda Pizza", "adres": "Caferağa Mah. …", "enlem": 40.9876, "boylam": 29.0254 }, "musteri": { "ad": "Ayşe Yılmaz", "telefon": "055 *** 33" }, "teslimat_adresi": "Osmanağa Mah. …", "teslimat_konum": { "enlem": 40.9901, "boylam": 29.0287 }, "tutar": 245.5, "odeme": { "yontem": "cash", "durum": "pending", "kapida_tahsilat": true }, "hazir_saat": "2026-11-12T13:25:00.000Z", "mesafe_km": 1.8, "son_yanit": "2026-11-12T13:15:00.000Z" } }

x-pp-signature, gövdenin webhook imza anahtarıyla hesaplanmış HMAC-SHA256 özetidir (hex). Doğrulama örneği:

// Node.js / benzeri ortam const crypto = require("crypto"); // body: ham istek gövdesi (JSON.parse ETMEDEN), secret: panelde gösterilen imza anahtarı const beklenen = crypto .createHmac("sha256", secret) .update(body) .digest("hex"); if (beklenen !== req.headers["x-pp-signature"]) { return res.status(401).end(); // imza uyuşmuyor } const { olay, veri } = JSON.parse(body);

Hata yanıtları

  • 200 işlem alındı
  • 400 alan hatası — hata alanında açıklama
  • 401 geçersiz veya pasif x-api-key
  • 403 kurye onayı yok ya da paket size atanmamış
  • 404 anahtara bağlı kurye veya paket bulunamadı
  • 409 teklifin süresi doldu, paket başkasına atandı veya kapasite dolu