Getting started

This page takes you from credentials to your first delivery. Everything here works against the sandbox, so nothing you do sends a real courier anywhere.

1. Get a token

Your client secret is used once, to obtain a token. The token is valid for one hour and goes on every subsequent request.

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

{
  "clientId": "your-client-id",
  "clientSecret": "hzl_test_..."
}

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

Cache this token. Renew it about five minutes before it expires — see Authentication for why that matters.

2. Register a store

A store is one restaurant branch. Register it once; update it whenever its details change. The endpoint is an upsert keyed by your store id, so you never have to remember ours.

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

{
  "taxNumber": "1234567890",
  "name": "Oncu Doner - Kizilay",
  "phone": "5321234567",
  "address": {
    "text": "Mesrutiyet Cad. No:12/A, Kizilay, Cankaya/Ankara",
    "latitude": 39.920778,
    "longitude": 32.854110
  }
}

Because no fleet is attached yet, the response tells you which fleets serve this address:

{
  "success": true,
  "data": {
    "status": "AwaitingFleet",
    "subRegion": "Cankaya - Kizilay",
    "availableFleets": [
      {
        "fleetId": "9d41c7a2-5b83-4e10-91cc-72f0ab3d5e64",
        "name": "Baskent Moto Kurye",
        "status": "Available",
        "avgDeliveryMinutes": 27
      }
    ]
  }
}

3. Attach a fleet

The restaurant agrees terms with one of those fleets — price, payment schedule, coverage. That conversation happens without Hızlıyo. Once it is settled, record the choice by calling the same endpoint again with fleetId added.

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

{
  "taxNumber": "1234567890",
  "name": "Oncu Doner - Kizilay",
  "phone": "5321234567",
  "address": { "text": "...", "latitude": 39.920778, "longitude": 32.854110 },
  "fleetId": "9d41c7a2-5b83-4e10-91cc-72f0ab3d5e64"
}

The store moves to AwaitingFleetApproval. When the fleet confirms, it becomes Active and you receive a store.activated webhook.

4. Send an order

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 Yildirim",
    "phone": "5339876543"
  },
  "dropoff": {
    "text": "Cemal Gursel Cad. No:45 D:8, Kurtulus, Cankaya/Ankara",
    "latitude": 39.925310,
    "longitude": 32.862440,
    "buildingNo": "45",
    "doorNo": "8",
    "floor": "3",
    "note": "Doorbell is broken, please knock"
  },
  "packageNote": "2 wraps, 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": "Baskent Moto Kurye" },
    "trackingUrl": "https://takip.hizliyo.com/d/8fK2mQ",
    "estimatedPickupAt": "2026-08-04T18:59:00+03:00"
  }
}

Keep the orderId. It is how you query status and request cancellation.

Send each order once

If the request fails, it fails. We do not retry it in the background — a package races the clock, and an order that silently revives ten minutes later is worse than no order. Deciding whether to resend is yours. See Orders.

5. Receive status updates

Register a webhook URL with us and we will post every status change to it, signed. This is the primary channel — polling is a fallback.

{
  "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": "Motorcycle" },
    "etaDropoffAt": "2026-08-04T19:14:00+03:00"
  }
}

Always verify the signature before acting on a webhook.

Next

• Sandbox — trigger failures on purpose before they happen in production
• Errors — every error code and whether retrying helps