Kurye API

İşletmenin bağladığı kurye firması bu API ile kendisine gelen siparişleri okur, kuryesini ve kuryenin konumunu bildirir, siparişi teslim alır ve teslim eder. Kuryelerinizin Söyle Gelir'de kayıtlı olması gerekmez: kurye kendi yazılımınızdadır, siparişe yalnız adı, telefonu ve konumu yazılır.

• Taban adres: https://soylegelir.com/api/v1/courier
• Kimlik: işletmenin verdiği iki anahtar, X-Api-Key + X-Api-Secret (Kimlik doğrulama).
• Hız sınırı: bağlantı başına dakikada 240 istek.

Akış#

1. Sipariş gelir. İşletme bir teslimat siparişini onayladığı anda sipariş firmanıza geçer ve bildirim adresinize order.assigned gider. Bildirim adresiniz yoksa GET /orders ile düzenli çekin.
2. Kuryeyi bildirin. POST /orders/{number}/courier: müşteri kuryesinin adını, işletme adını ve telefonunu görür.
3. Teslim alın. POST /orders/{number}/status {"action": "pick_up"}. Sipariş yola çıkar.
4. Konum gönderin. POST /locations (toplu): müşteri kuryeyi haritada izler.
5. Teslim edin. {"action": "deliver", "pin": "<teslim kodu>"}. Teslim kodunu müşteri verir; kodsuz teslim yapılamaz. Teslim edilemezse {"action": "fail", "note": "<gerekçe>"}.

Kurye bulamazsanız siparişi teslim almadan önce POST /orders/{number}/release ile işletmeye geri verin; işletme kendi kuryesini atar.

Uçlar#

Sipariş nesnesi#

{
  "number": "SG261114GCCE",
  "status": "accepted",
  "assigned": true,
  "store": {
    "id": 1, "name": "Pamukkale Kebap", "phone": "+902580000000",
    "address": "Sırakapılar Mah., Saltak Cad. No: 24", "district": "Merkezefendi", "city": "Denizli",
    "lat": 37.778556, "lng": 29.082223
  },
  "dropoff": {
    "title": "Ev", "city": "Denizli", "district": "Merkezefendi", "neighborhood": "Sırakapılar",
    "street": "Saltak Cad.", "building": "12", "floor": "3", "apartment": "7", "directions": "Yeşil kapı",
    "line": "Sırakapılar Mah., Saltak Cad., No: 12, Kat: 3, Daire: 7 — Merkezefendi/Denizli",
    "lat": 37.779539, "lng": 29.079447
  },
  "customer": { "name": "Ayşe Yılmaz", "phone": "+905321234567" },
  "note": "Zili çalmayın",
  "items": [{ "name": "Karışık Pide", "quantity": 1, "unit": "adet" }],
  "payment": { "method": "cash", "collect_on_delivery": true, "amount_to_collect": 25000 },
  "delivery_fee": 1500,
  "total": 25000,
  "courier": { "name": "Ali Demir", "phone": "+905321112233" },
  "scheduled_for": null,
  "accepted_at": "2026-11-14T12:01:00+00:00",
  "ready_at": null,
  "picked_up_at": null,
  "delivered_at": null,
  "created_at": "2026-11-14T12:00:00+00:00",
  "updated_at": "2026-11-14T12:02:00+00:00",
  "currency": "TRY",
  "amounts_in": "kurus"
}

İşletme#

GET /api/v1/courier/store

Yanıt: {"data": {"id", "name", "phone", "address", "district", "city", "lat", "lng", "status"}}. status: open, busy ya da closed.

Siparişler#

GET /api/v1/courier/orders?since=2026-11-14T12:00:00Z

Firmanıza gönderilen siparişler (geçmiş dahil), en yeni başta, en çok 100 kayıt. status ve since süzgeçleri işletme API'sindeki gibidir. Tek sipariş: GET /orders/{number}; firmanızda olmayan sipariş 404.

Kurye bilgisi#

POST /api/v1/courier/orders/{number}/courier
Content-Type: application/json

{ "courier_name": "Ali Demir", "courier_phone": "+905321112233" }

En az biri gönderilir; yalnız gönderilen alan değişir, null gönderilen silinir. Kapanmış siparişte 422 (errors.order).

Taşıma adımları#

POST /api/v1/courier/orders/{number}/status
Content-Type: application/json

{ "action": "pick_up", "lat": 37.7790, "lng": 29.0810 }

lat ve lng isteğe bağlıdır (ikisi birlikte); verilirse kuryenin konumu da güncellenir.

Siparişi geri verme#

POST /api/v1/courier/orders/{number}/release
Content-Type: application/json

{ "note": "Bölgede kurye yok" }

Yalnız teslim alınmadan. Sipariş firmanızdan çıkar, işletme kendi kuryesini atar; note sipariş geçmişine yazılır. Yanıt: {"data": {"number": "…", "released": true}}. Yoldaki sipariş geri verilemez (422); bu arada işletme geri aldıysa 409.

Kurye konumları#

POST /api/v1/courier/locations
Content-Type: application/json

{
  "items": [
    { "number": "SG261114GCCE", "lat": 37.7793, "lng": 29.0801 },
    { "number": "SG261114HXQA", "lat": 37.7651, "lng": 29.0912 }
  ]
}

Tek istekte en çok 100 sipariş. Yalnız firmanızdaki açık siparişler güncellenir; öbür numaralar skipped içinde döner (hata değildir: sipariş bu arada teslim edilmiş olabilir).

{ "data": { "updated": 1, "skipped": ["SG261114HXQA"] } }

Konumu 10–30 saniyede bir göndermeniz yeterlidir; müşterinin haritası birkaç saniyede bir yenilenir ve gönderdiğiniz son konumu gösterir.

Bilmeniz gerekenler#

• Ne zaman gelir: Yalnız teslimat siparişleri, işletme onayladığı anda, bir kez. Gel al ve restoranda siparişler gelmez.
• İşletme geri alabilir: İşletme kendi kuryesini atarsa sipariş firmanızdan çıkar; size order.released gider ve sipariş GET /orders/{number} ile artık görünmez.
• İptal: İşletme siparişi iptal ederse size order.status.changed (to: "cancelled") gider.
• Bağlantı kaldırılırsa: anahtarlarınız hemen çalışmaz; firmanızdaki, henüz teslim alınmamış siparişler işletmeye döner.