جدول المحتويات

وثائق واجهة برمجة التطبيقات العامة لـ ShaQ Express

مرحباً بك في واجهة برمجة التطبيقات العامة لـ ShaQ Express. توفر هذه الوثائق للشركاء والمطورين نقاط النهاية اللازمة لإدارة الطرود والشحنات واستقبال تحديثات التتبع بسلاسة.

المعلومات	القيمة
الإصدار	1.0
رابط التطوير	`https://test-partner.shaqexpress.com/api/v1`

الترويسات القياسية

يجب أن تحتوي جميع الطلبات المرسلة إلى API على ترويسات HTTP القياسية التالية:

الترويسة	النوع	الوصف
`Content-Type`	`application/json`	يتطلب جسم الطلب بتنسيق JSON
`Accept`	`application/json`	يتوقع جسم الاستجابة بتنسيق JSON

(ملاحظة: ستتطلب نقاط النهاية المحمية أيضاً ترويسة Authorization: Bearer <token> التي يتم الحصول عليها عند تسجيل الدخول).

حالات الطرود

يستخدم نظامنا حالات متعددة لتتبع دورة حياة الطرد. فيما يلي القائمة الشاملة للحالات التي قد تستقبلها:

📦 الانتظار والاستلام

pending : لم يتم استلام الطرد من الشريك بعد
received : تم استلام الطرد من الشريك
warehouse_received : تم استلام الطرد في مستودع إقليمي
collected : تم استلام الطرد من الشريك من قِبل ShaQ Express
ready_for_pickup : الطرد جاهز لاستلامه من قِبل العميل

🚚 العبور والإرسال

shipped : تم شحن الطرد من قِبل الشريك
assigned : تم تعيين الطرد لمندوب توصيل
in_transit : الطرد في طريقه إلى أقرب مستودع
dispatched : الطرد في طريقه للتسليم

✅ نتائج التسليم

confirmed : تم الاتصال بالعميل وتأكيد التسليم
delivered : تم تسليم الطرد بنجاح للعميل

⚠️ المشاكل والاستثناءات

not_delivered : تمت محاولة التسليم لكن لم تكتمل
rescheduled : تم إعادة جدولة تسليم الطرد لمحاولة جديدة
customer_hold : التسليم معلّق بناءً على طلب العميل
customer_unreachable : التسليم معلّق لعدم إمكانية التواصل مع العميل
suspected_scam : التسليم معلّق بسبب اشتباه بعملية احتيال

🔙 الإرجاع

return_picked : تم استلام الطرد من العميل لإعادته إلى الشريك
return_in_progress : يجري تجهيز الطرد لإرساله إلى الشريك
returned_to_sender : تم إرسال الطرد إلى الشريك
return_to_central : يتم إرجاع الطرد إلى المستودع المركزي لـ ShaQ Express بعد محاولات تسليم فاشلة متعددة، تمهيداً لإعادته إلى الشريك

نقاط نهاية API

الحصول على الطرود

GET /packages?page=1&limit=1

الحصول على جميع الطرود

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Request successful",
  "data": {
    "list": [
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "delivered",
        "statusDescription": "Package was successfully delivered to customer",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          },
          {
            "name": "iPhone 14 Pro",
            "quantity": 2
          }
        ]
      },
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received from Partner.",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": null,
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          }
        ]
      }
    ],
    "meta": {
      "total": 2,
      "perPage": 15,
      "currentPage": 1,
      "lastPage": 1
    }
  }
}

الحصول على طرد محدد

GET /packages/{partnerRef}

الحصول على تفاصيل طرد

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "confirmed",
        "description": "Customer has been called and delivery confirmed.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "received",
        "description": "Package has been received from Partner.",
        "date": "2025-07-15 15:38",
        "comment": null
      },
      {
        "name": "pending",
        "description": "Package is yet to be received by Partner.",
        "date": "2025-07-14 10:38",
        "comment": null
      }
    ]
  }
}

حذف طرد معلّق

DELETE /packages/{partnerRef}

حذف طرد. يمكن حذف الطرود المعلّقة فقط.

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Package deleted",
  "data": null
}

إلغاء الطلب

POST /packages/{partnerRef}/cancel

إلغاء طلب تنفيذ.

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Order cancelled successfully",
  "data": null
}

400

{
  "message": "Order cannot be cancelled. Order cancellation failed",
  "data": null
}

404

{
  "message": "Order not found",
  "data": null
}

إنشاء طرد واحد

POST /packages

إنشاء طرد واحد

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الطلب

المعامل	النوع	الوصف
`tracking_number`	`string`	اختياري.
`partner_ref`	`string`	مطلوب. يجب أن يكون فريداً.
`customer_name`	`string`	مطلوب.
`customer_phone_1`	`string`	مطلوب.
`customer_phone_2`	`string`	اختياري.
`source_country_iso2`	`string`	مطلوب.
`source_address_line_1`	`string`	مطلوب.
`source_address_line_2`	`string`	اختياري.
`destination_region`	`string`	مطلوب إذا كان `region_id` فارغاً.
`destination_city`	`string`	مطلوب.
`destination_address_line_1`	`string`	مطلوب.
`destination_address_line_2`	`string`	اختياري.
`destination_postal_code`	`string`	اختياري.
`length`	`decimal`	اختياري.
`height`	`decimal`	اختياري.
`weight`	`decimal`	اختياري.
`description`	`string`	مطلوب.
`units`	`string`	مطلوب.
`type`	`string`	مطلوب، من بين: `parcel`، `box`
`handling`	`string`	مطلوب، من بين: `normal`، `fragile`
`special_instructions`	`string`	اختياري.
`latitude`	`decimal`	اختياري.
`longitude`	`decimal`	اختياري.
`value`	`decimal`	مطلوب.
`amount_to_collect`	`decimal`	اختياري. يُعيَّن افتراضياً بقيمة `value` الطرد.
`payment_collector`	`string`	اختياري، من بين: `shaq`، `partner` (لا يمكن إرسال هذا المعامل إلا عندما تكون ShaQ Express هي جامعة الدفع. يحدد من المسؤول عن تحصيل الدفعة من العميل، ومخصص للحالات الخاصة التي يتولى فيها الشريك التحصيل. في حال عدم توفيره، يُستخدم إعداد جامع الدفع المتفق عليه افتراضياً.)
`items`	`array`	مطلوب. `{name, quantity}`
`region_id`	`integer`	مطلوب إذا كان `destination_region` فارغاً.

الاستجابة

200

{
  "message": "Package created successfully",
  "data": {
    "partnerRef": "UNIQUE-REF-001",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "altPhone": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "units": 1,
    "type": "box",
    "handling": "normal",
    "specialInstructions": null,
    "status": "pending",
    "statusDescription": "Package is yet to be received by Partner",
    "landmark": null,
    "proofPhotoUrl": null,
    "partner": "Demo Partner",
    "scheduleDate": null,
    "deliveryFee": null,
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "paymentStatus": null,
    "date": "2025-04-10 11:15",
    "deliveredAt": null,
    "eta": "2026-04-20 - 2026-04-22",
    "deliveryAttempts": 0,
    "items": [
      { "name": "iPhone 6", "quantity": 1 },
      { "name": "iPhone 14 Pro", "quantity": 2 }
    ]
  }
}

404

{
  "message": "No Region with name {destination_region} found",
  "data": null
}

إنشاء طرود بالجملة

POST /packages/bulk

إنشاء عدة طرود دفعةً واحدة

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الطلب

المعامل	النوع	الوصف
`packages`	`array`	مطلوب.
`packages.*.tracking_number`	`string`	اختياري.
`packages.*.partner_ref`	`string`	مطلوب.
`packages.*.customer_name`	`string`	مطلوب.
`packages.*.customer_phone_1`	`string`	مطلوب.
`packages.*.customer_phone_2`	`string`	اختياري.
`packages.*.source_country_iso2`	`string`	مطلوب.
`packages.*.source_address_line_1`	`string`	مطلوب.
`packages.*.source_address_line_2`	`string`	اختياري.
`packages.*.destination_region`	`string`	مطلوب إذا كان `region_id` فارغاً.
`packages.*.destination_city`	`string`	مطلوب.
`packages.*.destination_address_line_1`	`string`	مطلوب.
`packages.*.destination_address_line_2`	`string`	اختياري.
`packages.*.destination_postal_code`	`string`	اختياري.
`packages.*.length`	`decimal`	اختياري.
`packages.*.height`	`decimal`	اختياري.
`packages.*.weight`	`decimal`	اختياري.
`packages.*.description`	`string`	مطلوب.
`packages.*.units`	`string`	مطلوب.
`packages.*.type`	`string`	مطلوب، من بين: `parcel`، `box`
`packages.*.handling`	`string`	مطلوب، من بين: `normal`، `fragile`
`packages.*.special_instructions`	`string`	اختياري.
`packages.*.latitude`	`decimal`	اختياري.
`packages.*.longitude`	`decimal`	اختياري.
`packages.*.value`	`decimal`	مطلوب.
`packages.*.amount_to_collect`	`decimal`	اختياري. يُعيَّن افتراضياً بقيمة `value` الطرد.
`packages.*.payment_collector`	`string`	اختياري، من بين: `shaq`، `partner` (لا يمكن إرسال هذا المعامل إلا عندما تكون ShaQ Express هي جامعة الدفع. يحدد من المسؤول عن تحصيل الدفعة من العميل، ومخصص للحالات الخاصة التي يتولى فيها الشريك التحصيل. في حال عدم توفيره، يُستخدم إعداد جامع الدفع المتفق عليه افتراضياً.)
`packages.*.items`	`array`	مطلوب. `{name, quantity}`
`packages.*.region_id`	`integer`	مطلوب إذا كان `destination_region` فارغاً.

الاستجابة

200

{
  "message": "Packages created successfully",
  "data": null
}

إنشاء شحنة

POST /shipments

إنشاء شحنة تمثّل الإرسال الفعلي للطرود إلى ShaQ Express.

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الطلب

المعامل	النوع	الوصف
`packages`	`array`	مطلوب.
`packages.*.tracking_number`	`string`	اختياري.
`packages.*.partner_ref`	`string`	مطلوب.
`packages.*.customer_name`	`string`	مطلوب.
`packages.*.customer_phone_1`	`string`	مطلوب.
`packages.*.customer_phone_2`	`string`	اختياري.
`packages.*.source_country_iso2`	`string`	مطلوب.
`packages.*.source_address_line_1`	`string`	مطلوب.
`packages.*.source_address_line_2`	`string`	اختياري.
`packages.*.destination_region`	`string`	مطلوب إذا كان `region_id` فارغاً.
`packages.*.destination_city`	`string`	مطلوب.
`packages.*.destination_address_line_1`	`string`	مطلوب.
`packages.*.destination_address_line_2`	`string`	اختياري.
`packages.*.destination_postal_code`	`string`	اختياري.
`packages.*.length`	`decimal`	اختياري.
`packages.*.height`	`decimal`	اختياري.
`packages.*.weight`	`decimal`	اختياري.
`packages.*.description`	`string`	مطلوب.
`packages.*.units`	`string`	مطلوب.
`packages.*.type`	`string`	مطلوب، من بين: `parcel`، `box`
`packages.*.handling`	`string`	مطلوب، من بين: `normal`، `fragile`
`packages.*.special_instructions`	`string`	اختياري.
`packages.*.latitude`	`decimal`	اختياري.
`packages.*.longitude`	`decimal`	اختياري.
`packages.*.value`	`decimal`	مطلوب.
`packages.*.amount_to_collect`	`decimal`	اختياري. يُعيَّن افتراضياً بقيمة `value` الطرد.
`packages.*.payment_collector`	`string`	اختياري، من بين: `shaq`، `partner` (لا يمكن إرسال هذا المعامل إلا عندما تكون ShaQ Express هي جامعة الدفع. يحدد من المسؤول عن تحصيل الدفعة من العميل، ومخصص للحالات الخاصة التي يتولى فيها الشريك التحصيل. في حال عدم توفيره، يُستخدم إعداد جامع الدفع المتفق عليه افتراضياً.)
`packages.*.items`	`array`	مطلوب.
`packages.*.region_id`	`integer`	مطلوب إذا كان `destination_region` فارغاً.

الاستجابة

200

{
  "message": "Shipment created successfully",
  "data": {
    "reference": "PAR-20260322053800"
  }
}

الحصول على شحنة محددة

GET /shipments/{reference}

الحصول على تفاصيل شحنة

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Request successful",
  "data": {
    "reference": "SAAM-20260322053800",
    "date": "2026-03-22 05:38",
    "packages": [
      {
        "partnerRef": "qwertyui1a1aaqweqqaqx",
        "trackingNumber": "C561819A",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceAddressLine1": "Accra spintex basket junction",
        "sourceAddressLine2": null,
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "units": 1,
        "type": "box",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received by Partner",
        "latitude": null,
        "longitude": null,
        "value": "1468.00",
        "amountToCollect": "1468.00",
        "paymentCollector": "shaq",
        "date": "2026-03-22 05:38",
        "eta": "2026-04-20 - 2026-04-22",
        "trackingUrl": "https://dev.tracking-website.pages.dev/packages/C561819A",
        "items": [
          {
            "name": "14cm Alya Glass Cookie Holder - Transparent",
            "quantity": 4
          },
          {
            "name": "10.6 Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
            "quantity": 1
          },
          {
            "name": "6 Pieces Nossa 21cm Cake Plate Set",
            "quantity": 1
          }
        ]
      }
    ]
  }
}

تحديث طرد

PATCH /packages/{partnerRef}

تحديث طرد محدد

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الطلب

المعامل	النوع	الوصف
`tracking_number`	`string`	اختياري.
`customer_name`	`string`	اختياري.
`customer_phone_1`	`string`	اختياري.
`customer_phone_2`	`string`	اختياري.
`source_country_iso2`	`string`	اختياري.
`source_address_line_1`	`string`	اختياري.
`source_address_line_2`	`string`	اختياري.
`destination_region`	`string`	اختياري.
`destination_city`	`string`	اختياري.
`destination_address_line_1`	`string`	اختياري.
`destination_address_line_2`	`string`	اختياري.
`destination_postal_code`	`string`	اختياري.
`length`	`decimal`	اختياري.
`height`	`decimal`	اختياري.
`weight`	`decimal`	اختياري.
`description`	`string`	اختياري.
`units`	`string`	اختياري.
`type`	`string`	اختياري، من بين: `parcel`، `box`
`handling`	`string`	اختياري، من بين: `normal`، `fragile`
`special_instructions`	`string`	اختياري.
`latitude`	`decimal`	اختياري.
`longitude`	`decimal`	اختياري.
`value`	`decimal`	اختياري.
`amount_to_collect`	`decimal`	اختياري.
`items`	`array`	اختياري.

الاستجابة

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      }
    ]
  }
}

تتبع طرد

GET /tracking/{trackingNumber}

الحصول على حالات تتبع طرد محدد

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Package tracking",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "description": "Kitchen cabinet",
    "status": "shipped",
    "statusDescription": "Package has been shipped by Partner.",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "tracking": [
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:17"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:16"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:14"
      }
    ]
  }
}

الحصول على المناطق

GET /setup/regions

الحصول على جميع المناطق المسموح بها

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Request successful",
  "data": [
    {
      "id": 16,
      "name": "Western North"
    },
    {
      "id": 15,
      "name": "Ashanti"
    }
  ]
}

استقبال تحديثات الطرود عبر Webhook

POST /YOUR_WEBHOOK_URL

سنرسل طلب POST إلى رابط Webhook الخاص بك في كل مرة يحدث فيها حدث متتبَّع على طرد.

الغلاف

يشترك كل حمولة Webhook في نفس الغلاف العلوي:

الحقل	النوع	الوصف
`event`	`string`	نوع الحدث. انظر أحداث Webhook أدناه.
`event_id`	`string`	معرّف UUID فريد لكل تسليم، يُستخدم للتحقق من التكرار وتفادي المعالجة المتكررة.
`api_version`	`string`	إصدار الحمولة، مثل `v1`
`occurred_at`	`string`	طابع زمني بتوقيت UTC وفق معيار ISO 8601 يشير إلى وقت وقوع الحدث
`data`	`object`	حمولة خاصة بالحدث، يختلف شكلها بحسب نوع `event`.

أحداث Webhook

`package.status_updated`

يُطلَق في كل مرة تتغير فيها حالة طرد.

الحقل	النوع	الوصف
`tracking_number`	`string`	رقم تتبع ShaQ Express
`partner_ref`	`string`	مرجعك للطرد
`status`	`string`	الحالة الجديدة. انظر حالات الطرود للقيم المتاحة
`description`	`string`	وصف مقروء للحالة
`comment`	`string`	سياق أو تعليق إضافي، قد يكون `null`
`meta`	`object`	بيانات إضافية، تتضمن `proof_url` عندما تكون `status` بقيمة `delivered`

{
  "event": "package.status_updated",
  "event_id": "018e2b3c-7f4a-7c2d-9e1b-4a8f3d2c6b5a",
  "api_version": "v1",
  "occurred_at": "2025-05-29T10:30:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "delivered",
    "description": "Package was successfully delivered to customer",
    "comment": null,
    "meta": {
      "proof_url": "https://example.com/proof.jpg"
    }
  }
}

`package.amount_to_collect_updated`

يُطلَق عند تعديل المبلغ المراد تحصيله للطرد، ويكون ذلك دائماً بطلب من العميل وموافقته.

الحقل	النوع	الوصف
`tracking_number`	`string`	رقم تتبع ShaQ Express
`partner_ref`	`string`	مرجعك للطرد
`status`	`string`	حالة الطرد وقت التعديل. انظر حالات الطرود للقيم المتاحة
`meta.old_amount_to_collect`	`number`	المبلغ السابق للتحصيل
`meta.new_amount_to_collect`	`number`	المبلغ المعدَّل للتحصيل
`meta.currency`	`string`	رمز العملة، مثل `GHS`
`meta.reason`	`string`	سبب التعديل

{
  "event": "package.amount_to_collect_updated",
  "event_id": "039g4d5e-9h6c-9e4f-1g3d-6c0h5f4e8d7c",
  "api_version": "v1",
  "occurred_at": "2025-05-29T09:00:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "received",
    "meta": {
      "old_amount_to_collect": 25.0,
      "new_amount_to_collect": 35.0,
      "currency": "GHS",
      "reason": "Items changed"
    }
  }
}

الاستجابة المتوقعة

يجب أن تعيد نقطة النهاية الخاصة بك استجابة 2xx لتأكيد استلام Webhook. أي استجابة غير 2xx ستتم إعادة محاولتها حتى 3 مرات.

{
  "message": "",
  "data": {
    "status": "OK"
  }
}

متطلبات Webhook

لضمان التسليم الموثوق وتجنب انتهاء مهلة Webhook، يُرجى الالتزام بالإرشادات التالية:

*   **مهلة الاستجابة:** يجب أن يُعيد خادمك رمز حالة `2xx` خلال **10 ثوانٍ** من استلام الحمولة.
*   **المعالجة غير المتزامنة:** أكّد استلام Webhook فوراً، ثم عالج عمليات قاعدة البيانات ومنطق العمل والإشعارات الخارجية بشكل غير متزامن (مثلاً باستخدام طابور أو عامل في الخلفية).
*   **إزالة التكرار والتحقق من الأحادية:** استخدم `event_id` المقدَّم في غلاف الحمولة لضمان المعالجة الأحادية. احتفظ بسجل لمعرّفات الأحداث المعالجة وتخطَّ المعالجة إذا سبق رؤية المعرّف.
*   **توقّع التسليم المكرر:** يجب أن تكون نقطة النهاية الخاصة بك مستعدة للتعامل مع التسليمات المكررة بسلاسة في حال إعادة المحاولة عند فشل الشبكة أو مشاكل الاتصال العابرة.

إنشاء بديل للطرد

POST /packages/replacement

الوصف: إنشاء طرد أو طردين لاستبدال طرد موجود. يحدد حقل rule عدد الطرود المطلوبة وaction الذي يجب أن ينفذه كل طرد.

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

القواعد

القاعدة	الطرود المطلوبة	الإجراءات المطلوبة
`deliver`	1	`action = deliver`
`return`	1	`action = return`
`return_deliver`	2	إجراء `return` وإجراء `deliver`

الطلب

المعامل	النوع	الوصف
`rule`	`string`	مطلوب. أحد القيم: `deliver`، `return`، `return_deliver`
`packages`	`array`	مطلوب. من 1 إلى 2 كائن طرد، يجب أن تستوفي قيود `rule`

كائن الطرد

يجب أن يتوافق كل عنصر في مصفوفة packages مع الهيكل التالي:

المعامل	النوع	الوصف
`action`	`string`	مطلوب. أحد القيم: `deliver`، `return`، يجب أن يتوافق مع `rule`
`partner_ref`	`string`	مطلوب. يجب أن يكون فريداً
`customer_name`	`string`	مطلوب
`customer_phone_1`	`string`	مطلوب. رقم جوال صالح
`customer_phone_2`	`string`	اختياري
`source_country_iso2`	`string`	مطلوب. رمز دولة ISO2 صالح
`source_address_line_1`	`string`	مطلوب
`source_address_line_2`	`string`	اختياري
`destination_country_iso2`	`string`	مطلوب. رمز دولة ISO2 صالح
`destination_region`	`string`	مطلوب إذا كان `region_id` غائباً
`destination_city`	`string`	مطلوب
`destination_address_line_1`	`string`	مطلوب
`destination_address_line_2`	`string`	اختياري
`destination_postal_code`	`string`	اختياري
`landmark`	`string`	اختياري
`region_id`	`integer`	مطلوب إذا كان `destination_region` غائباً
`length`	`decimal`	اختياري
`height`	`decimal`	اختياري
`weight`	`decimal`	اختياري
`description`	`string`	مطلوب
`units`	`number`	مطلوب
`type`	`string`	مطلوب. أحد القيم: `parcel`، `box`
`value`	`decimal`	مطلوب. الحد الأدنى `0`
`amount_to_collect`	`decimal`	اختياري. الحد الأدنى `0`
`handling`	`string`	مطلوب. أحد القيم: `normal`، `fragile`
`payment_collector`	`string`	اختياري، من بين: `shaq`، `partner` (لا يمكن إرسال هذا المعامل إلا عندما تكون ShaQ Express هي جامعة الدفع. يحدد من المسؤول عن تحصيل الدفعة من العميل، ومخصص للحالات الخاصة التي يتولى فيها الشريك التحصيل. في حال عدم توفيره، يُستخدم إعداد جامع الدفع المتفق عليه افتراضياً.)
`items`	`array`	مطلوب. مصفوفة من `{ name: string, quantity: number }`، يمكن أن تكون فارغة
`special_instructions`	`string`	اختياري
`latitude`	`decimal`	اختياري
`longitude`	`decimal`	اختياري

الاستجابة

200

{
  "message": "Package replacement created successfully",
  "data": [
    {
      "partnerRef": "GH945214",
      "trackingNumber": "9F0FD9D5",
      "customerName": "Derrick Nti",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "deliver",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    },
    {
      "partnerRef": "GH545728",
      "trackingNumber": "A797CA0A",
      "customerName": "Kwabena Azaglo",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "return",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    }
  ]
}

الحصول على ملصق الطرد

GET /packages/{partnerRef}/print-label

الحصول على ملصق طرد محدد

الترويسات

المعامل	النوع	الوصف
`Authorization`	`bearer`	مطلوب.

الاستجابة

200

{
  "message": "Label ready",
  "data": {
    "url": "https://d167icvhk5jowg.cloudfront.net/labels/20250410X51DIQ.pdf"
  }
}

202

{
  "message": "Label generation started. Please retry shortly.",
  "data": null
}

404

{
  "message": "Package not found",
  "data": null
}

المعامل	النوع	الوصف
`identifier`	`string`	مطلوب.
`secret`	`string`	مطلوب.