{ "info": { "name": "RAWAFED Partner API v1.0.0", "description": "واجهة شركاء RAWAFED (Partner API).\n\n**المصادقة:** كل المسارات تتطلب مفتاح API بالترويسة `X-API-Key` بصيغة\n`{prefix}.{secret}` — المفتاح يُنشأ من بوابة التاجر ويُعرض مرة واحدة فقط.\n\n**الصلاحيات (Scopes) — مفروضة فعلياً:** كل مفتاح يحمل مجموعة صلاحيات تُختار\nعند إنشائه. الطلب لمسار خارج صلاحيات المفتاح يُرفض بـ `403` مع رسالة تُسمّي\nالصلاحية الناقصة. الصلاحيات المتاحة:\n\n| Scope | يسمح بـ |\n|---|---|\n| `addresses:read` | حلّ رمز توصيل، البحث المحجوب بالموبايل |\n| `addresses:write` | إنشاء عنوان، إرسال طلب مشاركة |\n| `rates:read` | التسعير قبل الإنشاء |\n| `shipments:read` | قراءة/تتبع الشحنات وملصقاتها |\n| `shipments:write` | إنشاء الشحنات وإلغاؤها |\n| `express:read` | تسعير التوصيل، قراءة الطلبات السريعة ومتاجرك |\n| `express:write` | إنشاء الطلب السريع وإلغاؤه و«جاهز»، وإدارة متاجرك |\n| `cod:read` | قراءة دورات تسوية COD |\n| `webhooks:manage` | تسجيل وإدارة الـ webhooks |\n\n**التوصيل السريع (أكل وماركت):** سجّل متاجرك مرة (`POST /partner/v1/express/stores`)، ثم أرسل\nكل طلب (`POST /partner/v1/express`) بالمتجر والزبون والدبوس والأصناف وطريقة الدفع. يُعرض فوراً على\nالكباتن، وكل خطوة بعدها — قبول الكابتن، وصوله للمتجر، الاستلام، وصوله للباب، التسليم أو الفشل أو\nالإلغاء — تصلك webhook باسم `express.status_changed` يحمل الطلب كاملاً بشكل `ExpressOrder`\nنفسه (الحالة، الكابتن، والخطوات بأوقاتها). **اعرض `delivery_code` لزبونك**: الكابتن لا يسلّم بدونه.\nللتتبع: `GET /partner/v1/express/{code}/tracking` (الموقع الحي والوقت المتوقع)، أو أرسل لزبونك\n`tracking_url` — صفحة جاهزة باسم شركتك.\n\n**رمز التسليم منك:** أرسل `delivery_code` (4–6 أرقام) مع الطلب السريع أو طلب المتجر، فنفحصه نحن عند الباب ولا\nنتصل بك في اللحظة. يصلك `delivery.code_failed` عند كل رمز خطأ (`attempts_left`)، و`delivery.code_locked` عند الحد.\nواستبدل الرمز ليُفتح الباب. وكل تسليم يقول `verification`: `code` أو `override` أو `none`.\n\n**الخريطة الحية:** اشترك **بالاسم** في `express.location_updated` (لا يصل لمن اشترك بـ`*`). يصلك موقع\nالكابتن من الإسناد حتى الباب، مرة كل 10 ثوانٍ على الأكثر لكل طلب، بشكل `ExpressLocationUpdated`. الكابتن\nالذي يحمل طلباً يرسل موقعه فور أخذه، فما يصلك عمره ثوانٍ.\n\n**Idempotency:** مسارات الكتابة في الشحنات والطلب السريع تقبل ترويسة\n`Idempotency-Key`. تكرار نفس المفتاح بنفس الجسم يُعيد الاستجابة المحفوظة\nبدل إنشاء سجل ثانٍ (مع ترويسة `Idempotent-Replay: true`)، وتكراره بجسم\nمختلف يُرفض بـ `422`. استخدمه دائماً عند إعادة المحاولة بعد انقطاع الشبكة.\n\n**حدود المعدل:** 60 طلب/دقيقة لكل مفتاح على عموم الواجهة (120 على مسارات السريع)، و10 طلبات/دقيقة\nعلى مسارات البحث بالموبايل ومشاركة العنوان.\n\n**الخصوصية:** `/partner/v1/addresses/lookup-phone` يُرجع بيانات محجوبة فقط\n(`exists` / `has_verified_address`) ولا يكشف إحداثيات ولا معلماً ولا رمز\nالتوصيل. كشف العنوان يتم فقط بحيازة رمز التوصيل نفسه.\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "baseUrl", "value": "https://mail.rawafedsystems.com", "type": "string" }, { "key": "apiKey", "value": "", "type": "string" } ], "item": [ { "name": "Addresses", "item": [ { "name": "قائمة عناوين الشريك", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/addresses", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "addresses" ] }, "description": null } }, { "name": "إنشاء عنوان", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/addresses", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "addresses" ] }, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "description": null } }, { "name": "حلّ رمز توصيل إلى عنوان كامل", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/addresses/{code}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "addresses", "{code}" ] }, "description": "حيازة رمز التوصيل هي الإذن نفسه — لا يوجد بحث عام بالعناوين، والرمز\nيُشارك من صاحب العنوان فقط. يُرجع نقاط استلام بديلة تلقائياً إن كان\nالعنوان ضعيف الثقة. Scope مطلوب `addresses:read`.\n" } }, { "name": "بحث عنوان برقم الهاتف (مقنّع فقط)", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/addresses/lookup-phone", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "addresses", "lookup-phone" ], "query": [ { "key": "phone", "value": "", "description": "رقم الهاتف للبحث", "disabled": false } ] }, "description": "يُرجع نتائج مقنّعة فقط. لا يُكشف رقم الهاتف الكامل ولا تفاصيل\nالعنوان الدقيقة. الحقل `is_masked` يكون دائماً `true`.\n" } }, { "name": "طلب مشاركة عنوان عبر الموبايل", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/addresses/request-share", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "addresses", "request-share" ] }, "body": { "mode": "raw", "raw": "{\n \"phone\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "يرسل للزبون رسالة تطلب مشاركة رمز عنوانه. **لا يُرجع العنوان إطلاقاً** —\nالرمز يصل للزبون وحده وهو يقرر مشاركته. Scope مطلوب `addresses:write`.\nمحدود بـ 10 طلبات/دقيقة.\n" } } ] }, { "name": "Express", "item": [ { "name": "تسعير التوصيل قبل الطلب", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/quote", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "quote" ] }, "body": { "mode": "raw", "raw": "{\n \"store_ref\": \"\",\n \"pickup\": \"\",\n \"dropoff\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "المسافة ورسم التوصيل والوقت المتوقع (تجهيز + طريق) قبل أن يُطلب. المتجر بمعرّفه عندك (store_ref) أو نقطة استلام. يحتاج نطاق express:read." } }, { "name": "إنشاء طلب توصيل (أكل أو ماركت)", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express" ] }, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "description": "الطلب الكامل من تطبيقك: المتجر، الزبون، موقع التسليم (دبوس أو رمز توصيل)، الأصناف، وطريقة الدفع. يُعرض فوراً على الكباتن. نفس external_ref مرتين يعيد الطلب الأول بـ200 ولا يُنشئ طلباً ثانياً. المبلغ الذي يقبضه الكابتن عند الباب (cod_amount) = قيمة الطلب + رسم التوصيل إن كان الدفع cash، وصفر إن كان prepaid. رسم التوصيل يُحسب بقواعد الشركة إن لم ترسله. يحتاج express:write وIdempotency-Key." } }, { "name": "قائمة طلباتك", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express" ], "query": [ { "key": "status", "value": "", "description": null, "disabled": true }, { "key": "store_ref", "value": "", "description": null, "disabled": true }, { "key": "from", "value": "", "description": null, "disabled": true }, { "key": "to", "value": "", "description": null, "disabled": true }, { "key": "per_page", "value": "", "description": null, "disabled": true }, { "key": "page", "value": "", "description": null, "disabled": true } ] }, "description": null } }, { "name": "متاجرك (مطاعم وماركات)", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/stores", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "stores" ] }, "description": null } }, { "name": "إضافة متجر أو تحديثه بمعرّفه عندك", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/stores", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "stores" ] }, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "description": "payment_mode يحدد نقد الكابتن — captain_pays: الكابتن يدفع للمتجر قيمة الطلب عند الاستلام؛ company_settles: الشركة تسوّي مع المتجر لاحقاً ولا يدفع الكابتن شيئاً." } }, { "name": "طلب واحد بحالته وخطواته وكابتنه", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/{code}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "{code}" ] }, "description": null } }, { "name": "أين الطلب ومن يحمله ومتى يصل", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/{code}/tracking", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "{code}", "tracking" ] }, "description": "لشاشة التتبع في تطبيقك. **للخريطة الحية اشترك في webhook ‏`express.location_updated`** بدل السؤال المتكرر؛ وهذا المسار لفتح الشاشة ولملء ما فات. موقع الكابتن من لحظة الإسناد حتى الباب، وفقط إن كان حديثاً، وكما أبلغ به الكابتن. يحتاج express:read." } }, { "name": "إلغاء الطلب", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/{code}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "{code}", "cancel" ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "يُقبل حتى يخرج الطلب من المتجر. بعد الاستلام يُرفض بـ422 والسبب." } }, { "name": "استبدال رمز التسليم", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/{code}/delivery-code", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "{code}", "delivery-code" ] }, "body": { "mode": "raw", "raw": "{\n \"delivery_code\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "رمز جديد للزبون، لأنه طلب إعادته أو لأن الرمز قُفل بمحاولات خاطئة. تبدأ المحاولات من الصفر، فيُفتح الباب المقفول.\nScope مطلوب `express:write`.\n" } }, { "name": "المتجر جهّز الطلب", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/express/{code}/ready", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "express", "{code}", "ready" ] }, "description": "يضبط وقت الجهوزية الآن — أبكر أو أبعد مما قُدّر عند الطلب." } } ] }, { "name": "Rates", "item": [ { "name": "تسعير شحنة / توصيل", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/rates/quote", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "rates", "quote" ] }, "body": { "mode": "raw", "raw": "{\n \"from_zone_id\": \"\",\n \"to_zone_id\": \"\",\n \"weight_kg\": 0,\n \"service\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": null } } ] }, { "name": "Shipments", "item": [ { "name": "قائمة الشحنات", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/shipments", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "shipments" ], "query": [ { "key": "status", "value": "", "description": null, "disabled": true }, { "key": "reference", "value": "", "description": "مرجعك أو بدايته — `ORD-1001` يجد طرود الطلب كلها (`ORD-1001/P1`، `ORD-1001/P2`).", "disabled": true }, { "key": "page", "value": "", "description": null, "disabled": true } ] }, "description": null } }, { "name": "إنشاء شحنة", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/shipments", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "shipments" ] }, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "description": "يُرفض بـ `422` ورسالة تقول السبب إن كانت شركة الشحن موقوفة (لاشتراك غير مسدّد أو بقرار من المنصة).\nالشحنات القائمة لا تتأثر: تتبّعها وإلغاؤها وملصقاتها تعمل كالمعتاد.\n" } }, { "name": "تفاصيل شحنة", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/shipments/{tracking}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "shipments", "{tracking}" ] }, "description": null } }, { "name": "ملصق PDF لشحنة", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/shipments/{tracking}/label.pdf", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "shipments", "{tracking}", "label.pdf" ] }, "description": null } }, { "name": "ملصقات PDF دفعة واحدة", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/labels.pdf", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "labels.pdf" ] }, "description": null } }, { "name": "إلغاء شحنة", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/shipments/{tracking}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "shipments", "{tracking}", "cancel" ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "يُسمح بالإلغاء فقط ما دامت الشحنة لم تدخل شبكة التشغيل بعد\n(`created` / `awaiting_pickup` / `awaiting_dropoff`). بعد استلامها فعلياً\nيصبح الإلغاء قراراً تشغيلياً (إرجاع بضاعة فعلي) ويُرفض بـ `422`.\nScope مطلوب `shipments:write`.\n" } }, { "name": "أسابيع تسوية التحصيل", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/cod/settlements", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "cod", "settlements" ] }, "description": "الأسابيع المغلقة للتاجر، الأحدث أولاً: الإجمالي والرسوم والصافي والعملة وعدد البنود.\nتبقى مصفوفة كما كانت. Scope مطلوب `cod:read`.\n" } }, { "name": "أسبوع تسوية واحد", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/cod/settlements/{id}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "cod", "settlements", "{id}" ] }, "description": null } }, { "name": "بنود الأسبوع — سطر لكل طرد", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/cod/settlements/{id}/items", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "cod", "settlements", "{id}", "items" ], "query": [ { "key": "reference", "value": "", "description": "بادئة: `ORD-5001` تجد `ORD-5001/P1` و`/P2`", "disabled": true }, { "key": "per_page", "value": "", "description": null, "disabled": true }, { "key": "page", "value": "", "description": null, "disabled": true } ] }, "description": "لكل طرد قُبض نقده في الأسبوع: التحصيل، وما خُصم منه (رسم الشحن ورسم التحصيل)، والصافي.\nالأرقام كما كانت لحظة الإغلاق. حين تكون وحدة المتاجر مفعّلة يحمل السطر أيضاً `store_order`\nو`seller`. Scope مطلوب `cod:read`.\n" } } ] }, { "name": "Stores", "item": [ { "name": "حصة كل بائع من الأسبوع", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/cod/settlements/{id}/sellers", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "cod", "settlements", "{id}", "sellers" ], "query": [ { "key": "seller_ref", "value": "", "description": null, "disabled": true } ] }, "description": "لسوقٍ متعدد البائعين. يعطي لكل بائع عدد طروده ومجموع التحصيل والرسوم والصافي، ثم `unattributed`\nلطرود التاجر نفسه. مجموع الأسطر يساوي أرقام الأسبوع بالضبط. ومع `seller_ref` تأتي أسطر ذلك البائع\nفي `items`. Scope مطلوب `cod:read`.\n" } }, { "name": "استقبال طلب من متجر التاجر", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders" ] }, "body": { "mode": "raw", "raw": "{\n \"connection_id\": 0,\n \"external_id\": \"\",\n \"external_number\": \"\",\n \"status\": \"\",\n \"payment\": {},\n \"recipient\": {},\n \"delivery\": {},\n \"parcel\": {},\n \"metadata\": {},\n \"delivery_code\": \"\",\n \"seller_ref\": \"\",\n \"seller\": \"\",\n \"packages\": []\n}", "options": { "raw": { "language": "json" } } }, "description": "الباب الموحّد: أرسل الطلب فور موافقة التاجر عليه في متجره. العقد الكامل\nبالحقول والأمثلة في `docs/partner-api/store-order-intake.md`.\n\nيردّ `202` **قبل** المعالجة عمداً: المتجر لا ينتظرنا، والفشل يُسجَّل على\nالطلب لا في الاستجابة. لذلك `202` تعني «وصل وسُجِّل»، لا «صارت شحنة» —\nاقرأ `status` في الجسم، وهو أحد `received` / `ignored` / `needs_address`\n/ `shipped` / `failed`.\n\n`external_id` هو الهوية: إعادة إرسال نفس الطلب تحدّثه ولا تنشئ ثانياً،\nفالتكرار آمن بلا ترويسة إضافية. Scope مطلوب `shipments:write`.\n" } }, { "name": "الطلب وطروده برقمه عندك", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}" ] }, "description": "الحالة، وسبب التوقف إن توقف، ولكل طرد رقم التتبع وحالته ورابط صفحة الزبون والملصق. Scope `shipments:read`." } }, { "name": "ملصقات الطلب كله في ملف واحد", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}/labels.pdf", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}", "labels.pdf" ] }, "description": "للوحة البائع تطبعها وتلصقها على الطرود. Scope `shipments:read`." } }, { "name": "بائعوك (سوق متعدد البائعين)", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/sellers", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "sellers" ] }, "description": null } }, { "name": "تسجيل بائع أو تحديثه برقمه عندك", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/sellers", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "sellers" ] }, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "description": "باب الاستلام إحداثيات أو رمز توصيل — نصٌّ وحده لا يكفي ليجده الكابتن. نفس `ref` مرة ثانية يحدّث البائع. Scope `shipments:write`، وIdempotency-Key." } }, { "name": "استبدال رمز تسليم الطلب", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}/delivery-code", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}", "delivery-code" ] }, "body": { "mode": "raw", "raw": "{\n \"delivery_code\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "كل طرد من الطلب لم يُسلَّم بعد يأخذ الرمز الجديد، وتبدأ محاولاته من الصفر. Scope مطلوب `shipments:write`.\n" } }, { "name": "مرتجع بطلب الزبون", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}/returns", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}", "returns" ] }, "body": { "mode": "raw", "raw": "{\n \"ref\": \"\",\n \"package_ref\": \"\",\n \"reason\": \"\",\n \"items\": [],\n \"pieces\": 0,\n \"weight_kg\": 0\n}", "options": { "raw": { "language": "json" } } }, "description": "الزبون استلم طرداً ويريد إعادة شيء منه. يذهب كابتن إلى باب الزبون، ويتصل بالزبون نفسه، ثم يحمل\nالقطعة إلى باب البائع الذي أرسلها، أو إلى باب التاجر لطرد بلا بائع. **أعطوا الزبون `tracking_code`**،\nفهو يقرؤه للكابتن عند الباب، أو اطبعوا له `label_url`.\n\n- يُقبل فقط **بعد تسليم الطرد** (`delivered`)، ويبقى الطرد الأصلي `delivered`.\n- لا تحصيل على المرتجع: استرداد المبلغ للزبون بينكم وبينه. ورسوم المرتجع (الشحن والاستلام) تصل فاتورتكم.\n- `ref` رقم المرتجع عندكم: إعادة الإرسال بنفس الرقم تعيد المرتجع نفسه (`200`). ومرتجع واحد مفتوح لكل طرد.\n- كل تغيّر يصلكم في `store_order.updated` ضمن `packages[].returns`، ولا يُكتب في حالة طلبكم.\nScope مطلوب `shipments:write`.\n" } }, { "name": "إلغاء مرتجع", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}/returns/{ref}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}", "returns", "{ref}", "cancel" ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "ما دامت القطعة عند الزبون. بعد أن يستلمها الكابتن يُرفض بـ`422`. Scope مطلوب `shipments:write`." } }, { "name": "إلغاء طلب متجر", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/store-orders/{externalId}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "store-orders", "{externalId}", "cancel" ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "يُلغى ما دامت الشحنة لم تدخل شبكة التشغيل. بعد استلامها فعلياً يصبح\nالإلغاء إرجاع بضاعة ويُرفض بـ `422`. Scope مطلوب `shipments:write`.\n" } } ] }, { "name": "Webhooks", "item": [ { "name": "قائمة اشتراكات الويب هوك", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks" ] }, "description": null } }, { "name": "تسجيل نقطة ويب هوك", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Enable when retrying a create call to avoid duplicates" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks" ] }, "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [],\n \"secret\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "الرد يحمل `secret` الذي نولّده نحن — احفظه. كل إرسال جسمه:\n`{\"id\": \"evt_123\", \"event\": \"shipment.status_changed\", \"occurred_at\": \"…\", \"data\": {…}}`\nمع الترويسات:\n- `X-Tawseel-Signature`: HMAC-SHA256 بالـ`secret` للجسم الخام كما وصل (hex).\n- `X-Tawseel-Event-Id`: نفس `id` — ثابت في كل إعادة محاولة لهذا الحدث؛ تجاهل ما رأيته.\n- `X-Tawseel-Timestamp`: وقت الحدث (Unix) — داخل الجسم الموقّع أيضاً، فارفض القديم جداً.\n\nنعيد المحاولة حتى 3 مرات إن لم يصل رد 2xx.\n" } }, { "name": "تغيير العنوان أو الأحداث أو إيقافها مؤقتاً", "request": { "method": "PATCH", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks/{id}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks", "{id}" ] }, "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [],\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": null } }, { "name": "إيقاف النقطة (يبقى سجل ما أُرسل لها)", "request": { "method": "DELETE", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks/{id}", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks", "{id}" ] }, "description": null } }, { "name": "سرّ جديد فوراً", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks/{id}/rotate-secret", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks", "{id}", "rotate-secret" ] }, "description": "السرّ القديم يتوقف عن التحقق من الإرسال التالي. الرد هو المرة الوحيدة التي يُعرض فيها الجديد." } }, { "name": "إرسال حدث تجريبي (`webhook.test`) لهذه النقطة", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks/{id}/test", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks", "{id}", "test" ] }, "description": "للتأكد من العنوان والتوقيع قبل الأحداث الحقيقية. النتيجة في سجل الإرسال." } }, { "name": "سجل ما أُرسل لهذه النقطة وكيف أجابت", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhooks/{id}/deliveries", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhooks", "{id}", "deliveries" ], "query": [ { "key": "status", "value": "", "description": null, "disabled": true }, { "key": "event", "value": "", "description": null, "disabled": true } ] }, "description": null } }, { "name": "إعادة إرسال حدث (بنفس `event_id`)", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/webhook-deliveries/{id}/redeliver", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "webhook-deliveries", "{id}", "redeliver" ] }, "description": "بعد إصلاح جهتك. المستقبِل الذي وصله أول مرة يُسقط النسخة بالمعرّف." } } ] }, { "name": "Zones", "item": [ { "name": "قائمة المناطق", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/zones", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "zones" ], "query": [ { "key": "city", "value": "", "description": "تصفية حسب المدينة", "disabled": true } ] }, "description": null } }, { "name": "بحث بالمناطق والأسماء الشعبية", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/zones/search", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "zones", "search" ], "query": [ { "key": "q", "value": "", "description": null, "disabled": false } ] }, "description": "يبحث بالاسم الرسمي وبقاموس الأسماء المحكية (مثل «الشام» → دمشق). Scope مطلوب — لا شيء (متاح لأي مفتاح صالح)." } }, { "name": "بحث بالجغرافيا الرسمية السورية", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/gis/search", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "gis", "search" ], "query": [ { "key": "q", "value": "", "description": null, "disabled": false } ] }, "description": "بحث نصي بالمناطق الإدارية الرسمية (OCHA P-codes) والتجمعات السكانية." } }, { "name": "تحويل إحداثية لتسلسلها الإداري", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{apiKey}}" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/partner/v1/gis/resolve", "host": [ "{{baseUrl}}" ], "path": [ "partner", "v1", "gis", "resolve" ], "query": [ { "key": "lat", "value": "", "description": null, "disabled": false }, { "key": "lng", "value": "", "description": null, "disabled": false } ] }, "description": "يُرجع السلسلة الكاملة (محافظة ← منطقة ← ناحية ← حي) لإحداثية." } } ] } ] }