{
  "info": {
    "_postman_id": "7f3d0a4e-9c21-4d5b-8e17-2b6a5c9d4f10",
    "name": "منفذ Manfath API",
    "description": "مجموعة Postman الرسمية لواجهة منفذ. عيّن متغير api_key بمفتاح فريقك، ومتغير baseUrl عند الحاجة.\n\nThe official Manfath API Postman collection. Set the api_key variable to your team key, and adjust baseUrl if needed.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://localhost:8080/api/v1",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "mnf_live_YOUR_KEY_HERE",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Carriers",
      "description": "الناقلون وخدماتهم | Carriers and their services",
      "item": [
        {
          "name": "قائمة الناقلين | List carriers",
          "request": {
            "method": "GET",
            "description": "يعيد جميع الناقلين المتاحين في منفذ مع مستويات الخدمة ونطاق التغطية لكل ناقل.\n\nReturns all carriers available on Manfath with each carrier's service levels and coverage countries.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/carriers",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "carriers"
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Rates",
      "description": "التسعير وعروض الأسعار | Rating and quotes",
      "item": [
        {
          "name": "طلب تسعيرات الشحن | Request shipping rates",
          "request": {
            "method": "POST",
            "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.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/rates",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "rates"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"origin\": {\n    \"country\": \"SA\",\n    \"city\": \"Riyadh\",\n    \"short_address\": \"RRDA2929\"\n  },\n  \"destination\": {\n    \"country\": \"AE\",\n    \"city\": \"Dubai\",\n    \"line1\": \"Al Wasl Road 214\"\n  },\n  \"parcels\": [\n    {\n      \"weight_kg\": 2.5,\n      \"length_cm\": 30,\n      \"width_cm\": 20,\n      \"height_cm\": 15\n    }\n  ],\n  \"declared_value\": 450,\n  \"declared_value_currency\": \"SAR\",\n  \"incoterm\": \"DAP\",\n  \"hs_codes\": [\n    \"330499\"\n  ],\n  \"cod_amount\": 0\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Shipments",
      "description": "الشحنات والتتبع | Shipments and tracking",
      "item": [
        {
          "name": "قائمة الشحنات | List shipments",
          "request": {
            "method": "GET",
            "description": "يعيد شحنات فريقك مرتبة من الأحدث إلى الأقدم، مع إمكانية الترشيح حسب الحالة.\n\nReturns your team's shipments, newest first, optionally filtered by status.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/shipments",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments"
              ],
              "query": [
                {
                  "key": "status",
                  "value": "IN_TRANSIT",
                  "description": "ترشيح حسب الحالة | Filter by status",
                  "disabled": true
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "عدد النتائج (الافتراضي 20، الأقصى 100) | Page size (default 20, max 100)",
                  "disabled": true
                },
                {
                  "key": "offset",
                  "value": "0",
                  "description": "الإزاحة (الافتراضي 0) | Offset (default 0)",
                  "disabled": true
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "إنشاء شحنة | Create a shipment",
          "request": {
            "method": "POST",
            "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.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/shipments",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"quote_id\": \"cmdg7f3k2a0001x8p9zr41mstq\",\n  \"origin\": {\n    \"name\": \"مستودع الرياض\",\n    \"line1\": \"طريق الملك فهد\",\n    \"country\": \"SA\",\n    \"city\": \"Riyadh\",\n    \"short_address\": \"RRDA2929\",\n    \"phone\": \"966512345678\"\n  },\n  \"destination\": {\n    \"name\": \"عبدالله القحطاني\",\n    \"line1\": \"حي الروضة\",\n    \"country\": \"SA\",\n    \"city\": \"Jeddah\",\n    \"short_address\": \"JHFB8823\",\n    \"phone\": \"966555112233\"\n  },\n  \"parcels\": [\n    {\n      \"weight_kg\": 2.5,\n      \"length_cm\": 30,\n      \"width_cm\": 20,\n      \"height_cm\": 15\n    }\n  ],\n  \"declared_value\": 450,\n  \"incoterm\": \"DAP\",\n  \"hs_codes\": [\n    \"330499\"\n  ],\n  \"cod_amount\": 0,\n  \"reference\": \"PO-10422\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        },
        {
          "name": "تفاصيل شحنة | Get a shipment",
          "request": {
            "method": "GET",
            "description": "يعيد تفاصيل الشحنة كاملة بحالتها الراهنة.\n\nReturns the full shipment with its current status.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/shipments/:id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "أحداث تتبع الشحنة | Shipment tracking events",
          "request": {
            "method": "GET",
            "description": "يعيد أحداث التتبع للشحنة مرتبة من الأحدث إلى الأقدم.\n\nReturns the shipment's tracking events, most recent first.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/shipments/:id/tracking",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments",
                ":id",
                "tracking"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "إلغاء شحنة | Cancel a shipment",
          "request": {
            "method": "POST",
            "description": "يلغي الشحنة. الإلغاء ممكن قبل استلام الشحنة من المرسل فقط.\n\nCancels the shipment. Cancellation is only possible before the shipment is picked up.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/shipments/:id/cancel",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments",
                ":id",
                "cancel"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"طلب العميل إلغاء الشراء\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        },
        {
          "name": "رفع مستندات الشحنة | Upload shipment documents",
          "request": {
            "method": "POST",
            "description": "ارفع المستندات الجمركية للشحنة: فاتورة تجارية، قائمة تعبئة، أو شهادة منشأ.\n\nUpload customs documents for the shipment: commercial invoice, packing list, or certificate of origin.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/shipments/:id/documents",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments",
                ":id",
                "documents"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            },
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": []
                },
                {
                  "key": "type",
                  "type": "text",
                  "value": "",
                  "description": "نوع المستند | Document type"
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "تحديث عنوان الوجهة | Update destination address",
          "request": {
            "method": "PATCH",
            "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.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/shipments/:id/destination",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "shipments",
                ":id",
                "destination"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"عبدالله القحطاني\",\n  \"line1\": \"حي السلامة\",\n  \"country\": \"SA\",\n  \"city\": \"Jeddah\",\n  \"postal_code\": \"23525\",\n  \"additional_number\": \"7712\",\n  \"phone\": \"966555112233\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Labels",
      "description": "بوليصات الشحن | Shipping labels",
      "item": [
        {
          "name": "بوليصة الشحن (PDF) | Shipping label (PDF)",
          "request": {
            "method": "GET",
            "description": "يعيد بوليصة الشحن بصيغة PDF بمقاس A6، متضمنة الرمز الشريطي ورمز الاستجابة السريعة للتتبع.\n\nReturns the A6 shipping label as a PDF, including the barcode and the tracking QR code.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/labels/:id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "labels",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdg8s1t20003x8p9aqk2v7hu",
                  "description": "معرّف الشحنة في منفذ | The Manfath shipment id"
                }
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Webhooks",
      "description": "الإشعارات الفورية | Real-time notifications",
      "item": [
        {
          "name": "إعداد Webhooks | Configure webhooks",
          "request": {
            "method": "POST",
            "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.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/webhooks/config",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "webhooks",
                "config"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.sa/manfath/hook\",\n  \"events\": [\n    \"shipment.status_updated\",\n    \"shipment.exception\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Invoices",
      "description": "الفواتير | Billing",
      "item": [
        {
          "name": "الفاتورة الحالية | Current invoice",
          "request": {
            "method": "GET",
            "description": "يعيد فاتورة فترة الفوترة الحالية لفريقك بجميع بنودها، شاملة ضريبة القيمة المضافة 15%.\n\nReturns your team's current billing period invoice with all line items, including 15% VAT.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/invoices/current",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "invoices",
                "current"
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Data Readiness",
      "description": "جاهزية بيانات الكتالوج | Catalogue data readiness",
      "item": [
        {
          "name": "تقييم جاهزية البيانات | Data readiness assessment",
          "request": {
            "method": "POST",
            "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.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/data-readiness",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "data-readiness"
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Makhzoon",
      "description": "دفعات مخزون بلس | Makhzoon Plus fulfilment batches",
      "item": [
        {
          "name": "رفع دفعة طلبات مخزون بلس | Upload a Makhzoon Plus order batch",
          "request": {
            "method": "POST",
            "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.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/makhzoon/batches",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "makhzoon",
                "batches"
              ]
            },
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": []
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "حالة دفعة مخزون بلس | Makhzoon batch status",
          "request": {
            "method": "GET",
            "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.",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/makhzoon/batches/:id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "makhzoon",
                "batches",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "cmdgh7w2b000bx8p9t5kq2n8j",
                  "description": "معرّف الدفعة | The batch id"
                }
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Passthrough",
      "description": "التمرير المباشر إلى الناقل | Carrier-native passthrough",
      "item": [
        {
          "name": "التمرير المباشر إلى الناقل | Direct carrier passthrough",
          "request": {
            "method": "POST",
            "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.",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/carriers/:code/passthrough",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "carriers",
                ":code",
                "passthrough"
              ],
              "variable": [
                {
                  "key": "code",
                  "value": "SARIE",
                  "description": "رمز الناقل | Carrier code"
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        }
      ]
    }
  ]
}