العنوان الأساسي والمفاتيح
العنوان الأساسي هو عنوان تفسي اللوجستيات الخاص بك متبوعًا بـ /api/logistics/v1، وتعرضه الإعدادات › واجهة API وخطافات الويب مع مثال جاهز. أرسل المفتاح في ترويسة Authorization بصيغة Bearer tlk_…. ويحصل المفتاح المفقود أو الخاطئ أو الملغى على 401. ولكل مفتاح حتى 600 استدعاء في عشر دقائق.
إنشاء طلب
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}'المطلوب: recipientName وrecipientPhone (جوال سعودي) وcity. والاختياري: recipientEmail، وحقول العنوان الوطني (buildingNumber وstreet وdistrict وpostalCode وadditionalNumber وshortAddress وunit وdirections)، وdropLat/dropLng، وdate (YYYY-MM-DD، اليوم أو بعده)، وwindowStart/windowEnd (دقائق بعد منتصف الليل)، وparcels وweightKg وcodAmount وnotes. والإجابة هي الطلب مع reference وstatus وtrackingUrl.
قراءة الطلبات
- GET /orders يعيد أحدث 100 طلب، ويمكن التصفية بـ ?date=YYYY-MM-DD و?status= (new وassigned وpicked_up وon_the_way وdelivered وfailed وcancelled).
- GET /orders/{reference} يعيد طلبًا واحدًا (ويعمل معرّف الطلب أيضًا). والطلب غير المعروف يحصل على 404.
خطافات الويب
اختر أيًّا من order.created وorder.out_for_delivery وorder.delivered وorder.failed وorder.cancelled. كل استدعاء طلب POST بمحتوى JSON مثل هذا:
{
"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" } }
}الترويسات: X-Tafsee-Event وX-Tafsee-Delivery (معرّف فريد لعملية الإرسال) وX-Tafsee-Signature. أجب بأي رمز 2xx خلال 5 ثوانٍ. وأي إجابة أخرى تُعاد بعد 1 و5 و30 و120 و360 دقيقة، وبعد 20 عملية فاشلة متتالية يُوقف الخطاف. وتضيف أحداث التعذّر failReason وnextStep، وأحداث التسليم deliveredAt وreceivedBy.
التحقق من التوقيع
// 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();استخدم محتوى الطلب الخام كما وصل تمامًا، واحفظ سرّ خطاف الويب في خادمك فقط.
