İçeriğe geç
KuryeSoft

Başlarken

Kimlik doğrulama

Her istek, kurye firmanızın panelden oluşturduğu bir API anahtarıyla imzalanır. Oturum, çerez ya da OAuth yoktur.

Anahtarı göndermek

Anahtarı her istekte X-Api-Key başlığında gönderin. Kullandığınız HTTP kütüphanesi yalnızca Authorization başlığını destekliyorsa aynı anahtar Bearer biçiminde de kabul edilir:

curl "https://kurye.firmaniz.com/api/v1/ping" -H "X-Api-Key: ks_ANAHTARINIZ"

curl "https://kurye.firmaniz.com/api/v1/ping" -H "Authorization: Bearer ks_ANAHTARINIZ"

Anahtar her zaman ks_ ile başlar ve 43 karakterdir. İstekler yalnızca HTTPS üzerinden yapılır.

Anahtar türleri

Kurye firmasının yöneticisi anahtarı oluştururken onu bir işletmeye bağlayabilir ya da firma geneli bırakabilir:

İşletmeye bağlı
Siparişler hangi işletmeye yazılır:Her zaman anahtarın işletmesine. Gövdedeki restaurant_id / restaurant_code yok sayılır.
Hangi siparişleri görür:Yalnızca o işletmenin siparişlerini. Başka işletmenin siparişi 404 döner.
Firma geneli
Siparişler hangi işletmeye yazılır:Her POST /orders ve POST /quote isteğinde restaurant_id ya da restaurant_code gönderilir; gönderilmezse 422.
Hangi siparişleri görür:Firmanın bütün işletmelerinin siparişlerini.

Bir işletmenin kendi POS'u ya da sitesi için işletmeye bağlı anahtar kullanın. Firma geneli anahtar, birden çok işletmeye sipariş aktaran yazılımlar (zincir restoran merkezi, çağrı merkezi, toplu sipariş platformu) içindir. Anahtarın türünü GET /ping yanıtındaki restaurant_id ile öğrenebilirsiniz.

Anahtarın oluşturulması ve yönetimi

Anahtarları yalnızca kurye firmasının yetkili yöneticisi yönetir: panelde Ayarlar → API Anahtarları ve Webhook → API Anahtarları. İşletme kullanıcıları ve geliştiriciler anahtar oluşturamaz.

  • Bir kez gösterilir. Sistem anahtarın yalnızca özetini saklar; kaybedilen anahtar geri getirilemez, yenisi oluşturulur.
  • Son kullanım panelde görünür (en çok dakikada bir güncellenir); kullanılmayan anahtarları bununla ayıklayabilirsiniz.
  • Pasif yapma ve silme hemen etkili olur: sonraki istek 401 API_KEY_INVALID alır.

Anahtarı yenilemek

Kesintisiz yenilemek için:

  1. Kurye firmanızdan yeni bir anahtar isteyin (eskisi çalışmaya devam eder).
  2. Yeni anahtarı sisteminize yükleyin ve bir istekle sınayın.
  3. Eski anahtarı pasif yaptırın ya da sildirin.

Güvenli kullanım

Anahtar yalnızca sunucunuzda durur

API anahtarı, işletme adına sipariş açma ve iptal etme yetkisi verir. Tarayıcıda çalışan koda, mobil uygulamaya ya da herkese açık bir depoya koymayın. Tarayıcıdan yapılan istekler zaten engellenir (CORS); müşterinin cihazı sizin sunucunuzla, sizin sunucunuz KuryeSoft ile konuşmalıdır.

  • Anahtarı ortam değişkeninde ya da gizli bilgi yöneticisinde (secret manager) saklayın; kaynak koduna yazmayın.
  • Anahtarı günlüklere (log) yazmayın. Hata ayıklarken ilk 8 karakteri yeterlidir; panel de anahtarı bu ön ekle gösterir.
  • Her yazılım ya da kurulum için ayrı anahtar isteyin: biri sızarsa yalnızca o kapatılır.
  • Anahtarın sızdığından şüphelenirseniz hemen kurye firmanıza pasif yaptırın.

Kimlik hataları

401 · application/json
{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "API anahtarı geçersiz"
  }
}
API_KEY_REQUIRED
Ne zaman:Başlık yok ya da değer ks_ ile başlamıyor.
API_KEY_INVALID
Ne zaman:Anahtar yanlış, silinmiş ya da pasif. Aynı anahtarla yeniden denemek işe yaramaz.