Developers

Tafsee Logistics API and webhooks

Everything a developer needs to send delivery orders from a store or system and to react when they move. Keys and webhooks are made by your team in Settings › API & webhooks.

Base address and keys

The base address is your Tafsee Logistics address followed by /api/logistics/v1; Settings › API & webhooks shows it with a ready example. Send the key in the Authorization header as Bearer tlk_…. A missing, wrong or revoked key gets 401. Each key may make up to 600 calls in ten minutes.

Create an order

curl -X POST https://<your Logistics address>/api/logistics/v1/orders \
  -H "Authorization: Bearer tlk_xxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{"recipientName":"Sara Al Qahtani","recipientPhone":"0551234567","city":"Riyadh","shortAddress":"RRRD2929","codAmount":150}'

Required: recipientName, recipientPhone (Saudi mobile) and city. Optional: recipientEmail, the national address fields (buildingNumber, street, district, postalCode, additionalNumber, shortAddress, unit, directions), dropLat/dropLng, date (YYYY-MM-DD, today or later), windowStart/windowEnd (minutes after midnight), parcels, weightKg, codAmount and notes. The answer is the order with its reference, status and trackingUrl.

Read orders

  • GET /orders returns the latest 100 orders; filter with ?date=YYYY-MM-DD and ?status= (new, assigned, picked_up, on_the_way, delivered, failed, cancelled).
  • GET /orders/{reference} returns one order (the order id works too). An unknown order gets 404.

Webhooks

Pick any of order.created, order.out_for_delivery, order.delivered, order.failed and order.cancelled. Each call is a POST with a JSON body like this:

{
  "id": "7c1d…",
  "event": "order.delivered",
  "createdAt": "2026-11-21T10:42:07.000Z",
  "data": { "order": { "id": "…", "reference": "DL-…", "status": "delivered", "recipientName": "Sara Al Qahtani",
    "city": "Riyadh", "date": "2026-11-21", "codAmount": 150, "trackingUrl": "https://…/t/…",
    "deliveredAt": "2026-11-21T10:42:05.000Z", "receivedBy": "Sara" } }
}

Headers: X-Tafsee-Event, X-Tafsee-Delivery (unique id of the delivery) and X-Tafsee-Signature. Answer with any 2xx within 5 seconds. Anything else is tried again after 1, 5, 30, 120 and 360 minutes; after 20 failed deliveries in a row the webhook is switched off. Failed events add failReason and nextStep; delivered events add deliveredAt and receivedBy.

Check the signature

// Node.js: check X-Tafsee-Signature: t=<seconds>,v1=<hex>
const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
if (!fresh || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) reject();

Use the raw request body exactly as received, and keep the webhook secret on your server only.

Questions

Frequently asked questions


Use the 14-day free trial as your test organisation; keys and webhooks work the same way there.


Usually, but not guaranteed when a call is retried. Use createdAt and the order status in the body.


Receive your first shipment today

Try everything in Business free for 14 days, then choose a plan. No card is needed.

  • Arabic and English
  • Built for Saudi Arabia, in SAR
  • Nothing to install

Warehouse & delivery

Tafsee Logistics

Receive goods with a barcode on every package, hold them until they are cleared, then plan delivery trips with proof at every door.

Arabic & English · Saudi national address14-day free trialDriver app in the browser

Tafsee Logistics TermsPrivacy PolicyTrust & securityDevelopersWhat's new

+966 58 267 6110+966 58 267 6110