الشحنات

يتطلب مفتاح API — انظر المصادقة. نقطتا النهاية كلتاهما للقراءة فقط (GET).

قائمة الشحنات

GET /v1/shipments

معاملات الاستعلام

المعامل	النوع	الافتراضي	ملاحظات
limit	integer	50	الحد الأقصى 200.
offset	integer	0
status	string	—	مطابقة تامة لحالة الشحنة (مثل in_transit). أغفله لإرجاع الشحنات بأي حالة.

النتائج مرتّبة تنازليًا حسب createdAt.

مثال طلب

curl -H "Authorization: Bearer lk_YOUR_KEY" \
  "https://tenant.logistall.cloud/api/v1/shipments?limit=2&status=in_transit"

مثال استجابة

[
  {
    "id": "3f1c9c2a-6b3e-4b3a-9b2d-1a2b3c4d5e6f",
    "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",
    "createdAt": "2026-07-08T14:22:03.000Z"
  },
  {
    "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "shipmentNumber": "SHP-00479",
    "status": "in_transit",
    "mode": "ocean",
    "originCity": "Casablanca",
    "destCity": "Marrakech",
    "pickupScheduledAt": "2026-07-09T09:30:00.000Z",
    "deliveryScheduledAt": "2026-07-14T00:00:00.000Z",
    "createdAt": "2026-07-07T11:05:47.000Z"
  }
]

قيمة mode واحدة من ftl أو ltl أو parcel أو air أو ocean أو rail أو intermodal. وقد تكون originCity/destCity بقيمة null إذا لم يكن للشحنة موقع منشأ أو وجهة مسجَّل.

جلب شحنة واحدة

GET /v1/shipments/:id

الحقول نفسها كما في نقطة نهاية القائمة، إضافة إلى مصفوفة tracking — السجل الزمني الكامل لتتبع الشحنة، الحدث الأحدث أولًا.

مثال طلب

curl -H "Authorization: Bearer lk_YOUR_KEY" \
  https://tenant.logistall.cloud/api/v1/shipments/3f1c9c2a-6b3e-4b3a-9b2d-1a2b3c4d5e6f

مثال استجابة

{
  "id": "3f1c9c2a-6b3e-4b3a-9b2d-1a2b3c4d5e6f",
  "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",
  "createdAt": "2026-07-08T14:22:03.000Z",
  "tracking": [
    {
      "eventType": "departure",
      "status": "in_transit",
      "city": "Casablanca",
      "eventAt": "2026-07-10T09:15:00.000Z"
    },
    {
      "eventType": "pickup",
      "status": "pickup_scheduled",
      "city": "Casablanca",
      "eventAt": "2026-07-10T08:05:00.000Z"
    }
  ]
}

قيمة tracking[].eventType واحدة من pickup أو departure أو arrival أو in_transit أو out_for_delivery أو delivered أو exception أو customs_hold أو attempt_failed أو returned. أما tracking[].status فهي حالة الشحنة وقت ذلك الحدث.

الأخطاء

الحالة	المتن	متى
404	{ "error": "Not found" }	لا توجد شحنة بذلك id.
401	انظر المصادقة	مفتاح مفقود/غير صالح.
500	{ "error": "Database error" }	خطأ غير متوقع في الخادم.

هذا هو السجل الزمني نفسه للتتبع الظاهر في التطبيق على صفحة الشحنات، والبيانات نفسها التي يكشفها رابط التتبع العام لمستلم الشحنة دون مصادقة. انظر صفحة الشحنات في دليل المستخدم لمعرفة كيفية إضافة أحداث التتبع.