مرجع API

المرجع الكامل لنقاط نهاية منفذ، مولّد من مواصفة OpenAPI نفسها التي تستهلكها أدواتك.

ملف OpenAPI الخام مجموعة Postmanالإصدار 1.0.0

جميع المسارات أدناه نسبية إلى /api/v1. كل النقاط تتطلب المصادقة بمفتاح Bearer — راجع صفحة المصادقة.

الناقلون وخدماتهم

GET/carriersقائمة الناقلين

يعيد جميع الناقلين المتاحين في منفذ مع مستويات الخدمة ونطاق التغطية لكل ناقل.

الاستجابات

200قائمة الناقلين

carriersarray<Carrier>

codestring

name_arstring

name_enstring

integration_typestring

rest · rest_legacy · csv_batch

coverage_countriesarray<string>

دول التغطية (ISO alpha-2)

service_levelsarray<object>

codestring

name_arstring

name_enstring

modestring

air · sea · land · express

transit_daysobject

mininteger

maxinteger

{
  "carriers": [
    {
      "code": "SARIE",
      "name_ar": "سريع إكسبريس",
      "name_en": "Sarie Express",
      "integration_type": "rest",
      "coverage_countries": [
        "SA",
        "AE",
        "KW",
        "BH",
        "QA",
        "OM"
      ],
      "service_levels": [
        {
          "code": "EXP_DOM",
          "name_ar": "إكسبريس محلي",
          "name_en": "Domestic Express",
          "mode": "express",
          "transit_days": {
            "min": 1,
            "max": 3
          }
        },
        {
          "code": "EXP_GCC",
          "name_ar": "إكسبريس خليجي",
          "name_en": "GCC Express",
          "mode": "express",
          "transit_days": {
            "min": 2,
            "max": 5
          }
        }
      ]
    },
    {
      "code": "BARR",
      "name_ar": "بر وبحر",
      "name_en": "Barr wa Bahr",
      "integration_type": "rest_legacy",
      "coverage_countries": [
        "IQ",
        "JO",
        "EG",
        "MA",
        "TR",
        "IT",
        "DE",
        "GB",
        "US",
        "CN",
        "IN"
      ],
      "service_levels": [
        {
          "code": "SEA_STD",
          "name_ar": "بحري عادي",
          "name_en": "Sea Standard",
          "mode": "sea",
          "transit_days": {
            "min": 20,
            "max": 45
          }
        },
        {
          "code": "LAND_STD",
          "name_ar": "بري عادي",
          "name_en": "Land Standard",
          "mode": "land",
          "transit_days": {
            "min": 7,
            "max": 20
          }
        },
        {
          "code": "SEA_EXP",
          "name_ar": "بحري سريع",
          "name_en": "Sea Expedited",
          "mode": "sea",
          "transit_days": {
            "min": 14,
            "max": 30
          }
        }
      ]
    },
    {
      "code": "MAKHZOON",
      "name_ar": "مخزون بلس",
      "name_en": "Makhzoon Plus",
      "integration_type": "csv_batch",
      "coverage_countries": [
        "SA"
      ],
      "service_levels": [
        {
          "code": "FULFIL_STD",
          "name_ar": "تنفيذ محلي",
          "name_en": "Standard Fulfilment",
          "mode": "land",
          "transit_days": {
            "min": 1,
            "max": 4
          }
        }
      ]
    }
  ]
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/carriers

curl -s "https://manfath.example/api/v1/carriers" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

التسعير وعروض الأسعار

POST/ratesطلب تسعيرات الشحن

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

جسم الطلبapplication/json

originAddressمطلوب

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddressمطلوب

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>مطلوب

الطرود؛ الوزن بالكيلوغرام والأبعاد بالسنتيمتر

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_valuenumber

القيمة المصرّح بها للشحنة

declared_value_currencystring

عملة القيمة المصرّح بها بصيغة ISO 4217، مثل SAR

incotermstring

شرط التسليم التجاري

EXW · FOB · CIF · DAP · DDP

hs_codesarray<string>

رموز النظام المنسق للبضاعة

cod_amountnumber

مبلغ الدفع عند الاستلام بالريال

مثال

{
  "origin": {
    "country": "SA",
    "city": "Riyadh",
    "short_address": "RRDA2929"
  },
  "destination": {
    "country": "AE",
    "city": "Dubai",
    "line1": "Al Wasl Road 214"
  },
  "parcels": [
    {
      "weight_kg": 2.5,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }
  ],
  "declared_value": 450,
  "declared_value_currency": "SAR",
  "incoterm": "DAP",
  "hs_codes": [
    "330499"
  ],
  "cod_amount": 0
}

الاستجابات

200التسعيرات المتاحة

quotesarray<Quote>

quote_idstring

carrierCarrierRef

مرجع الناقل

codestring

name_arstring

name_enstring

serviceServiceRef

مرجع مستوى الخدمة

codestring

name_arstring

name_enstring

modestring

وسيلة النقل

air · sea · land · express

transit_daysobject

mininteger

maxinteger

weightsobject

الأوزان: الفعلي والحجمي والقابل للفوترة

actual_kgnumber

volumetric_kgnumber

chargeable_kgnumber

الأعلى بين الفعلي والحجمي، مقربًا لأعلى إلى 0.5 كغ

volumetric_divisorinteger

weight_break_appliedstring

breakdownarray<BreakdownItem>

codestring

رمز البند، مثل base أو weight_charge أو fuel_surcharge أو vat

label_enstring

label_arstring

amount_sarnumber

total_sarnumber

currencystring

expires_atstring (date-time)

انتهاء صلاحية التسعيرة (15 دقيقة من الإصدار)

{
  "quotes": [
    {
      "quote_id": "cmdg7f3k2a0001x8p9zr41mstq",
      "carrier": {
        "code": "SARIE",
        "name_ar": "سريع إكسبريس",
        "name_en": "Sarie Express"
      },
      "service": {
        "code": "EXP_GCC",
        "name_ar": "إكسبريس خليجي",
        "name_en": "GCC Express",
        "mode": "express"
      },
      "transit_days": {
        "min": 2,
        "max": 5
      },
      "weights": {
        "actual_kg": 2.5,
        "volumetric_kg": 1.8,
        "chargeable_kg": 2.5,
        "volumetric_divisor": 5000,
        "weight_break_applied": "upto_5_kg"
      },
      "breakdown": [
        {
          "code": "base",
          "label_en": "Base charge",
          "label_ar": "الرسم الأساسي",
          "amount_sar": 15
        },
        {
          "code": "weight_charge",
          "label_en": "Weight charge",
          "label_ar": "رسم الوزن",
          "amount_sar": 50
        },
        {
          "code": "fuel_surcharge",
          "label_en": "Fuel surcharge",
          "label_ar": "رسم الوقود",
          "amount_sar": 9.75
        },
        {
          "code": "vat",
          "label_en": "VAT 15%",
          "label_ar": "ضريبة القيمة المضافة 15%",
          "amount_sar": 11.21
        }
      ],
      "total_sar": 85.96,
      "currency": "SAR",
      "expires_at": "2026-07-26T10:15:00+03:00"
    }
  ]
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

422فشل التحقق من صحة الطلب

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_VALIDATION",
    "message_en": "Request validation failed.",
    "message_ar": "فشل التحقق من صحة الطلب."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/rates

curl -s -X POST "https://manfath.example/api/v1/rates" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": {
    "country": "SA",
    "city": "Riyadh",
    "short_address": "RRDA2929"
  },
  "destination": {
    "country": "AE",
    "city": "Dubai",
    "line1": "Al Wasl Road 214"
  },
  "parcels": [
    {
      "weight_kg": 2.5,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }
  ],
  "declared_value": 450,
  "declared_value_currency": "SAR",
  "incoterm": "DAP",
  "hs_codes": [
    "330499"
  ],
  "cod_amount": 0
}'

الشحنات والتتبع

GET/shipmentsقائمة الشحنات

يعيد شحنات فريقك مرتبة من الأحدث إلى الأقدم، مع إمكانية الترشيح حسب الحالة.

المعاملات

الاسم	الموضع	النوع	الوصف
`status`	query	string	ترشيح حسب الحالة
`limit`	query	integer	عدد النتائج (الافتراضي 20، الأقصى 100)
`offset`	query	integer	الإزاحة (الافتراضي 0)

الاستجابات

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

shipmentsarray<Shipment>

idstring

tracking_numberstring

manfath_referencestring

statusstring

CREATED · LABEL_GENERATED · PICKUP_SCHEDULED · PICKED_UP · AT_ORIGIN_HUB · DEPARTED_ORIGIN · IN_TRANSIT · ARRIVED_DESTINATION_COUNTRY · CUSTOMS_CLEARANCE · CUSTOMS_CLEARED · AT_DELIVERY_HUB · OUT_FOR_DELIVERY · DELIVERED · EXCEPTION_CUSTOMS_HOLD · EXCEPTION_ADDRESS_ISSUE · EXCEPTION_WEIGHT_MISMATCH · EXCEPTION_FAILED_DELIVERY_ATTEMPT · EXCEPTION_CARRIER_DELAY · RETURN_TO_ORIGIN · RETURNED · LOST · CANCELLED

status_arstring

status_enstring

carrierCarrierRef

مرجع الناقل

codestring

name_arstring

name_enstring

serviceServiceRef

مرجع مستوى الخدمة

codestring

name_arstring

name_enstring

modestring

وسيلة النقل

air · sea · land · express

originAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_value_sarnumber

incotermstring

hs_codesarray<string>

cod_amount_sarnumber

label_urlstring

مسار بوليصة الشحن PDF

warningsarray<Warning>

تنبيهات غير مانعة إن وجدت

codestring

message_enstring

message_arstring

quoted_total_sarnumber

estimated_delivery_atstring (date-time)

created_atstring (date-time)

totalinteger

limitinteger

offsetinteger

{
  "shipments": [
    {
      "id": "cmdg8s1t20003x8p9aqk2v7hu",
      "tracking_number": "SRE0248817359",
      "manfath_reference": "MNF-2026-K7Q2ZC",
      "status": "CREATED",
      "status_ar": "تم إنشاء الشحنة",
      "status_en": "Shipment created",
      "carrier": {
        "code": "SARIE",
        "name_ar": "سريع إكسبريس",
        "name_en": "Sarie Express"
      },
      "service": {
        "code": "EXP_DOM",
        "name_ar": "إكسبريس محلي",
        "name_en": "Domestic Express",
        "mode": "express"
      },
      "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_sar": 450,
      "incoterm": "DAP",
      "hs_codes": [
        "330499"
      ],
      "cod_amount_sar": 0,
      "label_url": "/api/v1/labels/cmdg8s1t20003x8p9aqk2v7hu",
      "warnings": [],
      "quoted_total_sar": 63.25,
      "estimated_delivery_at": "2026-07-28T17:00:00+03:00",
      "created_at": "2026-07-26T09:12:00+03:00"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/shipments

curl -s "https://manfath.example/api/v1/shipments" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

POST/shipmentsإنشاء شحنة

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

جسم الطلبapplication/json

quote_idstringمطلوب

معرّف التسعيرة من POST /rates (صالحة 15 دقيقة)

originAddressمطلوب

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddressمطلوب

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>مطلوب

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_valuenumber

القيمة المصرّح بها بالريال

incotermstring

شرط التسليم التجاري

EXW · FOB · CIF · DAP · DDP

hs_codesarray<string>

رموز النظام المنسق للبضاعة

cod_amountnumber

مبلغ الدفع عند الاستلام بالريال

referencestring

مرجعك الداخلي للطلب

مثال

{
  "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تم إنشاء الشحنة

Shipment

شحنة

idstring

tracking_numberstring

manfath_referencestring

statusstring

status_arstring

status_enstring

carrierCarrierRef

مرجع الناقل

codestring

name_arstring

name_enstring

serviceServiceRef

مرجع مستوى الخدمة

codestring

name_arstring

name_enstring

modestring

وسيلة النقل

air · sea · land · express

originAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_value_sarnumber

incotermstring

hs_codesarray<string>

cod_amount_sarnumber

label_urlstring

مسار بوليصة الشحن PDF

warningsarray<Warning>

تنبيهات غير مانعة إن وجدت

codestring

message_enstring

message_arstring

quoted_total_sarnumber

estimated_delivery_atstring (date-time)

created_atstring (date-time)

{
  "id": "cmdg8s1t20003x8p9aqk2v7hu",
  "tracking_number": "SRE0248817359",
  "manfath_reference": "MNF-2026-K7Q2ZC",
  "status": "CREATED",
  "status_ar": "تم إنشاء الشحنة",
  "status_en": "Shipment created",
  "carrier": {
    "code": "SARIE",
    "name_ar": "سريع إكسبريس",
    "name_en": "Sarie Express"
  },
  "service": {
    "code": "EXP_DOM",
    "name_ar": "إكسبريس محلي",
    "name_en": "Domestic Express",
    "mode": "express"
  },
  "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_sar": 450,
  "incoterm": "DAP",
  "hs_codes": [
    "330499"
  ],
  "cod_amount_sar": 0,
  "label_url": "/api/v1/labels/cmdg8s1t20003x8p9aqk2v7hu",
  "warnings": [],
  "quoted_total_sar": 63.25,
  "estimated_delivery_at": "2026-07-28T17:00:00+03:00",
  "created_at": "2026-07-26T09:12:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

409انتهت صلاحية التسعيرة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_QUOTE_EXPIRED",
    "message_en": "This quote has expired. Quotes are valid for 15 minutes. Request a new rate.",
    "message_ar": "انتهت صلاحية هذه التسعيرة. التسعيرات صالحة لمدة 15 دقيقة. اطلب تسعيرة جديدة."
  }
}

422فشل التحقق أو عنوان الوجهة غير مطابق للعنوان الوطني

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

E_VALIDATION

{
  "error": {
    "code": "E_VALIDATION",
    "message_en": "Request validation failed.",
    "message_ar": "فشل التحقق من صحة الطلب.",
    "details": {
      "field": "parcels.0.weight_kg",
      "reason": "must be a positive number"
    }
  }
}

E_ADDRESS_NOT_NORMALISED

{
  "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"
      ]
    }
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/shipments

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"
}'

GET/shipments/{id}تفاصيل شحنة

يعيد تفاصيل الشحنة كاملة بحالتها الراهنة.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

الاستجابات

200الشحنة

Shipment

شحنة

idstring

tracking_numberstring

manfath_referencestring

statusstring

status_arstring

status_enstring

carrierCarrierRef

مرجع الناقل

codestring

name_arstring

name_enstring

serviceServiceRef

مرجع مستوى الخدمة

codestring

name_arstring

name_enstring

modestring

وسيلة النقل

air · sea · land · express

originAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_value_sarnumber

incotermstring

hs_codesarray<string>

cod_amount_sarnumber

label_urlstring

مسار بوليصة الشحن PDF

warningsarray<Warning>

تنبيهات غير مانعة إن وجدت

codestring

message_enstring

message_arstring

quoted_total_sarnumber

estimated_delivery_atstring (date-time)

created_atstring (date-time)

{
  "id": "cmdg8s1t20003x8p9aqk2v7hu",
  "tracking_number": "SRE0248817359",
  "manfath_reference": "MNF-2026-K7Q2ZC",
  "status": "CREATED",
  "status_ar": "تم إنشاء الشحنة",
  "status_en": "Shipment created",
  "carrier": {
    "code": "SARIE",
    "name_ar": "سريع إكسبريس",
    "name_en": "Sarie Express"
  },
  "service": {
    "code": "EXP_DOM",
    "name_ar": "إكسبريس محلي",
    "name_en": "Domestic Express",
    "mode": "express"
  },
  "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_sar": 450,
  "incoterm": "DAP",
  "hs_codes": [
    "330499"
  ],
  "cod_amount_sar": 0,
  "label_url": "/api/v1/labels/cmdg8s1t20003x8p9aqk2v7hu",
  "warnings": [],
  "quoted_total_sar": 63.25,
  "estimated_delivery_at": "2026-07-28T17:00:00+03:00",
  "created_at": "2026-07-26T09:12:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/shipments/{id}

curl -s "https://manfath.example/api/v1/shipments/cmdg8s1t20003x8p9aqk2v7hu" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

GET/shipments/{id}/trackingأحداث تتبع الشحنة

يعيد أحداث التتبع للشحنة مرتبة من الأحدث إلى الأقدم.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

الاستجابات

200أحداث التتبع

tracking_numberstring

statusstring

eventsarray<TrackingEvent>

أحداث التتبع

codestring

رمز الحالة

status_arstring

status_enstring

location_arstring

location_enstring

occurred_atstring (date-time)

is_exceptionboolean

exception_typestring

نوع الاستثناء عندما يكون الحدث استثناءً

CUSTOMS_HOLD · ADDRESS_ISSUE · WEIGHT_MISMATCH · FAILED_DELIVERY_ATTEMPT · CARRIER_DELAY

{
  "tracking_number": "SRE0248817359",
  "status": "IN_TRANSIT",
  "events": [
    {
      "code": "IN_TRANSIT",
      "status_ar": "في الطريق",
      "status_en": "In transit",
      "location_ar": "الرياض",
      "location_en": "Riyadh",
      "occurred_at": "2026-07-26T18:40:00+03:00",
      "is_exception": false
    },
    {
      "code": "AT_ORIGIN_HUB",
      "status_ar": "وصلت إلى مركز الفرز في بلد المنشأ",
      "status_en": "Arrived at origin hub",
      "location_ar": "الرياض",
      "location_en": "Riyadh",
      "occurred_at": "2026-07-26T15:05:00+03:00",
      "is_exception": false
    },
    {
      "code": "PICKED_UP",
      "status_ar": "تم الاستلام من المرسل",
      "status_en": "Picked up",
      "location_ar": "الرياض",
      "location_en": "Riyadh",
      "occurred_at": "2026-07-26T13:30:00+03:00",
      "is_exception": false
    },
    {
      "code": "PICKUP_SCHEDULED",
      "status_ar": "تم جدولة الاستلام",
      "status_en": "Pickup scheduled",
      "location_ar": "الرياض",
      "location_en": "Riyadh",
      "occurred_at": "2026-07-26T10:00:00+03:00",
      "is_exception": false
    },
    {
      "code": "CREATED",
      "status_ar": "تم إنشاء الشحنة",
      "status_en": "Shipment created",
      "location_ar": "الرياض",
      "location_en": "Riyadh",
      "occurred_at": "2026-07-26T09:12:00+03:00",
      "is_exception": false
    }
  ]
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/shipments/{id}/tracking

curl -s "https://manfath.example/api/v1/shipments/cmdg8s1t20003x8p9aqk2v7hu/tracking" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

POST/shipments/{id}/cancelإلغاء شحنة

يلغي الشحنة. الإلغاء ممكن قبل استلام الشحنة من المرسل فقط.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

جسم الطلبapplication/json

reasonstring

سبب الإلغاء (اختياري)

مثال

{
  "reason": "طلب العميل إلغاء الشراء"
}

الاستجابات

200أُلغيت الشحنة

idstring

tracking_numberstring

statusstring

status_arstring

status_enstring

cancelled_atstring (date-time)

{
  "id": "cmdg8s1t20003x8p9aqk2v7hu",
  "tracking_number": "SRE0248817359",
  "status": "CANCELLED",
  "status_ar": "أُلغيت الشحنة",
  "status_en": "Cancelled",
  "cancelled_at": "2026-07-26T11:03:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

409لا يمكن الإلغاء بعد الاستلام من المرسل

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_CANCEL_NOT_ALLOWED",
    "message_en": "Shipment can no longer be cancelled after pickup.",
    "message_ar": "لا يمكن إلغاء الشحنة بعد الاستلام من المرسل."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/shipments/{id}/cancel

curl -s -X POST "https://manfath.example/api/v1/shipments/cmdg8s1t20003x8p9aqk2v7hu/cancel" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "طلب العميل إلغاء الشراء"
}'

POST/shipments/{id}/documentsرفع مستندات الشحنة

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

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

جسم الطلبmultipart/form-data

filestring (binary)مطلوب

ملف المستند (PDF)

typestringمطلوب

نوع المستند

commercial_invoice · packing_list · certificate_of_origin · other

الاستجابات

201تم استلام المستند

idstring

shipment_idstring

typestring

filenamestring

uploaded_atstring (date-time)

{
  "id": "cmdgcy4u80009x8p9m1tq8r3z",
  "shipment_id": "cmdg8s1t20003x8p9aqk2v7hu",
  "type": "commercial_invoice",
  "filename": "invoice-PO-10422.pdf",
  "uploaded_at": "2026-07-26T12:40:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

422ملف أو نوع غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_VALIDATION",
    "message_en": "Request validation failed.",
    "message_ar": "فشل التحقق من صحة الطلب."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/shipments/{id}/documents

curl -s -X POST "https://manfath.example/api/v1/shipments/cmdg8s1t20003x8p9aqk2v7hu/documents" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -F "file=@document.pdf" \
  -F "type=commercial_invoice"

PATCH/shipments/{id}/destinationتحديث عنوان الوجهة

يحدّث عنوان وجهة الشحنة، مثلًا لمعالجة مشكلة في عنوان التسليم. تنطبق قواعد العنوان الوطني السعودي نفسها المذكورة عند إنشاء الشحنة.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

جسم الطلبapplication/json

Address

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

مثال

{
  "name": "عبدالله القحطاني",
  "line1": "حي السلامة",
  "country": "SA",
  "city": "Jeddah",
  "postal_code": "23525",
  "additional_number": "7712",
  "phone": "966555112233"
}

الاستجابات

200تم تحديث الوجهة

Shipment

شحنة

idstring

tracking_numberstring

manfath_referencestring

statusstring

status_arstring

status_enstring

carrierCarrierRef

مرجع الناقل

codestring

name_arstring

name_enstring

serviceServiceRef

مرجع مستوى الخدمة

codestring

name_arstring

name_enstring

modestring

وسيلة النقل

air · sea · land · express

originAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

destinationAddress

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

namestring

اسم جهة الاتصال أو المنشأة

line1string

سطر العنوان

citystringمطلوب

regionstring

المنطقة

countrystringمطلوب

رمز الدولة ISO 3166-1 alpha-2

postal_codestring

الرمز البريدي (5 أرقام داخل المملكة)

additional_numberstring

الرقم الإضافي للعنوان الوطني (4 أرقام)

short_addressstring

العنوان الوطني المختصر، مثل RRDA2929

phonestring

رقم الجوال بصيغة 9665XXXXXXXX

parcelsarray<Parcel>

weight_kgnumberمطلوب

الوزن بالكيلوغرام

length_cmnumberمطلوب

الطول بالسنتيمتر

width_cmnumberمطلوب

العرض بالسنتيمتر

height_cmnumberمطلوب

الارتفاع بالسنتيمتر

declared_value_sarnumber

incotermstring

hs_codesarray<string>

cod_amount_sarnumber

label_urlstring

مسار بوليصة الشحن PDF

warningsarray<Warning>

تنبيهات غير مانعة إن وجدت

codestring

message_enstring

message_arstring

quoted_total_sarnumber

estimated_delivery_atstring (date-time)

created_atstring (date-time)

{
  "id": "cmdg8s1t20003x8p9aqk2v7hu",
  "tracking_number": "SRE0248817359",
  "manfath_reference": "MNF-2026-K7Q2ZC",
  "status": "CREATED",
  "status_ar": "تم إنشاء الشحنة",
  "status_en": "Shipment created",
  "carrier": {
    "code": "SARIE",
    "name_ar": "سريع إكسبريس",
    "name_en": "Sarie Express"
  },
  "service": {
    "code": "EXP_DOM",
    "name_ar": "إكسبريس محلي",
    "name_en": "Domestic Express",
    "mode": "express"
  },
  "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_sar": 450,
  "incoterm": "DAP",
  "hs_codes": [
    "330499"
  ],
  "cod_amount_sar": 0,
  "label_url": "/api/v1/labels/cmdg8s1t20003x8p9aqk2v7hu",
  "warnings": [],
  "quoted_total_sar": 63.25,
  "estimated_delivery_at": "2026-07-28T17:00:00+03:00",
  "created_at": "2026-07-26T09:12:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

422العنوان غير مطابق للعنوان الوطني

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

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

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

PATCH /api/v1/shipments/{id}/destination

curl -s -X PATCH "https://manfath.example/api/v1/shipments/cmdg8s1t20003x8p9aqk2v7hu/destination" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "عبدالله القحطاني",
  "line1": "حي السلامة",
  "country": "SA",
  "city": "Jeddah",
  "postal_code": "23525",
  "additional_number": "7712",
  "phone": "966555112233"
}'

بوليصات الشحن

GET/labels/{id}بوليصة الشحن (PDF)

يعيد بوليصة الشحن بصيغة PDF بمقاس A6، متضمنة الرمز الشريطي ورمز الاستجابة السريعة للتتبع.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الشحنة في منفذ

الاستجابات

200ملف البوليصة

application/pdf — ملف ثنائي

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الشحنة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/labels/{id}

curl -s "https://manfath.example/api/v1/labels/cmdg8s1t20003x8p9aqk2v7hu" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -o label.pdf

الإشعارات الفورية

POST/webhooks/configإعداد Webhooks

سجّل عنوان HTTPS لاستقبال إشعارات فورية عن أحداث الشحنات: shipment.created وshipment.status_updated وshipment.delivered وshipment.exception. تعيد الاستجابة سرّ Webhook الخاص بفريقك؛ نوقّع الحمولة بسرّك.

جسم الطلبapplication/json

urlstring (uri)مطلوب

عنوان HTTPS الذي يستقبل الإشعارات

eventsarray<string>

الأحداث المطلوبة (الافتراضي: الكل)

مثال

{
  "url": "https://example.sa/manfath/hook",
  "events": [
    "shipment.status_updated",
    "shipment.exception"
  ]
}

الاستجابات

200تم حفظ الإعداد

urlstring (uri)

eventsarray<string>

secretstring

سرّ Webhook الخاص بفريقك

{
  "url": "https://example.sa/manfath/hook",
  "events": [
    "shipment.status_updated",
    "shipment.exception"
  ],
  "secret": "whsec_9f2c4a7d1e8b3f6c5a0d9e2b4c7f1a3d"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

422عنوان غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_VALIDATION",
    "message_en": "Request validation failed.",
    "message_ar": "فشل التحقق من صحة الطلب."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/webhooks/config

curl -s -X POST "https://manfath.example/api/v1/webhooks/config" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.sa/manfath/hook",
  "events": [
    "shipment.status_updated",
    "shipment.exception"
  ]
}'

الفواتير

GET/invoices/currentالفاتورة الحالية

يعيد فاتورة فترة الفوترة الحالية لفريقك بجميع بنودها، شاملة ضريبة القيمة المضافة 15%.

الاستجابات

200الفاتورة

Invoice

فاتورة فترة الفوترة

idstring

period_startstring (date)

period_endstring (date)

line_itemsarray<InvoiceLineItem>

shipment_idstring

tracking_numberstring

descriptionstring

description_arstring

amount_sarnumber

causestring

سبب البند

subtotal_sarnumber

surcharges_sarnumber

vat_sarnumber

ضريبة القيمة المضافة 15%

total_sarnumber

updated_atstring (date-time)

{
  "id": "cmdgb1p9e0007x8p9w3nq5d2k",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "line_items": [
    {
      "shipment_id": "cmdg8s1t20003x8p9aqk2v7hu",
      "tracking_number": "SRE0248817359",
      "description": "Shipment SRE0248817359 — Domestic Express",
      "description_ar": "شحنة SRE0248817359 — إكسبريس محلي",
      "amount_sar": 55,
      "cause": "shipment"
    }
  ],
  "subtotal_sar": 55,
  "surcharges_sar": 0,
  "vat_sar": 8.25,
  "total_sar": 63.25,
  "updated_at": "2026-07-26T09:12:04+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/invoices/current

curl -s "https://manfath.example/api/v1/invoices/current" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

جاهزية بيانات الكتالوج

POST/data-readinessتقييم جاهزية البيانات

يفحص كتالوج منتجات فريقك ويقيّم اكتمال البيانات اللازمة للشحن الدولي: رموز النظام المنسق، الأوزان، الأبعاد، وبلد المنشأ، ثم يعيد درجة من 100 مع قائمة مفصلة بالمشكلات.

الاستجابات

200تقرير الجاهزية

DataReadinessReport

تقرير جاهزية بيانات الكتالوج

scoreinteger

الدرجة من 100

total_skusinteger

issuesarray<object>

skustring

fieldstring

severitystring

error · warn

message_arstring

message_enstring

summaryobject

missing_hs_codeinteger

missing_weightinteger

missing_dimensionsinteger

missing_origin_countryinteger

suspicious_valuesinteger

{
  "score": 52,
  "total_skus": 84,
  "issues": [
    {
      "sku": "SKU-1042",
      "field": "hs_code",
      "severity": "error",
      "message_ar": "رمز النظام المنسق مفقود",
      "message_en": "HS code is missing"
    },
    {
      "sku": "SKU-1108",
      "field": "weight_grams",
      "severity": "warn",
      "message_ar": "الوزن غير منطقي لهذا الصنف",
      "message_en": "Weight looks implausible for this item"
    }
  ],
  "summary": {
    "missing_hs_code": 29,
    "missing_weight": 17,
    "missing_dimensions": 38,
    "missing_origin_country": 21,
    "suspicious_values": 2
  }
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/data-readiness

curl -s -X POST "https://manfath.example/api/v1/data-readiness" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

دفعات مخزون بلس

POST/makhzoon/batchesرفع دفعة طلبات مخزون بلس

ارفع ملف CSV بطلبات التنفيذ المحلي. يجب أن يطابق صف العناوين تمامًا بالترتيب والأسماء: order_ref,recipient_name_ar,recipient_name_latin,phone,city,district,short_address,sku,qty,cod_amount_sar,notes أي خطأ في أي صف يؤدي إلى رفض الملف كاملًا. تتم المعالجة بشكل غير متزامن — استعلم عن النتيجة عبر GET /makhzoon/batches/{id}.

جسم الطلبmultipart/form-data

filestring (binary)مطلوب

ملف CSV بترميز UTF-8

الاستجابات

202الدفعة قيد المعالجة

MakhzoonBatch

دفعة طلبات مخزون بلس

idstring

statusstring

PROCESSING · COMPLETED · REJECTED

filenamestring

row_countinteger

accepted_countinteger

rejected_countinteger

result_csvstring | null

CSV النتائج عند الاكتمال، بعمودي tracking_number وstatus إضافة إلى أعمدة الملف الأصلي

rejection_csvstring | null

CSV أسباب الرفض عند رفض الملف: row_number,field,reason_ar,reason_en

created_atstring (date-time)

{
  "id": "cmdgh7w2b000bx8p9t5kq2n8j",
  "status": "PROCESSING",
  "filename": "orders-2026-07-26.csv",
  "row_count": 24,
  "accepted_count": 0,
  "rejected_count": 0,
  "result_csv": null,
  "rejection_csv": null,
  "created_at": "2026-07-26T13:10:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

422ملف مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_VALIDATION",
    "message_en": "Request validation failed.",
    "message_ar": "فشل التحقق من صحة الطلب."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/makhzoon/batches

curl -s -X POST "https://manfath.example/api/v1/makhzoon/batches" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -F "file=@orders.csv"

GET/makhzoon/batches/{id}حالة دفعة مخزون بلس

يعيد حالة الدفعة ونتيجتها: عند الاكتمال يتضمن result_csv عمودي tracking_number وstatus، وعند الرفض يتضمن rejection_csv أسباب رفض كل صف.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`مطلوب	path	string	معرّف الدفعة

الاستجابات

200الدفعة

MakhzoonBatch

دفعة طلبات مخزون بلس

idstring

statusstring

PROCESSING · COMPLETED · REJECTED

filenamestring

row_countinteger

accepted_countinteger

rejected_countinteger

result_csvstring | null

CSV النتائج عند الاكتمال، بعمودي tracking_number وstatus إضافة إلى أعمدة الملف الأصلي

rejection_csvstring | null

CSV أسباب الرفض عند رفض الملف: row_number,field,reason_ar,reason_en

created_atstring (date-time)

{
  "id": "cmdgh7w2b000bx8p9t5kq2n8j",
  "status": "COMPLETED",
  "filename": "orders-2026-07-26.csv",
  "row_count": 24,
  "accepted_count": 24,
  "rejected_count": 0,
  "result_csv": "order_ref,recipient_name_ar,recipient_name_latin,phone,city,district,short_address,sku,qty,cod_amount_sar,notes,tracking_number,status\nSO-1001,عبدالله القحطاني,Abdullah Alqahtani,966512345678,Riyadh,العليا,RRDA2929,SKU-100,1,0,,MKZ048112233,CREATED",
  "rejection_csv": null,
  "created_at": "2026-07-26T13:10:00+03:00"
}

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404الدفعة غير موجودة

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

GET /api/v1/makhzoon/batches/{id}

curl -s "https://manfath.example/api/v1/makhzoon/batches/cmdgh7w2b000bx8p9t5kq2n8j" \
  -H "Authorization: Bearer $MANFATH_API_KEY"

التمرير المباشر إلى الناقل

POST/carriers/{code}/passthroughالتمرير المباشر إلى الناقل

يمرر جسم الطلب كما هو إلى واجهة الناقل الأصلية ويعيد استجابة الناقل كما هي. راجع وثائق الناقل لمعرفة الصيغة المطلوبة.

المعاملات

الاسم	الموضع	النوع	الوصف
`code`مطلوب	path	string	رمز الناقل

جسم الطلبapplication/json

carrier-native payload — see carrier documentation

object

الاستجابات

200استجابة الناقل

carrier-native response — see carrier documentation

object

401مفتاح API مفقود أو غير صالح

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_UNAUTHENTICATED",
    "message_en": "Missing or invalid API key. Send Authorization: Bearer mnf_live_...",
    "message_ar": "مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."
  }
}

404ناقل غير معروف

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_NOT_FOUND",
    "message_en": "Resource not found.",
    "message_ar": "المورد غير موجود."
  }
}

429تم تجاوز حد الطلبات (60 في الدقيقة)

ErrorEnvelope

غلاف الأخطاء الموحد

errorobjectمطلوب

codestringمطلوب

رمز الخطأ الآلي

message_enstringمطلوب

message_arstringمطلوب

detailsobject

تفاصيل إضافية إن وجدت

{
  "error": {
    "code": "E_RATE_LIMITED",
    "message_en": "Rate limit exceeded: 60 requests per minute per API key.",
    "message_ar": "تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."
  }
}

أمثلة الاستدعاء

POST /api/v1/carriers/{code}/passthrough

curl -s -X POST "https://manfath.example/api/v1/carriers/SARIE/passthrough" \
  -H "Authorization: Bearer $MANFATH_API_KEY"