Integration Guide

Connect your existing delivery, ERP or e-commerce system to Tariq's route optimization. Three API calls cover the whole loop.

How it works

Tariq does not replace your system. It sits beside it: you keep your orders, customers and invoicing where they are, and Tariq handles the part none of those systems do — deciding which driver takes which stop, in which order.

Drivers use the Tariq Android app — nothing to build on your side. Your dispatcher can keep working in your existing software; Tariq's dashboard is optional.

Before you start

• Base URL: https://tariq.codeator.ai (HTTPS only)
• Auth: every request sends an X-API-Key header
• Money: COD is an integer in IQD. Never send decimals — 25000, not 25000.00
• Coordinates: lat/lng are optional but strongly recommended. Without them an order cannot be placed on a route accurately

Getting an API key

In the Tariq dashboard, sign in as the account owner and go to Settings → API Keys → Create key. The key is shown once and starts with tk_. Store it as a server-side secret.

Step 1 — Push orders into Tariq

Send orders whenever your system creates them, or in one batch each morning. Both work.

POST /api/v1/orders — one order

curl -X POST https://tariq.codeator.ai/api/v1/orders \
  -H "X-API-Key: tk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "Zainab Mohammed",
    "phone": "07701234567",
    "area": "Karrada",
    "cod": 45000,
    "lat": 33.3140,
    "lng": 44.3930,
    "priority": "normal",
    "time_window": "morning",
    "external_ref": "YOUR-ORDER-NO-8891",
    "barcode": "PKG-2026-0142"
  }'

# 200 OK
{"id": 4417, "status": "pending", "external_ref": "YOUR-ORDER-NO-8891", "duplicate": false, "message": "Created"}

POST /api/v1/orders/bulk — up to 500 at once

curl -X POST https://tariq.codeator.ai/api/v1/orders/bulk \
  -H "X-API-Key: tk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {"customer":"Ali Hasan","phone":"07701111111","area":"Mansour","cod":120000,"lat":33.345,"lng":44.348},
    {"customer":"Noor Sabri","phone":"07702222222","area":"Dora","cod":70000,"lat":33.254,"lng":44.391}
  ]'

# 200 OK — partial success is normal: check "errors"
{"created": 2, "errors": [], "orders": [{"id":4418,...},{"id":4419,...}]}

Order fields

Step 2 — Optimize

Call this once when the day's orders are loaded. Tariq solves the routing problem and assigns every pending order to a driver with a stop number. That assignment is what the drivers' phones read.

GET /api/v1/routes

curl "https://tariq.codeator.ai/api/v1/routes?depart_hour=8" \
  -H "X-API-Key: tk_your_key_here"

# 200 OK
{
  "routes": [
    {
      "driver": 1,
      "driver_id": 12,
      "driver_name": "Hussein Kareem",
      "driver_phone": "07801234567",
      "google_maps_url": "https://www.google.com/maps/dir/...",
      "orders": [
        {"stop":1, "order_id":4417, "customer":"Zainab Mohammed", "area":"Karrada", "cod":45000},
        {"stop":2, "order_id":4419, "customer":"Noor Sabri",      "area":"Dora",    "cod":70000}
      ]
    }
  ],
  "depart_hour": 8,
  "traffic_multiplier": 1.5,
  "total_time_seconds": 7420
}

Optional parameters

Step 3 — Get results back

Two options. Webhooks are strongly preferred: your system learns about a delivery within seconds instead of minutes, and you make no wasted calls.

Option A — Webhooks (recommended)

In the Tariq dashboard: Settings → Webhooks → Add webhook. Enter your HTTPS endpoint and a shared secret you generate. Tariq POSTs JSON to that URL whenever an order changes state.

// Tariq POSTs this to your endpoint
{
  "event": "order.delivered",
  "company_id": 7,
  "timestamp": "2026-09-22T11:04:19.223401",
  "data": {
    "order_id": 4417,
    "status": "delivered",
    "customer": "Zainab Mohammed",
    "phone": "07701234567",
    "area": "Karrada",
    "cod": 45000,
    "cod_collected": 45000,
    "barcode": "YOUR-SYSTEM-REF-8891",
    "assigned_driver_id": 12,
    "received_by": "Zainab",
    "fail_reason": null,
    "fail_reason_code": null,
    "postpone_reason": null,
    "postpone_reason_code": null,
    "postponed_to": null,
    "delivered_at": "2026-09-22T11:04:18",
    "completed_at": "2026-09-22T11:04:18"
  }
}

Events

Leave the event list empty to receive all of them, or subscribe to only the ones you need.

Verifying the signature

Every request carries X-Tariq-Signature: sha256=<hex> — an HMAC-SHA256 of the raw request body, keyed with your shared secret. Verify it before trusting the payload.

# Python / Flask
import hmac, hashlib

@app.route("/tariq-webhook", methods=["POST"])
def tariq_webhook():
    raw = request.get_data()                      # raw bytes, not request.json
    expected = "sha256=" + hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Tariq-Signature", "")):
        return "", 401
    event = request.get_json()
    # ... update your own order record here ...
    return "", 200

// Node / Express — note express.raw, not express.json
app.post("/tariq-webhook", express.raw({type: "application/json"}), (req, res) => {
  const expected = "sha256=" + require("crypto")
    .createHmac("sha256", SECRET).update(req.body).digest("hex");
  if (expected !== req.headers["x-tariq-signature"]) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString());
  // ... update your own order record here ...
  res.sendStatus(200);
});

// PHP
$raw = file_get_contents("php://input");
$expected = "sha256=" . hash_hmac("sha256", $raw, $SECRET);
if (!hash_equals($expected, $_SERVER["HTTP_X_TARIQ_SIGNATURE"] ?? "")) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// ... update your own order record here ...

Delivery rules

• Respond 2xx quickly. Tariq waits 5 seconds, then counts a timeout as a failure
• After 10 consecutive failures the webhook is disabled and must be re-enabled in the dashboard
• There is no automatic retry — do your slow work in a queue after responding 200
• Be idempotent. Treat a repeated order_id + status as the same event
• Use the Test button in the dashboard to fire a sample test event while you build

Option B — Polling

If you cannot expose a public endpoint, poll instead. Every 5–10 minutes is enough; the data does not change faster than drivers move.

# Everything closed out — poll each status you care about
curl "https://tariq.codeator.ai/api/v1/orders?status=delivered" -H "X-API-Key: tk_..."
curl "https://tariq.codeator.ai/api/v1/orders?status=failed"    -H "X-API-Key: tk_..."

# Full detail for one order, including POD and signature flags
curl "https://tariq.codeator.ai/api/v1/orders/4417" -H "X-API-Key: tk_..."

Returns the 200 most recent orders, newest first.

Other endpoints

Status values

Errors

A realistic first integration

1. Create a key and push one test order. Confirm it appears in the Tariq dashboard
2. Add a webhook pointing at your staging endpoint and press Test until the signature verifies
3. Push a real morning's orders with /orders/bulk, then call /routes
4. Hand the drivers the app and run one day in parallel with your current process
5. Once the callbacks line up with reality, switch over

Most teams finish this in one to two days.

Questions

Email tariq@codeator.ai with your company name and what you are connecting, and we will help directly.