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.
