Piyyuu REST API v1

API Dökümantasyonu

Kendi e-ticaret sitenizi, mobil uygulamanızı veya adisyon sisteminizi Piyyuu ağına entegre edin. Siparişleri otomatik aktarın ve kurye atama süreçlerini anlık olarak yönetin.

Kimlik Doğrulama

Piyyuu API'sine yapılan tüm isteklerin başlık (Header) kısmında geçerli bir API anahtarı barındırması gerekir. API anahtarınızı restoran panelindeki entegrasyonlar sayfasından alabilirsiniz.

HTTP HEADERS

X-API-Key: your_api_key_here

Content-Type: application/json

Sipariş Oluşturma

Yeni bir teslimat siparişi oluşturmak ve akıllı atama havuzuna dahil etmek için aşağıdaki endpoint'i kullanın.

POST/api/v1/orders

Request Body (JSON)

{
  "branch_id": "br_981723",
  "order_number": "P-48912",
  "customer": {
    "name": "Ahmet Yılmaz",
    "phone": "+905551234567",
    "address": "Kadıköy Merkez Mah. Rıhtım Cad. No:12 D:4 Istanbul"
  },
  "items": [
    { "name": "Margarita Pizza", "quantity": 1, "price": 280.00 },
    { "name": "Kola 330ml", "quantity": 1, "price": 45.00 }
  ],
  "total_amount": 325.00,
  "payment_method": "ONLINE",
  "notes": "Zil çalmayın, kapıya bırakın."
}

Response (201 Created)

{
  "status": "success",
  "order_id": "ord_8829104",
  "assigned_courier": {
    "id": "cr_0029",
    "name": "Mehmet Demir",
    "phone": "+905329876543"
  },
  "estimated_delivery_time": "25-35 mins",
  "created_at": "2026-06-27T16:15:00Z"
}

Kurye Durum Sorgulama

Aktif sipariş teslimatında olan kuryenin anlık koordinatlarını, durumunu ve batarya seviyesini sorgulamak için kullanılır.

GET/api/v1/couriers/{courier_id}/status

Response (200 OK)

{
  "courier_id": "cr_0029",
  "name": "Mehmet Demir",
  "status": "DELIVERING",
  "location": {
    "latitude": 41.0082,
    "longitude": 28.9784
  },
  "current_order_id": "ord_8829104",
  "battery_level": 82
}

Webhook Bildirimleri

Sipariş durumları değiştikçe sistemimiz belirttiğiniz Webhook URL'ine anlık POST istekleri gönderir. Bu sayede polling yapmadan sipariş süreçlerinizi senkronize edebilirsiniz.

Desteklenen Webhook Olayları:

order.assigned - Kurye siparişi kabul ettiğinde tetiklenir.
order.picked_up - Kurye siparişi şubeden alıp yola çıktığında tetiklenir.
order.delivered - Sipariş başarıyla teslim edildiğinde tetiklenir.
order.cancelled - Sipariş iptal edildiğinde tetiklenir.