المطوّرون

واجهة API وخطافات الويب في تفسي اللوجستيات

كل ما يحتاجه المطوّر لإرسال طلبات التوصيل من متجر أو نظام والتفاعل عند تحركها. يصنع فريقك المفاتيح وخطافات الويب من الإعدادات › واجهة API وخطافات الويب.

العنوان الأساسي والمفاتيح

العنوان الأساسي هو عنوان تفسي اللوجستيات الخاص بك متبوعًا بـ /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();

استخدم محتوى الطلب الخام كما وصل تمامًا، واحفظ سرّ خطاف الويب في خادمك فقط.

أسئلة

الأسئلة الشائعة


استخدم التجربة المجانية لمدة 14 يومًا منظمةً للاختبار، فالمفاتيح وخطافات الويب تعمل فيها بالطريقة نفسها.


عادةً، لكن ذلك غير مضمون عند إعادة المحاولة. استخدم createdAt وحالة الطلب في المحتوى.


استلم أول شحنة لك اليوم

جرّب كل ما في خطة الأعمال مجانًا لمدة 14 يومًا، ثم اختر خطة. لا تحتاج إلى بطاقة.

  • بالعربية والإنجليزية
  • مصمَّم للسعودية وبالريال
  • لا شيء للتثبيت

المستودعات والتوصيل

تفسي اللوجستيات

استلم البضائع بباركود على كل طرد، واحجزها حتى يُفرج عنها، ثم خطّط رحلات التوصيل مع إثبات عند كل باب.

عربي وإنجليزي · العنوان الوطني السعوديتجربة مجانية 14 يومًاتطبيق السائق في المتصفح

شروط تفسي اللوجستياتسياسة الخصوصيةالثقة والأمانالمطوّرونما الجديد

+966 58 267 6110+966 58 267 6110