Başlangıç

Bu sayfa, kimlik bilgilerinin alınmasından ilk teslimatın tamamlanmasına kadar olan adımları sırasıyla açıklar. Adımların tamamı test ortamında yürütülür; gerçek bir kurye görevlendirilmez.

1. Token alın

Gizli anahtar yalnızca token almak için kullanılır. Token bir saat geçerlidir ve sonraki tüm isteklere eklenir.

POST https://gw.hizliyo.com/api/vendor/v1/token
Content-Type: application/json

{
  "clientId": "istemci-kimliginiz",
  "clientSecret": "hzl_test_..."
}

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

Token'ı saklayın ve geçerlilik süresi dolmadan beş dakika önce yenileyin. Gerekçesi Kimlik doğrulama sayfasında açıklanmıştır.

2. Mağaza kaydedin

Mağaza, bir restoran şubesini temsil eder. Şube bir kez kaydedilir; bilgileri değiştikçe aynı uç noktadan güncellenir. Kayıt sizin kendi mağaza numaranız üzerinden yürütülür, Hızlıyo'nun ürettiği kimliği saklamanız gerekmez.

PUT /api/vendor/v1/stores/ADS-34781
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "taxNumber": "1234567890",
  "name": "Öncü Döner · Kızılay",
  "phone": "5321234567",
  "address": {
    "text": "Meşrutiyet Cad. No:12/A, Kızılay, Çankaya/Ankara",
    "latitude": 39.920778,
    "longitude": 32.854110
  }
}

Kurye şirketi henüz seçilmediği için yanıtta, bu adrese hizmet veren şirketler listelenir:

{
  "success": true,
  "data": {
    "status": "AwaitingFleet",
    "subRegion": "Çankaya · Kızılay",
    "availableFleets": [
      {
        "fleetId": "9d41c7a2-5b83-4e10-91cc-72f0ab3d5e64",
        "name": "Başkent Moto Kurye",
        "status": "Available",
        "avgDeliveryMinutes": 27
      }
    ]
  }
}

3. Kurye şirketini bağlayın

Restoran, listelenen şirketlerden biriyle görüşür; fiyat, ödeme günü ve hizmet verilecek bölgeler taraflar arasında belirlenir. Hızlıyo bu görüşmenin tarafı değildir. Anlaşma sonuçlandığında aynı uç nokta, bu kez fleetId alanı eklenerek çağrılır.

PUT /api/vendor/v1/stores/ADS-34781

{
  "taxNumber": "1234567890",
  "name": "Öncü Döner · Kızılay",
  "phone": "5321234567",
  "address": { "text": "...", "latitude": 39.920778, "longitude": 32.854110 },
  "fleetId": "9d41c7a2-5b83-4e10-91cc-72f0ab3d5e64"
}

Mağaza AwaitingFleetApproval durumuna geçer. Kurye şirketi onay verdiğinde durum Active olur ve tarafınıza store.activated bildirimi iletilir.

4. Sipariş gönderin

POST /api/vendor/v1/orders
Authorization: Bearer eyJhbGciOi...
X-Idempotency-Key: ADS-ORD-99213
Content-Type: application/json

{
  "externalStoreId": "ADS-34781",
  "externalOrderId": "ADS-ORD-99213",
  "orderedAt": "2026-08-04T18:42:11+03:00",
  "readyAt": "2026-08-04T18:57:00+03:00",
  "recipient": {
    "name": "Merve Yıldırım",
    "phone": "5339876543"
  },
  "dropoff": {
    "text": "Cemal Gürsel Cad. No:45 D:8, Kurtuluş, Çankaya/Ankara",
    "latitude": 39.925310,
    "longitude": 32.862440,
    "buildingNo": "45",
    "doorNo": "8",
    "floor": "3",
    "note": "Zil çalışmıyor, kapıyı çalın"
  },
  "packageNote": "2 dürüm, 1 ayran",
  "orderAmount": 480.00,
  "payment": {
    "type": "Cash",
    "collectionAmount": 480.00
  }
}

{
  "success": true,
  "data": {
    "orderId": "e5a9f0d3-7c21-4b88-a06e-3f9182bd4471",
    "externalOrderId": "ADS-ORD-99213",
    "status": "Searching",
    "fleet": { "fleetId": "9d41...5e64", "name": "Başkent Moto Kurye" },
    "trackingUrl": "https://takip.hizliyo.com/d/8fK2mQ",
    "estimatedPickupAt": "2026-08-04T18:59:00+03:00"
  }
}

Yanıttaki orderId değerini saklayın. Durum sorgusu ve iptal işlemleri bu değerle yapılır.

Sipariş isteği tek seferliktir

Başarısız olan istek başarısız kalır; Hızlıyo arka planda yeniden denemez. Teslimat zamana duyarlı bir süreçtir. On dakika sonra kendiliğinden yeniden oluşan bir sipariş, hiç oluşmamasından daha olumsuz sonuç doğurur. İsteğin yeniden gönderilip gönderilmeyeceğine siz karar verirsiniz. Bkz. Siparişler.

5. Durum bildirimlerini alın

Tanımladığınız adrese, her durum değişikliği imzalanarak iletilir. Durum takibinin asıl yöntemi budur; sorgulama yalnızca yedek yöntemdir.

{
  "eventId": "01J9XK4M2T7QW3ZR8B6N5FVCDA",
  "event": "delivery.status_changed",
  "occurredAt": "2026-08-04T19:03:22+03:00",
  "data": {
    "orderId": "e5a9f0d3-7c21-4b88-a06e-3f9182bd4471",
    "externalOrderId": "ADS-ORD-99213",
    "status": "PickedUp",
    "courier": { "name": "Emre K.", "phone": "5307654321", "vehicleType": "Motosiklet" },
    "etaDropoffAt": "2026-08-04T19:14:00+03:00"
  }
}

Bir bildirimi işleme almadan önce imzasını mutlaka doğrulayın.

Sonraki adımlar

• Test ortamı — hata senaryolarını canlıya çıkmadan önce deneyin
• Hatalar — tüm hata kodları ve hangilerinde yeniden denemenin sonuç verdiği