BetakuryeGeliştirici

Başlarken

Hızlı başlangıç

Beş adım: jeton al, restoranı bağla, sipariş gönder, webhook kur, durumu izle. Önce deneme ortamında deneyin; canlıya geçince yalnız kimlik değişir.

  1. Erişim jetonu alın

    Jeton 30 dakika geçerlidir. Süresi dolunca (ya da 401 alınca) yenisini alın; yenileme jetonu yoktur.

    curl -X POST https://betakurye.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"bk_xxxxxxxxxxxx","client_secret":"…"}'
    Yanıt
    {
  "access_token": "eyJhbGciOiJIUzI1NiJ9…",
  "token_type": "Bearer",
  "expires_in": 1800
}

  2. Restoranı eşleme koduyla bağlayın

    external_store_id sizin sisteminizdeki restoran/şube kimliğidir; bundan sonra restoranı hep bununla anarsınız. Eşleme kodu tek kullanımlıktır ve restoranı doğru kurye firmasına bağlar (firma panelde açtığı restoran için kod ürettiyse o kayda bağlanır). Aynı restoranı ikinci kez göndermek kodsuz çalışır, bilgilerini günceller ve 200 döner.

    curl
    curl -X POST https://betakurye.com/v1/stores \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "external_store_id": "lezzet-bostanli",
    "pairing_code": "K7M2Q9",
    "name": "Lezzet Döner Bostanlı",
    "phone": "02323334455",
    "address": { "text": "Cemal Gürsel Cad. No:120, Bostanlı, Karşıyaka", "lat": 38.4601, "lng": 27.0915 }
  }'
    Yanıt · 201
    {
  "id": "6ef5f915-05c4-4900-9f70-ccf86232d580",
  "external_store_id": "lezzet-bostanli",
  "name": "Lezzet Döner Bostanlı",
  "phone": "02323334455",
  "address_text": "Cemal Gürsel Cad. No:120, Bostanlı, Karşıyaka",
  "lat": 38.4601,
  "lng": 27.0915,
  "status": "ACTIVE",
  "courier_company": {
    "id": "7b1e2a40-3c55-4c7e-9b1a-2f3d4e5f6a7b",
    "name": "Betakurye İzmir"
  },
  "created_at": "2026-10-11T13:20:46.976Z",
  "updated_at": "2026-10-11T13:20:46.976Z"
}

  3. Siparişi gönderin

    Idempotency-Key başlığı zorunludur (8–128 karakter): her sipariş için sabit bir değer verin, ör. kendi sipariş numaranız. Yeniden denemede aynı anahtarı gönderin; aynı anahtar ve aynı gövdeyle ikinci istek yeni teslimat açmaz, ilkini 200 ile döner. Koordinat verirseniz sipariş hemen kurye aramaya başlar.

    curl -X POST https://betakurye.com/v1/deliveries \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: SM-48213" \
  -d '{
    "external_ref": "SM-48213",
    "store": { "external_store_id": "lezzet-bostanli" },
    "customer": { "name": "Ayşe Demir", "phone": "05321234567", "note": "Zili çalmayın" },
    "dropoff": {
      "text": "Şehitler Cad. No:12 D:4", "directions": "Eczanenin üstü",
      "neighborhood": "Bostanlı", "district": "Karşıyaka", "city": "İzmir",
      "lat": 38.4701, "lng": 27.1015
    },
    "payment": { "type": "NAKIT", "amount_due": 380, "subtotal": 420, "discount": 40 },
    "items": [ { "name": "Adana Dürüm", "quantity": 2, "total": 360 }, { "name": "Ayran", "quantity": 2, "total": 60 } ],
    "require_pin": true
  }'
    Yanıt · 201 (gerçek yanıttan)
    {
  "id": "c06218cb-638d-488d-a5d2-e368e9c3bd74",
  "external_ref": "SM-48213",
  "store_id": "6ef5f915-05c4-4900-9f70-ccf86232d580",
  "status": "QUEUED",
  "version": 1,
  "courier": null,
  "dropoff": {
    "text": "Şehitler Cad. No:12 D:4 · Eczanenin üstü",
    "lat": 38.4701,
    "lng": 27.1015,
    "source": "pos",
    "ref": null,
    "candidates": null,
    "district": "Karşıyaka",
    "neighborhood": "Bostanlı",
    "city": "İzmir"
  },
  "payment": {
    "type": "NAKIT",
    "amount_due": 380,
    "collected_type": null,
    "subtotal": 420,
    "discount": 40
  },
  "customer": {
    "name": "Ayşe Demir",
    "phone": "+905321234567",
    "phone_extension": null,
    "note": "Zili çalmayın"
  },
  "items": [
    {
      "name": "Adana Dürüm",
      "quantity": 2,
      "total": 360
    },
    {
      "name": "Ayran",
      "quantity": 2,
      "total": 60
    }
  ],
  "scheduled_for": null,
  "notes": null,
  "origin_channel": "pos",
  "package_count": 1,
  "prepaid": false,
  "test": false,
  "fee": null,
  "distance_m": 1412,
  "road_km": 1.9,
  "tracking_url": "https://betakurye.com/t/NwnC4m6V8KVOUJNbXW9CUA",
  "eta_pickup_at": "2026-10-11T13:30:49.068Z",
  "eta_dropoff_at": "2026-10-11T13:38:23.068Z",
  "ready_at": null,
  "assigned_at": null,
  "picked_up_at": null,
  "delivered_at": null,
  "cancelled_at": null,
  "returned_at": null,
  "delivery_pin": "2870",
  "pin_required": true,
  "failure_reason": null,
  "cancel_reason": null,
  "unassigned_alert_at": null,
  "created_at": "2026-10-11T13:20:49.044Z",
  "updated_at": "2026-10-11T13:20:49.044Z"
}

    tracking_url müşteriye iletebileceğiniz canlı takip sayfasıdır. delivery_pin'i (PIN istediyseniz) müşteriye iletin; kurye kapıda ister.

  4. Webhook adresinizi kaydedin

    Adres https olmalı. Yanıttaki secret yalnız bu kez gösterilir; imza doğrulamak için saklayın. Sonra deneme olayı gönderip doğrulamanızı sınayın.

    curl
    curl -X POST https://betakurye.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://pos.ornek.com.tr/betakurye/webhook","description":"Sipariş durumları"}'

# deneme olayı (webhook.test) gönder
curl -X POST https://betakurye.com/v1/webhooks/<id>/test -H "Authorization: Bearer $TOKEN"

    İmza doğrulama örnekleri: Webhook → İmzayı doğrulama.

  5. Durumu izleyin

    Her olay { id, type, timestamp, data } biçiminde gelir; data teslimatın o anki tam hâlidir. Webhook'unuz kapalı kaldıysa kaçırdıklarınızı imleçli listeyle toplayın:

    curl
    # değişenler, eskiden yeniye; yanıttaki next_cursor'ı bir sonraki istekte since= olarak verin
curl "https://betakurye.com/v1/deliveries?limit=100&since=<next_cursor>" -H "Authorization: Bearer $TOKEN"

Sonra