التتبع العام

بخلاف كل صفحة أخرى في مرجع API هذا، لا تتطلب نقطة النهاية هذه أي مفتاح API ولا تسجيل دخول. فهي ما يشغّل رابط التتبع العام الذي يُشارَك مع مستلم الشحنة.

كيف تُنشأ الرموز

لا يُولَّد رابط تتبع تلقائيًا لكل شحنة — بل يُسكّ عند الطلب. داخل التطبيق، يختار مستخدم يملك صلاحية قراءة الشحنات مشاركة رابط التتبع على شحنة (صفحة الشحنات)، فيُستدعى مسار مصادَق عليه (POST /shipments/:id/share) يقوم بما يلي:

• يولّد رمزًا عشوائيًا لتلك الشحنة عند أول مشاركة، ويخزّنه على سجل الشحنة.
• يعيد الرمز نفسه في كل مشاركة لاحقة — فالرابط لا يتغير بعد إنشائه.

انظر صفحة الشحنات في دليل المستخدم للاطلاع على الخطوات داخل التطبيق. الرابط الناتج يفتح صفحة التتبع الخاصة بالتطبيق (/track/:token)؛ ونقطة النهاية أدناه هي ما تستدعيه تلك الصفحة.

نقطة النهاية

GET /track/:token

لا حاجة إلى ترويسة مصادقة ولا يجري التحقق منها. ‏:token هو الرمز المُعتم من رابط المشاركة.

مثال طلب

curl https://tenant.logistall.cloud/api/track/9f2e4a1b7c3d5e6f8a0b1c2d3e4f5a6b

مثال استجابة

{
  "shipmentNumber": "SHP-00482",
  "status": "in_transit",
  "mode": "ftl",
  "originCity": "Casablanca",
  "destCity": "Tanger",
  "pickupScheduledAt": "2026-07-10T08:00:00.000Z",
  "deliveryScheduledAt": "2026-07-12T17:00:00.000Z",
  "events": [
    {
      "eventType": "departure",
      "status": "in_transit",
      "description": "Left Casablanca distribution hub",
      "city": "Casablanca",
      "eventAt": "2026-07-10T09:15:00.000Z"
    },
    {
      "eventType": "pickup",
      "status": "pickup_scheduled",
      "description": null,
      "city": "Casablanca",
      "eventAt": "2026-07-10T08:05:00.000Z"
    }
  ]
}

لاحظ أن events[] هنا تتضمن حقل description — الملاحظة النصية الحرة التي يمكن لموزع الشحنات أو السائق إرفاقها بحدث تتبع. وهذا هو الفرق الوحيد عن مصفوفة tracking[] في نقطة النهاية المصادَق عليها GET /v1/shipments/:id التي لا تتضمنه.

ما لا يُكشف أبدًا

نقطة النهاية هذه ضئيلة عن قصد. فهي لا تعيد أبدًا:

• المعرّف الداخلي id للشحنة (بل رقمها المقروء shipmentNumber فقط).
• أسماء العملاء أو الناقلين.
• أي عنوان أو بيانات اتصال أو أي معلومات شخصية أخرى تتجاوز اسمَي مدينتَي المنشأ/الوجهة.
• التسعير أو الرسوم أو الفواتير أو أي بيانات مالية.
• أي مستأجر/شركة تعود إليها الشحنة (الرمز وحده يحلّها على الخادم).
• أي بيانات تخص شحنات أو عملاء أو مستأجرين آخرين — فالرمز لا يفتح أبدًا سوى الشحنة الواحدة التي سُكّ لها.

إن احتجت إلى أكثر من هذا — أسماء العملاء والعناوين والتسعير — فذلك يتطلب مفتاح API مصادَقًا عليه مع /v1/shipments/:id أو ما يقابلها من صفحات داخل التطبيق، لا نقطة النهاية هذه.

الأخطاء

الحالة	المتن	متى
404	{ "error": "Not found" }	الرمز لا يطابق أي شحنة لدى أي مستأجر نشط.
500	{ "error": "Server error" }	خطأ غير متوقع في الخادم.

لا توجد طريقة لتعداد الرموز الصالحة أو سردها — فالرمز لا يعمل إلا إن كان لديك الرابط الدقيق.