Send orders, follow them live, find Iraqi addresses

Zoony runs delivery fleets in Iraq. Your system sends an order; a nearby driver gets it in the Zoony Driver app; you get every step by webhook, a tracking link for your customer, and cash on delivery reconciled. The same keys can use Zoony’s Iraqi maps: places and landmarks, drive times with live traffic, and routes.

Quick start

1. The delivery company (or Zoony) creates a test key for you in the dispatch dashboard: Settings → API keys → New key → Test key. Test keys start with zk_test_.
2. Tell Zoony where to send test webhooks (or set it yourself, below).
3. Send an order:

curl https://www.zoonyiraq.com/v1/dispatch/orders \
  -H "Authorization: Bearer zk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORDER-10045",
    "customer": { "name": "Ali Hassan", "phone": "07701234567" },
    "dropoff":  { "lat": 33.3128, "lon": 44.3615, "address": "Karrada, near Al-Wathiq Square" },
    "pickup":   { "name": "Burger House", "phone": "07801234567", "lat": 33.3005, "lon": 44.3893 },
    "prep_min": 12,
    "promise_min": 45,
    "cod_iqd": 18000
  }'

The answer is the order, with its id, status and tracking_url. With a test key, the pretend driver takes it, waits for the food, picks it up and delivers it, a step about every 8 seconds; you get each step by webhook and can read it any time with GET /v1/dispatch/orders/ext:ORDER-10045.

Keys and test mode

Send the key on every request as Authorization: Bearer <key>. Keys are made and revoked by the delivery company’s owner in the dispatch dashboard and are shown once; keep them on your server, never in an app or web page.

Steering test orders

Test webhook address

PUT /v1/dispatch/webhook        (test keys only)
{ "url": "https://your-server.example/zoony-hooks" }

→ { "url": "https://…", "secret": "whsec_…" }

Live webhooks are set by the company in the dashboard.

Limits

Each key may make a set number of requests a minute (600 unless agreed otherwise, up to 6,000; more on request). Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with Retry-After (seconds): wait that long and try again. Webhooks don’t count. The dashboard shows each key’s calls today, over 30 days, and how many were refused.

Orders

Creating an order

The order you get back

{
  "id": 81234, "external_id": "ORDER-10045", "status": "on_way",
  "customer": "Ali Hassan", "address": "Karrada, near Al-Wathiq Square", "lat": 33.3128, "lon": 44.3615,
  "driver": { "name": "Mustafa", "phone": "+9647…", "lat": 33.305, "lon": 44.37, "seen_at": "…" },
  "ready_at": "…", "promised_by": "2026-11-05T14:45:00Z", "late": false, "eta": "2026-11-05T14:31:00Z",
  "tracking_url": "https://www.zoonyiraq.com/t/…",
  "cod_iqd": 18000, "cod_collected_iqd": null, "delivery_fee_iqd": null,
  "created_at": "…", "accepted_at": "…", "at_pickup_at": "…", "picked_up_at": "…", "on_way_at": "…",
  "arrived_at": null, "done_at": null, "has_photo": false, "has_signature": false,
  "parcel_code": "ZN7K2MQ4XR", "weight_kg": 2, "size": "small", "return_status": "", "rating": null, "required_tags": []
}

The driver’s position is shown only while the order is under way.

On the tracking link the customer can leave instructions for the driver (customer_note) and move the delivery to a later 2-hour slot, up to twice (window_from/window_to, reschedules); a driver who hadn’t reached the shop is then taken off it and it goes back to new.

Statuses

Webhooks

Each event is a POST of {"id", "event", "at", "order"}, with the order as above. Answer 2xx within 10 seconds. Failed posts are tried again after 30 s, 2 min, 10 min, 30 min, 2 h and 6 h. Events can arrive more than once and, rarely, out of order: use id to skip repeats and the order’s status as the truth.

Checking the signature

X-Zoony-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your whsec_… secret. Reject bodies whose signature doesn’t match or whose t is more than 5 minutes old.

// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
  const mac = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Order intake (no code on your side)

A delivery app or restaurant system that already sends orders as JSON can send them to Zoony unchanged. The company makes an intake in the dashboard (Settings → Order intake), which gives a secret address, and says where each field is in your JSON. Every post to the address becomes an order.

POST https://www.zoonyiraq.com/v1/intake/zi_…        (no API key: the address is the secret)
Content-Type: application/json

{ "order": { "id": "T-5521", "total": 18000, "notes": "ring twice",
    "customer": { "name": "Ali Hassan", "phone": "07701234567" },
    "address":  { "text": "Karrada", "lat": 33.3128, "lng": 44.3615 },
    "items": [ { "name": "Burger", "quantity": 2 }, { "name": "Cola" } ] } }

→ 201 { "id": 9312, "track_url": "https://www.zoonyiraq.com/t/…" }

Paths use dots between keys, [0] for one list item and [] for all; a | b takes the first that has a value and a + b joins them (customer.first + customer.last). The dashboard has a tester: paste a sample and see the order it would make, without making it.

Signature (optional). When the intake has a header name and secret, each post must carry the HMAC-SHA256 of the raw body in that header, as hex or base64, with or without sha256=. Posts without it get 401.

Refusals are {"error", "code"}: bad_json, mapping (a required field wasn’t found), bad_signature, intake_off, too_big (over 256 KB), rate_limited (over 300 a minute, with Retry-After), or the company’s plan limits. The dashboard keeps the last 200 posts to each intake with their answer and the first 2 KB of the body, to find what went wrong.

Maps API

Keys with Maps API turned on can use Zoony’s Iraqi maps, within a monthly quota agreed with Zoony. Answers carry X-Maps-Quota-Remaining; past the quota you get 429 until the month ends (Baghdad time).

Errors

Errors are JSON: {"error": "what went wrong, in plain words"}.

Going live

1. Run your flow with a test key: created → delivered, a failed order ([fail]), a cancellation, a retried create, your webhook signature check.
2. Agree your request limit and, for maps, your monthly quota.
3. The company creates your live key (zk_…) and sets your live webhook address.
4. Swap the key. Nothing else changes.

Uptime and support

The service is checked from outside every 5 minutes, the team is alerted when anything is down, and the database is backed up every night with a copy kept off the server. GET https://www.zoonyiraq.com/readyz answers {"ok": true} when everything the API needs is working. For integration help, limits or quotas write to the Zoony team from zoonyiraq.com.