{"openapi":"3.1.0","info":{"title":"منفذ Manfath API","version":"1.0.0","contact":{"name":"فريق منفذ | Manfath Team","email":"api@manfath.example"},"description":"**منفذ** — بوابة موحّدة لخدمات الشحن اللوجستي: تسعير، إنشاء شحنات، تتبع، بوليصات شحن، فواتير، وإشعارات Webhooks عبر عدة ناقلين من واجهة واحدة.\n\n**Manfath** is a unified logistics gateway: rating, shipment creation, tracking, labels, invoicing and webhooks across multiple carriers through a single API.\n\n## المصادقة | Authentication\nأرسل مفتاح فريقك في كل طلب: `Authorization: Bearer mnf_live_...`\n\nSend your team key on every request: `Authorization: Bearer mnf_live_...`\n\n## حدود الطلبات | Rate limits\n60 طلبًا في الدقيقة لكل مفتاح. عند التجاوز تعيد الواجهة 429 مع ترويسة `Retry-After`.\n\n60 requests per minute per key. Exceeding it returns 429 with a `Retry-After` header.\n\n## الوحدات | Units\nالأوزان بالكيلوغرام (kg)، الأبعاد بالسنتيمتر (cm)، المبالغ بالريال السعودي (SAR)، والتواريخ بصيغة ISO 8601.\n\nWeights in kilograms (kg), dimensions in centimetres (cm), amounts in Saudi riyals (SAR), timestamps in ISO 8601.\n\n## رموز الأخطاء | Error codes\nجميع الأخطاء تعيد الغلاف الموحد | All errors return the unified envelope:\n`{ \"error\": { \"code\", \"message_en\", \"message_ar\", \"details\"? } }`\n\n| Code | HTTP | English | العربية |\n|---|---|---|---|\n| `E_UNAUTHENTICATED` | 401 | Missing or invalid API key. Send Authorization: Bearer mnf_live_... | مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_... |\n| `E_VALIDATION` | 422 | Request validation failed. | فشل التحقق من صحة الطلب. |\n| `E_RATE_LIMITED` | 429 | Rate limit exceeded: 60 requests per minute per API key. | تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح. |\n| `E_QUOTE_EXPIRED` | 409 | This quote has expired. Quotes are valid for 15 minutes. Request a new rate. | انتهت صلاحية هذه التسعيرة. التسعيرات صالحة لمدة 15 دقيقة. اطلب تسعيرة جديدة. |\n| `E_ADDRESS_NOT_NORMALISED` | 422 | Destination address is not normalised to the Saudi National Address standard. | عنوان الوجهة غير مطابق لمعيار العنوان الوطني السعودي. |\n| `E_CANCEL_NOT_ALLOWED` | 409 | Shipment can no longer be cancelled after pickup. | لا يمكن إلغاء الشحنة بعد الاستلام من المرسل. |\n| `E_NOT_FOUND` | 404 | Resource not found. | المورد غير موجود. |"},"servers":[{"url":"/api/v1","description":"بيئة منفذ | Manfath environment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Carriers","description":"الناقلون وخدماتهم | Carriers and their services"},{"name":"Rates","description":"التسعير وعروض الأسعار | Rating and quotes"},{"name":"Shipments","description":"الشحنات والتتبع | Shipments and tracking"},{"name":"Labels","description":"بوليصات الشحن | Shipping labels"},{"name":"Webhooks","description":"الإشعارات الفورية | Real-time notifications"},{"name":"Invoices","description":"الفواتير | Billing"},{"name":"Data Readiness","description":"جاهزية بيانات الكتالوج | Catalogue data readiness"},{"name":"Makhzoon","description":"دفعات مخزون بلس | Makhzoon Plus fulfilment batches"},{"name":"Passthrough","description":"التمرير المباشر إلى الناقل | Carrier-native passthrough"}],"paths":{"/carriers":{"get":{"operationId":"listCarriers","tags":["Carriers"],"summary":"قائمة الناقلين | List carriers","description":"يعيد جميع الناقلين المتاحين في منفذ مع مستويات الخدمة ونطاق التغطية لكل ناقل.\n\nReturns all carriers available on Manfath with each carrier's service levels and coverage countries.","responses":{"200":{"description":"قائمة الناقلين | Carrier list","content":{"application/json":{"schema":{"type":"object","properties":{"carriers":{"type":"array","items":{"$ref":"#/components/schemas/Carrier"}}}},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/rates":{"post":{"operationId":"requestRates","tags":["Rates"],"summary":"طلب تسعيرات الشحن | Request shipping rates","description":"يحسب تسعيرات الشحن من جميع الناقلين المؤهلين للمسار والطرود المحددة. كل تسعيرة صالحة لمدة 15 دقيقة من إصدارها. الوزن القابل للفوترة هو الأعلى بين الوزن الفعلي والوزن الحجمي.\n\nComputes quotes from every eligible carrier for the given lane and parcels. Each quote is valid for 15 minutes from issue. Chargeable weight is the greater of actual and volumetric weight.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin","destination","parcels"],"properties":{"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"parcels":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Parcel"},"description":"الطرود؛ الوزن بالكيلوغرام والأبعاد بالسنتيمتر | Parcels; weight in kg, dimensions in cm"},"declared_value":{"type":"number","description":"القيمة المصرّح بها للشحنة | Declared value of the consignment"},"declared_value_currency":{"type":"string","description":"عملة القيمة المصرّح بها بصيغة ISO 4217، مثل SAR | Currency of the declared value (ISO 4217), e.g. SAR"},"incoterm":{"type":"string","enum":["EXW","FOB","CIF","DAP","DDP"],"description":"شرط التسليم التجاري | Incoterm"},"hs_codes":{"type":"array","items":{"type":"string"},"description":"رموز النظام المنسق للبضاعة | Harmonised System codes for the goods"},"cod_amount":{"type":"number","description":"مبلغ الدفع عند الاستلام بالريال | Cash-on-delivery amount in SAR"}}},"example":{"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}}}},"responses":{"200":{"description":"التسعيرات المتاحة | Available quotes","content":{"application/json":{"schema":{"type":"object","properties":{"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}}}},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"422":{"description":"فشل التحقق من صحة الطلب | Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_VALIDATION","message_en":"Request validation failed.","message_ar":"فشل التحقق من صحة الطلب."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments":{"post":{"operationId":"createShipment","tags":["Shipments"],"summary":"إنشاء شحنة | Create a shipment","description":"ينشئ شحنة من تسعيرة سارية. يجب أن يكون عنوان الوجهة داخل المملكة مطابقًا لمعيار العنوان الوطني السعودي: عنوان مختصر، أو رمز بريدي مع رقم إضافي. عند نجاح الإنشاء تُصدر بوليصة الشحن ويبدأ التتبع فورًا.\n\nCreates a shipment from a valid quote. Saudi destination addresses must be normalised to the National Address standard: a short address, or a postal code plus additional number. On success a label is issued and tracking starts immediately.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quote_id","origin","destination","parcels"],"properties":{"quote_id":{"type":"string","description":"معرّف التسعيرة من POST /rates (صالحة 15 دقيقة) | Quote id from POST /rates (valid for 15 minutes)"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"parcels":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Parcel"}},"declared_value":{"type":"number","description":"القيمة المصرّح بها بالريال | Declared value in SAR"},"incoterm":{"type":"string","enum":["EXW","FOB","CIF","DAP","DDP"],"description":"شرط التسليم التجاري | Incoterm"},"hs_codes":{"type":"array","items":{"type":"string"},"description":"رموز النظام المنسق للبضاعة | Harmonised System codes for the goods"},"cod_amount":{"type":"number","description":"مبلغ الدفع عند الاستلام بالريال | Cash-on-delivery amount in SAR"},"reference":{"type":"string","description":"مرجعك الداخلي للطلب | Your internal order reference"}}},"example":{"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"}}}},"responses":{"201":{"description":"تم إنشاء الشحنة | Shipment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"409":{"description":"انتهت صلاحية التسعيرة | Quote has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"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":{"description":"فشل التحقق أو عنوان الوجهة غير مطابق للعنوان الوطني | Validation failed, or destination address not normalised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation":{"summary":"E_VALIDATION","value":{"error":{"code":"E_VALIDATION","message_en":"Request validation failed.","message_ar":"فشل التحقق من صحة الطلب.","details":{"field":"parcels.0.weight_kg","reason":"must be a positive number"}}}},"address_not_normalised":{"summary":"E_ADDRESS_NOT_NORMALISED","value":{"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":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}},"get":{"operationId":"listShipments","tags":["Shipments"],"summary":"قائمة الشحنات | List shipments","description":"يعيد شحنات فريقك مرتبة من الأحدث إلى الأقدم، مع إمكانية الترشيح حسب الحالة.\n\nReturns your team's shipments, newest first, optionally filtered by status.","parameters":[{"name":"status","in":"query","required":false,"description":"ترشيح حسب الحالة | Filter by status","schema":{"type":"string"},"example":"IN_TRANSIT"},{"name":"limit","in":"query","required":false,"description":"عدد النتائج (الافتراضي 20، الأقصى 100) | Page size (default 20, max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","required":false,"description":"الإزاحة (الافتراضي 0) | Offset (default 0)","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"responses":{"200":{"description":"قائمة الشحنات | Shipment list","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments/{id}":{"get":{"operationId":"getShipment","tags":["Shipments"],"summary":"تفاصيل شحنة | Get a shipment","description":"يعيد تفاصيل الشحنة كاملة بحالتها الراهنة.\n\nReturns the full shipment with its current status.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"responses":{"200":{"description":"الشحنة | The shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments/{id}/tracking":{"get":{"operationId":"getShipmentTracking","tags":["Shipments"],"summary":"أحداث تتبع الشحنة | Shipment tracking events","description":"يعيد أحداث التتبع للشحنة مرتبة من الأحدث إلى الأقدم.\n\nReturns the shipment's tracking events, most recent first.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"responses":{"200":{"description":"أحداث التتبع | Tracking events","content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"status":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"description":"أحداث التتبع | The tracking events"}}},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments/{id}/cancel":{"post":{"operationId":"cancelShipment","tags":["Shipments"],"summary":"إلغاء شحنة | Cancel a shipment","description":"يلغي الشحنة. الإلغاء ممكن قبل استلام الشحنة من المرسل فقط.\n\nCancels the shipment. Cancellation is only possible before the shipment is picked up.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"سبب الإلغاء (اختياري) | Cancellation reason (optional)"}}},"example":{"reason":"طلب العميل إلغاء الشراء"}}}},"responses":{"200":{"description":"أُلغيت الشحنة | Shipment cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"status":{"type":"string"},"status_ar":{"type":"string"},"status_en":{"type":"string"},"cancelled_at":{"type":"string","format":"date-time"}}},"example":{"id":"cmdg8s1t20003x8p9aqk2v7hu","tracking_number":"SRE0248817359","status":"CANCELLED","status_ar":"أُلغيت الشحنة","status_en":"Cancelled","cancelled_at":"2026-07-26T11:03:00+03:00"}}}},"401":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"409":{"description":"لا يمكن الإلغاء بعد الاستلام من المرسل | Cancellation no longer possible after pickup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_CANCEL_NOT_ALLOWED","message_en":"Shipment can no longer be cancelled after pickup.","message_ar":"لا يمكن إلغاء الشحنة بعد الاستلام من المرسل."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments/{id}/documents":{"post":{"operationId":"uploadShipmentDocument","tags":["Shipments"],"summary":"رفع مستندات الشحنة | Upload shipment documents","description":"ارفع المستندات الجمركية للشحنة: فاتورة تجارية، قائمة تعبئة، أو شهادة منشأ.\n\nUpload customs documents for the shipment: commercial invoice, packing list, or certificate of origin.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","type"],"properties":{"file":{"type":"string","format":"binary","description":"ملف المستند (PDF) | The document file (PDF)"},"type":{"type":"string","enum":["commercial_invoice","packing_list","certificate_of_origin","other"],"description":"نوع المستند | Document type"}}}}}},"responses":{"201":{"description":"تم استلام المستند | Document received","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"shipment_id":{"type":"string"},"type":{"type":"string"},"filename":{"type":"string"},"uploaded_at":{"type":"string","format":"date-time"}}},"example":{"id":"cmdgcy4u80009x8p9m1tq8r3z","shipment_id":"cmdg8s1t20003x8p9aqk2v7hu","type":"commercial_invoice","filename":"invoice-PO-10422.pdf","uploaded_at":"2026-07-26T12:40:00+03:00"}}}},"401":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"422":{"description":"ملف أو نوع غير صالح | Invalid file or type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_VALIDATION","message_en":"Request validation failed.","message_ar":"فشل التحقق من صحة الطلب."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/shipments/{id}/destination":{"patch":{"operationId":"updateShipmentDestination","tags":["Shipments"],"summary":"تحديث عنوان الوجهة | Update destination address","description":"يحدّث عنوان وجهة الشحنة، مثلًا لمعالجة مشكلة في عنوان التسليم. تنطبق قواعد العنوان الوطني السعودي نفسها المذكورة عند إنشاء الشحنة.\n\nUpdates the shipment's destination address, e.g. to resolve a delivery address issue. The same Saudi National Address rules as at shipment creation apply.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"},"example":{"name":"عبدالله القحطاني","line1":"حي السلامة","country":"SA","city":"Jeddah","postal_code":"23525","additional_number":"7712","phone":"966555112233"}}}},"responses":{"200":{"description":"تم تحديث الوجهة | Destination updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"422":{"description":"العنوان غير مطابق للعنوان الوطني | Address not normalised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_ADDRESS_NOT_NORMALISED","message_en":"Destination address is not normalised to the Saudi National Address standard.","message_ar":"عنوان الوجهة غير مطابق لمعيار العنوان الوطني السعودي."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/labels/{id}":{"get":{"operationId":"getLabel","tags":["Labels"],"summary":"بوليصة الشحن (PDF) | Shipping label (PDF)","description":"يعيد بوليصة الشحن بصيغة PDF بمقاس A6، متضمنة الرمز الشريطي ورمز الاستجابة السريعة للتتبع.\n\nReturns the A6 shipping label as a PDF, including the barcode and the tracking QR code.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الشحنة في منفذ | The Manfath shipment id","schema":{"type":"string"},"example":"cmdg8s1t20003x8p9aqk2v7hu"}],"responses":{"200":{"description":"ملف البوليصة | The label file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الشحنة غير موجودة | Shipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/webhooks/config":{"post":{"operationId":"configureWebhooks","tags":["Webhooks"],"summary":"إعداد Webhooks | Configure webhooks","description":"سجّل عنوان HTTPS لاستقبال إشعارات فورية عن أحداث الشحنات: `shipment.created` و`shipment.status_updated` و`shipment.delivered` و`shipment.exception`. تعيد الاستجابة سرّ Webhook الخاص بفريقك؛ نوقّع الحمولة بسرّك.\n\nRegister an HTTPS endpoint to receive real-time notifications for shipment events: `shipment.created`, `shipment.status_updated`, `shipment.delivered`, `shipment.exception`. The response includes your team's webhook secret; we sign the payload with your secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"عنوان HTTPS الذي يستقبل الإشعارات | The HTTPS endpoint that receives events"},"events":{"type":"array","items":{"type":"string","enum":["shipment.created","shipment.status_updated","shipment.delivered","shipment.exception"]},"description":"الأحداث المطلوبة (الافتراضي: الكل) | Subscribed events (default: all)"}}},"example":{"url":"https://example.sa/manfath/hook","events":["shipment.status_updated","shipment.exception"]}}}},"responses":{"200":{"description":"تم حفظ الإعداد | Configuration saved","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"سرّ Webhook الخاص بفريقك | Your team's webhook secret"}}},"example":{"url":"https://example.sa/manfath/hook","events":["shipment.status_updated","shipment.exception"],"secret":"whsec_9f2c4a7d1e8b3f6c5a0d9e2b4c7f1a3d"}}}},"401":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"422":{"description":"عنوان غير صالح | Invalid URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_VALIDATION","message_en":"Request validation failed.","message_ar":"فشل التحقق من صحة الطلب."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/invoices/current":{"get":{"operationId":"getCurrentInvoice","tags":["Invoices"],"summary":"الفاتورة الحالية | Current invoice","description":"يعيد فاتورة فترة الفوترة الحالية لفريقك بجميع بنودها، شاملة ضريبة القيمة المضافة 15%.\n\nReturns your team's current billing period invoice with all line items, including 15% VAT.","responses":{"200":{"description":"الفاتورة | The invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/data-readiness":{"post":{"operationId":"assessDataReadiness","tags":["Data Readiness"],"summary":"تقييم جاهزية البيانات | Data readiness assessment","description":"يفحص كتالوج منتجات فريقك ويقيّم اكتمال البيانات اللازمة للشحن الدولي: رموز النظام المنسق، الأوزان، الأبعاد، وبلد المنشأ، ثم يعيد درجة من 100 مع قائمة مفصلة بالمشكلات.\n\nAnalyses your team's product catalogue and scores the completeness of the data required for international shipping — HS codes, weights, dimensions and country of origin — returning a score out of 100 with a detailed issue list.","responses":{"200":{"description":"تقرير الجاهزية | Readiness report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataReadinessReport"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/makhzoon/batches":{"post":{"operationId":"uploadMakhzoonBatch","tags":["Makhzoon"],"summary":"رفع دفعة طلبات مخزون بلس | Upload a Makhzoon Plus order batch","description":"ارفع ملف CSV بطلبات التنفيذ المحلي. يجب أن يطابق صف العناوين تمامًا بالترتيب والأسماء:\n`order_ref,recipient_name_ar,recipient_name_latin,phone,city,district,short_address,sku,qty,cod_amount_sar,notes`\nأي خطأ في أي صف يؤدي إلى رفض الملف كاملًا. تتم المعالجة بشكل غير متزامن — استعلم عن النتيجة عبر `GET /makhzoon/batches/{id}`.\n\nUpload a CSV of domestic fulfilment orders. The header row must match exactly, in order and by name:\n`order_ref,recipient_name_ar,recipient_name_latin,phone,city,district,short_address,sku,qty,cod_amount_sar,notes`\nAny error in any row rejects the whole file. Processing is asynchronous — poll `GET /makhzoon/batches/{id}` for the result.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"ملف CSV بترميز UTF-8 | UTF-8 encoded CSV file"}}}}}},"responses":{"202":{"description":"الدفعة قيد المعالجة | Batch accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakhzoonBatch"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"422":{"description":"ملف مفقود أو غير صالح | Missing or invalid file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_VALIDATION","message_en":"Request validation failed.","message_ar":"فشل التحقق من صحة الطلب."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/makhzoon/batches/{id}":{"get":{"operationId":"getMakhzoonBatch","tags":["Makhzoon"],"summary":"حالة دفعة مخزون بلس | Makhzoon batch status","description":"يعيد حالة الدفعة ونتيجتها: عند الاكتمال يتضمن `result_csv` عمودي `tracking_number` و`status`، وعند الرفض يتضمن `rejection_csv` أسباب رفض كل صف.\n\nReturns the batch status and result: on completion `result_csv` includes `tracking_number` and `status` columns; on rejection `rejection_csv` lists the reason for every failed row.","parameters":[{"name":"id","in":"path","required":true,"description":"معرّف الدفعة | The batch id","schema":{"type":"string"},"example":"cmdgh7w2b000bx8p9t5kq2n8j"}],"responses":{"200":{"description":"الدفعة | The batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakhzoonBatch"},"example":{"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":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"الدفعة غير موجودة | Batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}},"/carriers/{code}/passthrough":{"post":{"operationId":"carrierPassthrough","tags":["Passthrough"],"summary":"التمرير المباشر إلى الناقل | Direct carrier passthrough","description":"يمرر جسم الطلب كما هو إلى واجهة الناقل الأصلية ويعيد استجابة الناقل كما هي. راجع وثائق الناقل لمعرفة الصيغة المطلوبة.\n\nForwards the request body unchanged to the carrier's native API and returns the carrier's response as-is. See the carrier's documentation for the expected format.","parameters":[{"name":"code","in":"path","required":true,"description":"رمز الناقل | Carrier code","schema":{"type":"string","enum":["SARIE","BARR"]},"example":"SARIE"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"carrier-native payload — see carrier documentation"}}}},"responses":{"200":{"description":"استجابة الناقل | The carrier's response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"carrier-native response — see carrier documentation"}}}},"401":{"description":"مفتاح API مفقود أو غير صالح | Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_UNAUTHENTICATED","message_en":"Missing or invalid API key. Send Authorization: Bearer mnf_live_...","message_ar":"مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_..."}}}}},"404":{"description":"ناقل غير معروف | Unknown carrier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_NOT_FOUND","message_en":"Resource not found.","message_ar":"المورد غير موجود."}}}}},"429":{"description":"تم تجاوز حد الطلبات (60 في الدقيقة) | Rate limit exceeded (60 per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"E_RATE_LIMITED","message_en":"Rate limit exceeded: 60 requests per minute per API key.","message_ar":"تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح."}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"أرسل مفتاح API الخاص بفريقك: `Authorization: Bearer mnf_live_...` | Send your team's API key: `Authorization: Bearer mnf_live_...`"}},"schemas":{"ErrorEnvelope":{"type":"object","description":"غلاف الأخطاء الموحد | The unified error envelope.\n\n| Code | HTTP | English | العربية |\n|---|---|---|---|\n| `E_UNAUTHENTICATED` | 401 | Missing or invalid API key. Send Authorization: Bearer mnf_live_... | مفتاح API مفقود أو غير صالح. أرسل Authorization: Bearer mnf_live_... |\n| `E_VALIDATION` | 422 | Request validation failed. | فشل التحقق من صحة الطلب. |\n| `E_RATE_LIMITED` | 429 | Rate limit exceeded: 60 requests per minute per API key. | تم تجاوز حد الطلبات: 60 طلبًا في الدقيقة لكل مفتاح. |\n| `E_QUOTE_EXPIRED` | 409 | This quote has expired. Quotes are valid for 15 minutes. Request a new rate. | انتهت صلاحية هذه التسعيرة. التسعيرات صالحة لمدة 15 دقيقة. اطلب تسعيرة جديدة. |\n| `E_ADDRESS_NOT_NORMALISED` | 422 | Destination address is not normalised to the Saudi National Address standard. | عنوان الوجهة غير مطابق لمعيار العنوان الوطني السعودي. |\n| `E_CANCEL_NOT_ALLOWED` | 409 | Shipment can no longer be cancelled after pickup. | لا يمكن إلغاء الشحنة بعد الاستلام من المرسل. |\n| `E_NOT_FOUND` | 404 | Resource not found. | المورد غير موجود. |","required":["error"],"properties":{"error":{"type":"object","required":["code","message_en","message_ar"],"properties":{"code":{"type":"string","description":"رمز الخطأ الآلي | Machine-readable error code"},"message_en":{"type":"string"},"message_ar":{"type":"string"},"details":{"description":"تفاصيل إضافية إن وجدت | Additional details when available"}}}}},"Address":{"type":"object","description":"عنوان. للوجهات داخل المملكة يلزم عند إنشاء الشحنة عنوان وطني مطابق: عنوان مختصر، أو رمز بريدي مع رقم إضافي.\n\nAn address. Saudi destinations must be normalised at shipment creation: a short address, or a postal code plus additional number.","required":["country","city"],"properties":{"name":{"type":"string","description":"اسم جهة الاتصال أو المنشأة | Contact or company name"},"line1":{"type":"string","description":"سطر العنوان | Address line"},"city":{"type":"string","examples":["Riyadh"]},"region":{"type":"string","description":"المنطقة | Region"},"country":{"type":"string","description":"رمز الدولة ISO 3166-1 alpha-2 | ISO 3166-1 alpha-2 country code","examples":["SA"]},"postal_code":{"type":"string","description":"الرمز البريدي (5 أرقام داخل المملكة) | Postal code (5 digits inside Saudi Arabia)"},"additional_number":{"type":"string","description":"الرقم الإضافي للعنوان الوطني (4 أرقام) | National Address additional number (4 digits)"},"short_address":{"type":"string","description":"العنوان الوطني المختصر، مثل RRDA2929 | National short address, e.g. RRDA2929","examples":["RRDA2929"]},"phone":{"type":"string","description":"رقم الجوال بصيغة 9665XXXXXXXX | Mobile number in 9665XXXXXXXX format"}}},"Parcel":{"type":"object","description":"طرد واحد؛ الوزن بالكيلوغرام والأبعاد بالسنتيمتر | A single parcel; weight in kilograms, dimensions in centimetres.","required":["weight_kg","length_cm","width_cm","height_cm"],"properties":{"weight_kg":{"type":"number","description":"الوزن بالكيلوغرام | Weight in kilograms","examples":[2.5]},"length_cm":{"type":"number","description":"الطول بالسنتيمتر | Length in centimetres","examples":[30]},"width_cm":{"type":"number","description":"العرض بالسنتيمتر | Width in centimetres","examples":[20]},"height_cm":{"type":"number","description":"الارتفاع بالسنتيمتر | Height in centimetres","examples":[15]}}},"CarrierRef":{"type":"object","description":"مرجع الناقل | Carrier reference","properties":{"code":{"type":"string","examples":["SARIE"]},"name_ar":{"type":"string"},"name_en":{"type":"string"}}},"ServiceRef":{"type":"object","description":"مرجع مستوى الخدمة | Service level reference","properties":{"code":{"type":"string","examples":["EXP_DOM"]},"name_ar":{"type":"string"},"name_en":{"type":"string"},"mode":{"type":"string","enum":["air","sea","land","express"],"description":"وسيلة النقل | Transport mode"}}},"Carrier":{"type":"object","description":"ناقل بمستويات خدمته | A carrier and its service levels","properties":{"code":{"type":"string"},"name_ar":{"type":"string"},"name_en":{"type":"string"},"integration_type":{"type":"string","enum":["rest","rest_legacy","csv_batch"]},"coverage_countries":{"type":"array","items":{"type":"string"},"description":"دول التغطية (ISO alpha-2) | Coverage countries (ISO alpha-2)"},"service_levels":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name_ar":{"type":"string"},"name_en":{"type":"string"},"mode":{"type":"string","enum":["air","sea","land","express"]},"transit_days":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}}}}},"BreakdownItem":{"type":"object","description":"بند من بنود تفصيل السعر | A price breakdown line","properties":{"code":{"type":"string","description":"رمز البند، مثل base أو weight_charge أو fuel_surcharge أو vat | Line code, e.g. base, weight_charge, fuel_surcharge, vat"},"label_en":{"type":"string"},"label_ar":{"type":"string"},"amount_sar":{"type":"number"}}},"Quote":{"type":"object","description":"تسعيرة شحن صالحة لمدة 15 دقيقة | A shipping quote, valid for 15 minutes","properties":{"quote_id":{"type":"string"},"carrier":{"$ref":"#/components/schemas/CarrierRef"},"service":{"$ref":"#/components/schemas/ServiceRef"},"transit_days":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"weights":{"type":"object","description":"الأوزان: الفعلي والحجمي والقابل للفوترة | Actual, volumetric and chargeable weights","properties":{"actual_kg":{"type":"number"},"volumetric_kg":{"type":"number"},"chargeable_kg":{"type":"number","description":"الأعلى بين الفعلي والحجمي، مقربًا لأعلى إلى 0.5 كغ | Greater of actual and volumetric, rounded up to 0.5 kg"},"volumetric_divisor":{"type":"integer"},"weight_break_applied":{"type":"string"}}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownItem"}},"total_sar":{"type":"number"},"currency":{"type":"string","const":"SAR"},"expires_at":{"type":"string","format":"date-time","description":"انتهاء صلاحية التسعيرة (15 دقيقة من الإصدار) | Quote expiry (15 minutes from issue)"}}},"Warning":{"type":"object","description":"تنبيه غير مانع | A non-blocking advisory warning","properties":{"code":{"type":"string"},"message_en":{"type":"string"},"message_ar":{"type":"string"}}},"Shipment":{"type":"object","description":"شحنة | A shipment","properties":{"id":{"type":"string"},"tracking_number":{"type":"string","examples":["SRE0248817359"]},"manfath_reference":{"type":"string","examples":["MNF-2026-K7Q2ZC"]},"status":{"type":"string","enum":["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_ar":{"type":"string"},"status_en":{"type":"string"},"carrier":{"$ref":"#/components/schemas/CarrierRef"},"service":{"$ref":"#/components/schemas/ServiceRef"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"parcels":{"type":"array","items":{"$ref":"#/components/schemas/Parcel"}},"declared_value_sar":{"type":"number"},"incoterm":{"type":"string"},"hs_codes":{"type":"array","items":{"type":"string"}},"cod_amount_sar":{"type":"number"},"label_url":{"type":"string","description":"مسار بوليصة الشحن PDF | Path to the PDF label"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"},"description":"تنبيهات غير مانعة إن وجدت | Non-blocking advisory warnings, if any"},"quoted_total_sar":{"type":"number"},"estimated_delivery_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"TrackingEvent":{"type":"object","description":"حدث تتبع | A tracking event","properties":{"code":{"type":"string","description":"رمز الحالة | Status code"},"status_ar":{"type":"string"},"status_en":{"type":"string"},"location_ar":{"type":"string"},"location_en":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"is_exception":{"type":"boolean"},"exception_type":{"type":"string","enum":["CUSTOMS_HOLD","ADDRESS_ISSUE","WEIGHT_MISMATCH","FAILED_DELIVERY_ATTEMPT","CARRIER_DELAY"],"description":"نوع الاستثناء عندما يكون الحدث استثناءً | Exception type when the event is an exception"}}},"InvoiceLineItem":{"type":"object","description":"بند فاتورة | An invoice line item","properties":{"shipment_id":{"type":"string"},"tracking_number":{"type":"string"},"description":{"type":"string"},"description_ar":{"type":"string"},"amount_sar":{"type":"number"},"cause":{"type":"string","description":"سبب البند | Line cause"}}},"Invoice":{"type":"object","description":"فاتورة فترة الفوترة | A billing period invoice","properties":{"id":{"type":"string"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItem"}},"subtotal_sar":{"type":"number"},"surcharges_sar":{"type":"number"},"vat_sar":{"type":"number","description":"ضريبة القيمة المضافة 15% | 15% VAT"},"total_sar":{"type":"number"},"updated_at":{"type":"string","format":"date-time"}}},"DataReadinessReport":{"type":"object","description":"تقرير جاهزية بيانات الكتالوج | Catalogue data readiness report","properties":{"score":{"type":"integer","minimum":0,"maximum":100,"description":"الدرجة من 100 | Score out of 100"},"total_skus":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"field":{"type":"string"},"severity":{"type":"string","enum":["error","warn"]},"message_ar":{"type":"string"},"message_en":{"type":"string"}}}},"summary":{"type":"object","properties":{"missing_hs_code":{"type":"integer"},"missing_weight":{"type":"integer"},"missing_dimensions":{"type":"integer"},"missing_origin_country":{"type":"integer"},"suspicious_values":{"type":"integer"}}}}},"MakhzoonBatch":{"type":"object","description":"دفعة طلبات مخزون بلس | A Makhzoon Plus order batch","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","COMPLETED","REJECTED"]},"filename":{"type":"string"},"row_count":{"type":"integer"},"accepted_count":{"type":"integer"},"rejected_count":{"type":"integer"},"result_csv":{"type":["string","null"],"description":"CSV النتائج عند الاكتمال، بعمودي tracking_number وstatus إضافة إلى أعمدة الملف الأصلي | Result CSV on completion, with tracking_number and status columns appended to the original columns"},"rejection_csv":{"type":["string","null"],"description":"CSV أسباب الرفض عند رفض الملف: row_number,field,reason_ar,reason_en | Rejection CSV when the file is rejected: row_number,field,reason_ar,reason_en"},"created_at":{"type":"string","format":"date-time"}}}}}}