İçeriğe geç
KuryeSoft

Başlarken

Hızlı başlangıç

Beş adımda: anahtarı alın, bağlantıyı sınayın, ilk siparişi gönderin, durumu izleyin ve deneme siparişini iptal edin.

Deneme siparişleri gerçek kuryelere gider

Ayrı bir deneme ortamı yoktur: gönderdiğiniz sipariş kurye firmasının canlı sistemine düşer ve kuryelere teklif edilir. Geliştirme sırasında kurye firmanızdan bir deneme işletmesi ve ona bağlı bir anahtar isteyin, denemeleri firmayla önceden konuşun ve her deneme siparişini işiniz bitince iptal edin (5. adım).

  1. API anahtarınızı alın

    Anahtarı kurye firmanızın yöneticisi oluşturur: panelde Ayarlar → API Anahtarları ve Webhook → API Anahtarları. Anahtar ks_ ile başlar ve yalnızca oluşturulduğu anda bir kez gösterilir; size güvenli bir kanaldan iletilmelidir.

    Anahtarı bir işletmeye bağlamak en kolayıdır: siparişler kendiliğinden o işletmeye yazılır. Firma geneli anahtarla her siparişte işletmeyi belirtirsiniz. Ayrıntı: Kimlik doğrulama.

    Firmanın sunucu adresini de alın ve aşağıya yazın; bu sayfadaki örnekler sizin adresinizle gösterilir:

    Örnek kodlardaki adres sizinkiyle değişir. Adres yalnızca bu tarayıcıda saklanır; hiçbir yere gönderilmez.

  2. Bağlantıyı sınayın

    Anahtarı ortam değişkenine koyun (örnek kodlar oradan okur) ve ilk isteği gönderin:

    bash
    export KURYESOFT_API_KEY="ks_..."
    curl "https://kurye.firmaniz.com/api/v1/ping" \
      -H "X-Api-Key: $KURYESOFT_API_KEY"

    Yanıt anahtarın adını ve bağlı olduğu işletmeyi verir:

    200 · application/json
    {
      "ok": true,
      "key": "Kasa POS",
      "restaurant_id": 1
    }

    401 API_KEY_INVALID alırsanız anahtar yanlış kopyalanmış ya da pasif yapılmıştır.

  3. İlk siparişinizi gönderin

    Zorunlu olanlar external_id (sizin sipariş kimliğiniz) ve address. Konumu (lat, lng) mutlaka gönderin: mesafe, ücret ve kurye ataması konuma göre yapılır.

    curl -X POST "https://kurye.firmaniz.com/api/v1/orders" \
      -H "X-Api-Key: $KURYESOFT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "external_id": "DENEME-1",
        "customer": {
          "name": "Deneme Müşteri",
          "phone": "05321234567"
        },
        "address": {
          "text": "Caferağa Mah. Moda Cad. No:12 Kadıköy",
          "lat": 40.9969,
          "lng": 29.0342
        },
        "payment": {
          "kind": "cash"
        },
        "total_amount": 150
      }'

    Yanıt 201 Created ile oluşturulan siparişi döndürür. id değerini kendi kaydınızda saklayın; webhook'larda sipariş bu kimlikle gelir.

    201 · application/json
    {
      "id": 1842,
      "code": "2611200042",
      "external_id": "DENEME-1",
      "status": "pending",
      "status_label": "Bekliyor",
      "restaurant_id": 1,
      "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
      "courier": null,
      "distance_m": 1754,
      "eta_at": null,
      "delivery_fee": 70,
      "total_amount": 150,
      "collect_amount": 150,
      "created_at": "2026-11-20T18:10:32.000Z",
      "assigned_at": null,
      "picked_up_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "cancel_reason": null
    }
    İpucu:

    İstek zaman aşımına uğrarsa aynı gövdeyle tekrar gönderin: aynı external_id ikinci bir sipariş açmaz, mevcut siparişi döndürür.

  4. Durumu izleyin

    İki yol var; canlı kullanımda ikisini birlikte kullanın:

    • Webhook (önerilen): kurye firmanızdan, panelde Webhook'lar sekmesine sizin adresinizi eklemesini isteyin. Sipariş her durum değiştirdiğinde adresinize imzalı bir POST isteği gelir. Bkz. Webhook'lar.
    • Sorgu: son durumu her zaman GET /orders/ext:DENEME-1 ile alabilirsiniz.
    curl "https://kurye.firmaniz.com/api/v1/orders/ext:DENEME-1" \
      -H "X-Api-Key: $KURYESOFT_API_KEY"
  5. Deneme siparişini iptal edin

    Sipariş bir kuryeye gitmeden iptal edin:

    curl -X POST "https://kurye.firmaniz.com/api/v1/orders/ext:DENEME-1/cancel" \
      -H "X-Api-Key: $KURYESOFT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "reason": "Entegrasyon denemesi"
      }'

    Kurye işletmeye vardıktan sonra işletme adına iptal yapılamaz (403); o durumda kurye firmasına haber verin.

Sonraki adımlar