الشحنات

الشحنة هي الكائن المركزي في منفذ: تُنشأ من تسعيرة، وتحمل رقم تتبع وبوليصة، وتتحرك عبر نموذج حالات موحّد حتى التسليم.

إنشاء شحنة

الطريقة الموصى بها هي الإنشاء من تسعيرة سارية: مرّر quote_id الذي حصلت عليه من POST /api/v1/rates خلال 15 دقيقة من إصداره، فيثبت السعر المعروض.

يمكن أيضًا الإنشاء المباشر دون تسعيرة مسبقة بتحديد رمز الناقل والخدمة مع بيانات الشحنة نفسها، وعندها يُحسب السعر لحظة الإنشاء بالتعرفة السارية.

curl -s -X POST "https://manfath.example/api/v1/shipments" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "quote_id": "cmdg7f3k2a0001x8p9zr41mstq",
  "origin": {
    "name": "مستودع الرياض",
    "line1": "طريق الملك فهد",
    "country": "SA",
    "city": "Riyadh",
    "short_address": "RRDA2929",
    "phone": "966512345678"
  },
  "destination": {
    "name": "عبدالله القحطاني",
    "line1": "حي الروضة",
    "country": "SA",
    "city": "Jeddah",
    "short_address": "JHFB8823",
    "phone": "966555112233"
  },
  "parcels": [
    { "weight_kg": 2.5, "length_cm": 30, "width_cm": 20, "height_cm": 15 }
  ],
  "declared_value": 450,
  "incoterm": "DAP",
  "hs_codes": ["330499"],
  "cod_amount": 0,
  "reference": "PO-10422"
}'

عند النجاح تعود الاستجابة بالرمز 201 متضمنة رقم التتبع (tracking_number)، ومرجع منفذ (manfath_reference)، ومسار البوليصة (label_url).

وقد تتضمن الاستجابة مصفوفة warnings بتنبيهات غير مانعة عن بيانات الشحنة — اقرأها ولا تتجاهلها.

متطلبات العنوان السعودي

لكل وجهة داخل المملكة يشترط منفذ عنوانًا وطنيًا مطابقًا قبل إنشاء الشحنة. يقبل النظام أحد شكلين:

• عنوان مختصر من أربعة أحرف لاتينية وأربعة أرقام، مثل JHFB8823
• أو رمز بريدي من 5 أرقام (postal_code) مع رقم إضافي من 4 أرقام (additional_number)

عند غياب الشكلين يُرفض الإنشاء بالرمز 422 E_ADDRESS_NOT_NORMALISED ويخبرك حقل details.missing بالمكوّنات الناقصة:

{
  "error": {
    "code": "E_ADDRESS_NOT_NORMALISED",
    "message_en": "Destination address is not normalised to the Saudi National Address standard.",
    "message_ar": "عنوان الوجهة غير مطابق لمعيار العنوان الوطني السعودي.",
    "details": { "missing": ["postal_code", "additional_number"] }
  }
}

نموذج الحالات

تمر الشحنة بالمسار السعيد التالي من الإنشاء حتى التسليم. الشحنات المحلية داخل المملكة تتخطى مراحل الوصول للوجهة والتخليص الجمركي:

قد تتفرع الرحلة في أي مرحلة إلى حالة استثناء. بعض الاستثناءات تنحل تلقائيًا مثل تأخير الناقل، وبعضها يتطلب إجراء منك: الاحتجاز الجمركي يُعالج برفع المستندات عبر POST /shipments/{id}/documents، ومشكلة العنوان بتحديثه عبر PATCH /shipments/{id}/destination. تفاصيل الاستثناءات في صفحة التتبع.

قواعد الإلغاء

يمكن إلغاء الشحنة عبر POST /api/v1/shipments/{id}/cancel ما دامت لم تُستلم من المرسل — أي في الحالات PICKUP_SCHEDULED وما قبلها. بعد PICKED_UP يعيد الطلب 409 برمز E_CANCEL_NOT_ALLOWED.

الإلغاء نهائي: الحالة CANCELLED طرفية ولا يمكن إعادة تفعيل الشحنة بعدها.

التالي

• التتبع: الأحداث والاستثناءات
• الويبهوكس: إشعارات فورية بكل تغيير حالة