مرجع Partner API

كل المسارات تحت https://mail.rawafedsystems.com

واجهة شركاء RAWAFED (Partner API).

المصادقة: كل المسارات تتطلب مفتاح API بالترويسة X-API-Key بصيغة {prefix}.{secret} — المفتاح يُنشأ من بوابة التاجر ويُعرض مرة واحدة فقط.

الصلاحيات (Scopes) — مفروضة فعلياً: كل مفتاح يحمل مجموعة صلاحيات تُختار عند إنشائه. الطلب لمسار خارج صلاحيات المفتاح يُرفض بـ 403 مع رسالة تُسمّي الصلاحية الناقصة. الصلاحيات المتاحة:

Scope	يسمح بـ
`addresses:read`	حلّ رمز توصيل، البحث المحجوب بالموبايل
`addresses:write`	إنشاء عنوان، إرسال طلب مشاركة
`rates:read`	التسعير قبل الإنشاء
`shipments:read`	قراءة/تتبع الشحنات وملصقاتها
`shipments:write`	إنشاء الشحنات وإلغاؤها
`express:read`	تسعير التوصيل، قراءة الطلبات السريعة ومتاجرك
`express:write`	إنشاء الطلب السريع وإلغاؤه و«جاهز»، وإدارة متاجرك
`cod:read`	قراءة دورات تسوية COD
`webhooks:manage`	تسجيل وإدارة الـ webhooks

التوصيل السريع (أكل وماركت): سجّل متاجرك مرة (POST /partner/v1/express/stores)، ثم أرسل كل طلب (POST /partner/v1/express) بالمتجر والزبون والدبوس والأصناف وطريقة الدفع. يُعرض فوراً على الكباتن، وكل خطوة بعدها — قبول الكابتن، وصوله للمتجر، الاستلام، وصوله للباب، التسليم أو الفشل أو الإلغاء — تصلك webhook باسم express.status_changed يحمل الطلب كاملاً بشكل ExpressOrder نفسه (الحالة، الكابتن، والخطوات بأوقاتها). اعرض delivery_code لزبونك: الكابتن لا يسلّم بدونه. للتتبع: GET /partner/v1/express/{code}/tracking (الموقع الحي والوقت المتوقع)، أو أرسل لزبونك tracking_url — صفحة جاهزة باسم شركتك.

رمز التسليم منك: أرسل delivery_code (4–6 أرقام) مع الطلب السريع أو طلب المتجر، فنفحصه نحن عند الباب ولا نتصل بك في اللحظة. يصلك delivery.code_failed عند كل رمز خطأ (attempts_left)، وdelivery.code_locked عند الحد. واستبدل الرمز ليُفتح الباب. وكل تسليم يقول verification: code أو override أو none.

الخريطة الحية: اشترك بالاسم في express.location_updated (لا يصل لمن اشترك بـ*). يصلك موقع الكابتن من الإسناد حتى الباب، مرة كل 10 ثوانٍ على الأكثر لكل طلب، بشكل ExpressLocationUpdated. الكابتن الذي يحمل طلباً يرسل موقعه فور أخذه، فما يصلك عمره ثوانٍ.

Idempotency: مسارات الكتابة في الشحنات والطلب السريع تقبل ترويسة Idempotency-Key. تكرار نفس المفتاح بنفس الجسم يُعيد الاستجابة المحفوظة بدل إنشاء سجل ثانٍ (مع ترويسة Idempotent-Replay: true)، وتكراره بجسم مختلف يُرفض بـ 422. استخدمه دائماً عند إعادة المحاولة بعد انقطاع الشبكة.

حدود المعدل: 60 طلب/دقيقة لكل مفتاح على عموم الواجهة (120 على مسارات السريع)، و10 طلبات/دقيقة على مسارات البحث بالموبايل ومشاركة العنوان.

الخصوصية: /partner/v1/addresses/lookup-phone يُرجع بيانات محجوبة فقط (exists / has_verified_address) ولا يكشف إحداثيات ولا معلماً ولا رمز التوصيل. كشف العنوان يتم فقط بحيازة رمز التوصيل نفسه.

المناطق

قائمة المناطق

get /partner/v1/zones

المعاملات

city في الرابط · string تصفية حسب المدينة

الردود

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

data Zone[]

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

`message`	string
`errors`	object

بحث بالمناطق والأسماء الشعبية

get /partner/v1/zones/search

يبحث بالاسم الرسمي وبقاموس الأسماء المحكية (مثل «الشام» → دمشق). Scope مطلوب — لا شيء (متاح لأي مفتاح صالح).

المعاملات

q مطلوب في الرابط · string

الردود

200 مناطق مطابقة مع الأسماء الشعبية التي طابقت

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

`message`	string
`errors`	object

بحث بالجغرافيا الرسمية السورية

get /partner/v1/gis/search

الصلاحية addresses:read

بحث نصي بالمناطق الإدارية الرسمية (OCHA P-codes) والتجمعات السكانية.

المعاملات

q مطلوب في الرابط · string

الردود

200 نتائج مناطق/تجمعات سكانية

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

`message`	string
`errors`	object

تحويل إحداثية لتسلسلها الإداري

get /partner/v1/gis/resolve

الصلاحية addresses:read

يُرجع السلسلة الكاملة (محافظة ← منطقة ← ناحية ← حي) لإحداثية.

المعاملات

`lat` مطلوب	في الرابط · number
`lng` مطلوب	في الرابط · number

الردود

200 التسلسل الإداري

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

`message`	string
`errors`	object

404 الإحداثيات خارج الجغرافيا السورية المستوردة

العناوين

قائمة عناوين الشريك

get /partner/v1/addresses

الردود

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

data Address[]

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

`message`	string
`errors`	object

إنشاء عنوان

post /partner/v1/addresses

الصلاحية addresses:write

الجسم application/json

`company_code`	string	رمز الشركة الخاص للعنوان، فريد داخلها. يُقبل في البحث مثل رمزنا.
`label` مطلوب	string
`phone` مطلوب	string
`line1` مطلوب	string
`line2`	string
`city` مطلوب	string
`zone_id`	string
`lat`	number · double
`lng`	number · double

الردود

201 تم الإنشاء

data Address

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

حلّ رمز توصيل إلى عنوان كامل

get /partner/v1/addresses/{code}

الصلاحية addresses:read

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

المعاملات

code مطلوب في المسار · string رمز التوصيل، مثل DMS-2F7-K9Q4X

الردود

200 تفاصيل العنوان

`id`	string
`label`	string
`phone`	string
`line1`	string
`line2`	string \| null
`city`	string
`zone_id`	string \| null
`lat`	number · double \| null
`lng`	number · double \| null
`is_masked`	boolean

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

404 رمز غير موجود

بحث عنوان برقم الهاتف (مقنّع فقط)

get /partner/v1/addresses/lookup-phone

يُرجع نتائج مقنّعة فقط. لا يُكشف رقم الهاتف الكامل ولا تفاصيل العنوان الدقيقة. الحقل is_masked يكون دائماً true.

المعاملات

phone مطلوب في الرابط · string رقم الهاتف للبحث

الردود

200 نتائج مقنّعة

data MaskedAddress[]

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

`message`	string
`errors`	object

404 لا توجد نتائج

طلب مشاركة عنوان عبر الموبايل

post /partner/v1/addresses/request-share

الصلاحية addresses:write

يرسل للزبون رسالة تطلب مشاركة رمز عنوانه. لا يُرجع العنوان إطلاقاً — الرمز يصل للزبون وحده وهو يقرر مشاركته. محدود بـ 10 طلبات/دقيقة.

الجسم application/json

phone مطلوب string

الردود

200 أُرسل الطلب — العنوان غير مُعاد

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

429 تجاوزت حد المعدل

الشحنات والتسوية

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

get /partner/v1/shipments

الصلاحية shipments:read

المعاملات

`status`	في الرابط · string
`reference`	في الرابط · string	مرجعك أو بدايته — `ORD-1001` يجد طرود الطلب كلها (`ORD-1001/P1`، `ORD-1001/P2`).
`page`	في الرابط · integer

الردود

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

data Shipment[]

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

`message`	string
`errors`	object

إنشاء شحنة

post /partner/v1/shipments

الصلاحية shipments:write يقبل Idempotency-Key

يُرفض بـ 422 ورسالة تقول السبب إن كانت شركة الشحن موقوفة (لاشتراك غير مسدّد أو بقرار من المنصة). الشحنات القائمة لا تتأثر: تتبّعها وإلغاؤها وملصقاتها تعمل كالمعتاد.

الجسم application/json

`sender_name` مطلوب	string
`sender_phone` مطلوب	string
`recipient_name` مطلوب	string
`recipient_phone` مطلوب	string
`reference`	string	اسمك أنت للطرد (رقم طلبك). يعود في كل webhook ويُبحث به في القائمة.
`pieces`	integer
`weight_kg`	number
`intake_method`	string	`pickup` `dropoff`
`pickup_address_id`	string	Required unless pickup_tawseel_code is given.
`delivery_address_id`	string	Required unless delivery_tawseel_code is given.
`pickup_tawseel_code`	string
`delivery_tawseel_code`	string
`cod_amount`	number · float
`notes`	string

الردود

201 تم إنشاء الشحنة

data Shipment

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

تفاصيل شحنة

get /partner/v1/shipments/{tracking}

الصلاحية shipments:read

المعاملات

tracking مطلوب في المسار · string

الردود

200 تفاصيل الشحنة مع سجل الحالة

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

`message`	string
`errors`	object

404 غير موجودة

ملصق PDF لشحنة

get /partner/v1/shipments/{tracking}/label.pdf

الصلاحية shipments:read

المعاملات

tracking مطلوب في المسار · string

الردود

200 ملف PDF (Code128 + بيانات الشحنة) application/pdf

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

`message`	string
`errors`	object

404 غير موجودة

ملصقات PDF دفعة واحدة

get /partner/v1/labels.pdf

الصلاحية shipments:read

الردود

200 حتى 50 ملصق للشحنات القابلة للطباعة application/pdf

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

`message`	string
`errors`	object

404 لا توجد شحنات للطباعة

إلغاء شحنة

post /partner/v1/shipments/{tracking}/cancel

الصلاحية shipments:write يقبل Idempotency-Key

يُسمح بالإلغاء فقط ما دامت الشحنة لم تدخل شبكة التشغيل بعد (created / awaiting_pickup / awaiting_dropoff). بعد استلامها فعلياً يصبح الإلغاء قراراً تشغيلياً (إرجاع بضاعة فعلي) ويُرفض بـ 422.

المعاملات

tracking مطلوب في المسار · string

الجسم application/json

reason string

الردود

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

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

404 غير موجودة أو تخص تاجراً آخر

422 الشحنة دخلت شبكة التشغيل — الإلغاء غير مسموح عبر الواجهة

أسابيع تسوية التحصيل

get /partner/v1/cod/settlements

الصلاحية cod:read

الأسابيع المغلقة للتاجر، الأحدث أولاً: الإجمالي والرسوم والصافي والعملة وعدد البنود. تبقى مصفوفة كما كانت.

الردود

200 الأسابيع

`[]id`	integer
`[]status`	string	`closed` `paid`
`[]currency`	string
`[]period_start`	string · date
`[]period_end`	string · date
`[]gross_cod`	number
`[]fees`	number
`[]net`	number
`[]items_count`	integer
`[]closed_at`	string · date-time
`[]paid_at`	string · date-time \| null
`[]payment_method`	string \| null
`[]links`	object
`[]links.self`	string
`[]links.items`	string
`[]links.sellers`	string	حين تكون وحدة المتاجر مفعّلة

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

أسبوع تسوية واحد

get /partner/v1/cod/settlements/{id}

الصلاحية cod:read

المعاملات

id مطلوب في المسار · integer

الردود

200 الأسبوع

data Settlement أسبوع تسوية للتحصيل؛ هو أيضاً شكل data في webhook ‏settlement.closed (مع settlement_id).

404 ليس أسبوعاً لهذا التاجر

بنود الأسبوع — سطر لكل طرد

get /partner/v1/cod/settlements/{id}/items

الصلاحية cod:read

لكل طرد قُبض نقده في الأسبوع: التحصيل، وما خُصم منه (رسم الشحن ورسم التحصيل)، والصافي. الأرقام كما كانت لحظة الإغلاق. حين تكون وحدة المتاجر مفعّلة يحمل السطر أيضاً store_order وseller.

المعاملات

`id` مطلوب	في المسار · integer
`reference`	في الرابط · string	بادئة: `ORD-5001` تجد `ORD-5001/P1` و`/P2`
`per_page`	في الرابط · integer
`page`	في الرابط · integer

الردود

200 البنود

`settlement`	Settlement	أسبوع تسوية للتحصيل؛ هو أيضاً شكل `data` في webhook ‏`settlement.closed` (مع `settlement_id`).
`data`	SettlementItem[]
`meta`	object
`meta.current_page`	integer
`meta.last_page`	integer
`meta.per_page`	integer
`meta.total`	integer

404 ليس أسبوعاً لهذا التاجر

التوصيل السريع

تسعير التوصيل قبل الطلب

post /partner/v1/express/quote

الصلاحية express:read

المسافة ورسم التوصيل والوقت المتوقع (تجهيز + طريق) قبل أن يُطلب. المتجر بمعرّفه عندك (store_ref) أو نقطة استلام. يحتاج نطاق express:read.

الجسم application/json

`store_ref`	string
`pickup`	LatLng
`dropoff` مطلوب	LatLng

الردود

200 التسعير

`data`	object
`data.distance_km`	number
`data.delivery_fee`	number
`data.currency`	string
`data.eta_minutes`	integer

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

قائمة طلباتك

get /partner/v1/express

الصلاحية express:read

المعاملات

`status`	في الرابط · ExpressStatus
`store_ref`	في الرابط · string
`from`	في الرابط · string · date-time
`to`	في الرابط · string · date-time
`per_page`	في الرابط · integer
`page`	في الرابط · integer

الردود

200 صفحة من الطلبات، الأحدث أولاً

`data`	ExpressOrder[]
`meta`	object
`meta.current_page`	integer
`meta.last_page`	integer
`meta.total`	integer

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

`message`	string
`errors`	object

إنشاء طلب توصيل (أكل أو ماركت)

post /partner/v1/express

الصلاحية express:write يقبل Idempotency-Key

الطلب الكامل من تطبيقك: المتجر، الزبون، موقع التسليم (دبوس أو رمز توصيل)، الأصناف، وطريقة الدفع. يُعرض فوراً على الكباتن. نفس external_ref مرتين يعيد الطلب الأول بـ200 ولا يُنشئ طلباً ثانياً. المبلغ الذي يقبضه الكابتن عند الباب (cod_amount) = قيمة الطلب + رسم التوصيل إن كان الدفع cash، وصفر إن كان prepaid. رسم التوصيل يُحسب بقواعد الشركة إن لم ترسله. يحتاج express:write وIdempotency-Key.

الجسم application/json

`external_ref`	string	رقم الطلب في تطبيقك — يمنع التكرار
`store_ref`	string
`store`	ExpressStoreInput
`customer` مطلوب	object
`customer.name` مطلوب	string
`customer.phone` مطلوب	string
`dropoff` مطلوب	object	رمز توصيل، أو الدبوس الذي وضعه الزبون في تطبيقك.
`dropoff.tawseel_code`	string
`dropoff.lat`	number
`dropoff.lng`	number
`dropoff.landmark`	string
`dropoff.street`	string
`dropoff.building`	string
`dropoff.floor`	string
`dropoff.notes`	string
`items`	object[]
`items[].name` مطلوب	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].notes`	string
`subtotal`	number	قيمة الطلب حين لا تُرسل الأصناف
`delivery_fee`	number	إن لم يُرسل يُحسب بقواعد الشركة
`discount`	number	كوبون أو خصم عندك، بالمبلغ. يُطرح مما يقبضه الكابتن. لا يتجاوز قيمة الطلب مع رسم التوصيل (وإلا 422).
`discount_funded_by`	string	من يتحمّل الخصم: `merchant` (أنت) — المتجر يُدفع له كاملاً؛ `store` — يُطرح الخصم أيضاً مما يدفعه الكابتن للمتجر (حتى قيمة الأصناف). `merchant` `store`
`cod_amount`	number	اختياري — ما يقبضه الكابتن بالضبط، إن حسبته أنت (جزء مدفوع من محفظة، إكرامية، أي قاعدة لديك). بدونه: الأصناف + رسم التوصيل − الخصم. طلب `prepaid` لا يحمل مبلغاً هنا (422).
`store_payment`	number	اختياري — ما يدفعه الكابتن للمتجر عند الاستلام بالضبط (لمتجر `captain_pays` فقط). بدونه: قيمة الأصناف، ناقص الخصم إن كان على المتجر.
`payment_method` مطلوب	string	`cash` `prepaid`
`prep_minutes`	integer	إن لم يُرسل فوقت المتجر المعتاد
`ready_at`	string · date-time	طلب مجدول — جاهز في هذا الوقت (خلال 14 يوماً) بدل «بعد prep_minutes من الآن». لا يُعرض على كابتن إلا قرب موعده.
`metadata`	object	بياناتك أنت (حتى 4 كيلوبايت) — تعود كما أرسلتها في كل رد وwebhook.
`delivery_code`	string	رمزك أنت لزبونك (4–6 أرقام). نفحصه عند الباب بدل رمزنا، ولا نرسله لأحد. بلا هذا الحقل نولّد رمزنا (إن فعّلته الشركة) ونعيده في الرد كما اليوم. استبدله بـ`POST /express/{code}/delivery-code`.
`notes`	string

الردود

201 أُنشئ الطلب

data ExpressOrder

200 الطلب موجود بنفس external_ref — أُعيد كما هو

data ExpressOrder

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

متاجرك (مطاعم وماركات)

get /partner/v1/express/stores

الصلاحية express:read

الردود

200 المتاجر

data ExpressStore[]

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

`message`	string
`errors`	object

إضافة متجر أو تحديثه بمعرّفه عندك

post /partner/v1/express/stores

الصلاحية express:write يقبل Idempotency-Key

payment_mode يحدد نقد الكابتن — captain_pays: الكابتن يدفع للمتجر قيمة الطلب عند الاستلام؛ company_settles: الشركة تسوّي مع المتجر لاحقاً ولا يدفع الكابتن شيئاً.

الجسم application/json

`ref` مطلوب	string	معرّف المتجر في تطبيقك
`name` مطلوب	string
`phone`	string \| null
`lat` مطلوب	number
`lng` مطلوب	number
`landmark`	string \| null
`payment_mode`	string	`captain_pays` `company_settles`
`prep_minutes`	integer \| null	وقت التجهيز المعتاد بالدقائق
`active`	boolean

الردود

201 أُضيف المتجر

data ExpressStore

200 حُدّث المتجر

data ExpressStore

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

طلب واحد بحالته وخطواته وكابتنه

get /partner/v1/express/{code}

الصلاحية express:read

المعاملات

code مطلوب في المسار · string

الردود

200 الطلب

data ExpressOrder

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

`message`	string
`errors`	object

404 لا طلب بهذا الرمز لك

أين الطلب ومن يحمله ومتى يصل

get /partner/v1/express/{code}/tracking

الصلاحية express:read

لشاشة التتبع في تطبيقك. للخريطة الحية اشترك في webhook ‏express.location_updated بدل السؤال المتكرر؛ وهذا المسار لفتح الشاشة ولملء ما فات. موقع الكابتن من لحظة الإسناد حتى الباب، وفقط إن كان حديثاً، وكما أبلغ به الكابتن. يحتاج express:read.

المعاملات

code مطلوب في المسار · string

الردود

200 حالة التتبع

data ExpressTracking

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

`message`	string
`errors`	object

404 لا طلب بهذا الرمز لك

إلغاء الطلب

post /partner/v1/express/{code}/cancel

الصلاحية express:write يقبل Idempotency-Key

يُقبل حتى يخرج الطلب من المتجر. بعد الاستلام يُرفض بـ422 والسبب.

المعاملات

code مطلوب في المسار · string

الجسم application/json

reason مطلوب string

الردود

200 أُلغي

data ExpressOrder

404 لا طلب بهذا الرمز لك

422 بيانات غير صالحة

`message`	string
`errors`	object

استبدال رمز التسليم

post /partner/v1/express/{code}/delivery-code

الصلاحية express:write يقبل Idempotency-Key

رمز جديد للزبون، لأنه طلب إعادته أو لأن الرمز قُفل بمحاولات خاطئة. تبدأ المحاولات من الصفر، فيُفتح الباب المقفول.

المعاملات

code مطلوب في المسار · string

الجسم application/json

delivery_code مطلوب string

الردود

200 الطلب بالرمز الجديد

data ExpressOrder

422 الطلب انتهى، أو الرمز ليس 4–6 أرقام

المتجر جهّز الطلب

post /partner/v1/express/{code}/ready

الصلاحية express:write يقبل Idempotency-Key

يضبط وقت الجهوزية الآن — أبكر أو أبعد مما قُدّر عند الطلب.

المعاملات

code مطلوب في المسار · string

الردود

200 سُجّل

data ExpressOrder

404 لا طلب بهذا الرمز لك

422 بيانات غير صالحة

`message`	string
`errors`	object

التسعير

تسعير شحنة / توصيل

post /partner/v1/rates/quote

الصلاحية rates:read

الجسم application/json

`from_zone_id` مطلوب	string
`to_zone_id` مطلوب	string
`weight_kg`	number · float
`service`	string	`standard` `express`

الردود

200 عرض السعر

data RateQuote

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

الإشعارات (webhooks)

قائمة اشتراكات الويب هوك

get /partner/v1/webhooks

الصلاحية webhooks:manage

الردود

200 الاشتراكات

data WebhookEndpoint[]

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

`message`	string
`errors`	object

تسجيل نقطة ويب هوك

post /partner/v1/webhooks

الصلاحية webhooks:manage

الرد يحمل secret الذي نولّده نحن — احفظه. كل إرسال جسمه: {"id": "evt_123", "event": "shipment.status_changed", "occurred_at": "…", "data": {…}} مع الترويسات:

X-Tawseel-Signature: HMAC-SHA256 بالـsecret للجسم الخام كما وصل (hex).
X-Tawseel-Event-Id: نفس id — ثابت في كل إعادة محاولة لهذا الحدث؛ تجاهل ما رأيته.
X-Tawseel-Timestamp: وقت الحدث (Unix) — داخل الجسم الموقّع أيضاً، فارفض القديم جداً.

نعيد المحاولة حتى 3 مرات إن لم يصل رد 2xx.

الجسم application/json

`url` مطلوب	string · uri
`events` مطلوب	string[]	`shipment.created` `shipment.status_changed` `shipment.delivered` `shipment.returned` `store_order.updated` `express.status_changed` `express.location_updated` `delivery.code_failed` `delivery.code_locked` `webhook.test` `settlement.closed` `settlement.paid` `*`
`secret`	string	سر للتحقق من توقيع الحمولة

الردود

201 تم التسجيل

data WebhookEndpoint

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

`message`	string
`errors`	object

422 بيانات غير صالحة

`message`	string
`errors`	object

تغيير العنوان أو الأحداث أو إيقافها مؤقتاً

patch /partner/v1/webhooks/{id}

الصلاحية webhooks:manage

المعاملات

id مطلوب في المسار · integer

الجسم application/json

`url`	string · uri
`events`	string[]
`active`	boolean

الردود

200 النقطة بعد التغيير

404 ليست لك

إيقاف النقطة (يبقى سجل ما أُرسل لها)

delete /partner/v1/webhooks/{id}

الصلاحية webhooks:manage

المعاملات

id مطلوب في المسار · integer

الردود

200 أُوقفت (`active: false`)

سرّ جديد فوراً

post /partner/v1/webhooks/{id}/rotate-secret

الصلاحية webhooks:manage

السرّ القديم يتوقف عن التحقق من الإرسال التالي. الرد هو المرة الوحيدة التي يُعرض فيها الجديد.

المعاملات

id مطلوب في المسار · integer

الردود

200 النقطة ومعها `secret` الجديد

إرسال حدث تجريبي (`webhook.test`) لهذه النقطة

post /partner/v1/webhooks/{id}/test

الصلاحية webhooks:manage

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

المعاملات

id مطلوب في المسار · integer

الردود

202 في الطابور

سجل ما أُرسل لهذه النقطة وكيف أجابت

get /partner/v1/webhooks/{id}/deliveries

الصلاحية webhooks:manage

المعاملات

`id` مطلوب	في المسار · integer
`status`	في الرابط · string
`event`	في الرابط · string

الردود

200 الأحدث أولاً، 50 في الصفحة

data WebhookDelivery[]

إعادة إرسال حدث (بنفس `event_id`)

post /partner/v1/webhook-deliveries/{id}/redeliver

الصلاحية webhooks:manage

بعد إصلاح جهتك. المستقبِل الذي وصله أول مرة يُسقط النسخة بالمعرّف.

المعاملات

id مطلوب في المسار · integer

الردود

202 في الطابور

المتاجر والأسواق

حصة كل بائع من الأسبوع

get /partner/v1/cod/settlements/{id}/sellers

الصلاحية cod:read

لسوقٍ متعدد البائعين. يعطي لكل بائع عدد طروده ومجموع التحصيل والرسوم والصافي، ثم unattributed لطرود التاجر نفسه. مجموع الأسطر يساوي أرقام الأسبوع بالضبط. ومع seller_ref تأتي أسطر ذلك البائع في items.

المعاملات

`id` مطلوب	في المسار · integer
`seller_ref`	في الرابط · string

الردود

200 الحصص

`settlement`	Settlement	أسبوع تسوية للتحصيل؛ هو أيضاً شكل `data` في webhook ‏`settlement.closed` (مع `settlement_id`).
`sellers`	object[]
`unattributed`	SettlementShare
`items`	SettlementItem[]	مع `seller_ref` فقط

404 ليس أسبوعاً لهذا التاجر

استقبال طلب من متجر التاجر

post /partner/v1/store-orders

الصلاحية shipments:write يقبل Idempotency-Key

الباب الموحّد: أرسل الطلب فور موافقة التاجر عليه في متجره. العقد الكامل بالحقول والأمثلة في docs/partner-api/store-order-intake.md.

يردّ 202 قبل المعالجة عمداً: المتجر لا ينتظرنا، والفشل يُسجَّل على الطلب لا في الاستجابة. لذلك 202 تعني «وصل وسُجِّل»، لا «صارت شحنة» — اقرأ status في الجسم، وهو أحد received / ignored / needs_address / shipped / failed.

external_id هو الهوية: إعادة إرسال نفس الطلب تحدّثه ولا تنشئ ثانياً، فالتكرار آمن بلا ترويسة إضافية.

الجسم application/json

`connection_id`	integer	اختياري — الاتصال الذي يتبع له الطلب. بدونه يُستخدم اتصال Partner API الخاص بالتاجر.
`external_id` مطلوب	string	رقم الطلب في متجرك — الهوية التي نعتمدها
`external_number`	string
`status` مطلوب	string	حالة الطلب عندك. الشحن يبدأ فقط عند حالة الإطلاق المضبوطة على الاتصال.
`payment` مطلوب	object
`payment.method` مطلوب	string	`cod` `prepaid`
`payment.cod_amount`	number	يجب أن يكون صفراً أو غائباً عندما يكون الدفع مسبقاً. مع `packages` يُحسب من حصصها إن غاب.
`payment.currency`	string
`recipient` مطلوب	object
`recipient.name` مطلوب	string
`recipient.phone` مطلوب	string
`delivery` مطلوب	object	رمز التوصيل وحده يكفي. بدونه أرسل المدينة والمنطقة على الأقل.
`delivery.tawseel_code`	string
`delivery.city`	string
`delivery.zone`	string
`delivery.address_text`	string
`delivery.lat`	number
`delivery.lng`	number
`delivery.notes`	string
`parcel`	object
`parcel.weight_kg`	number
`parcel.pieces`	integer
`parcel.service_level`	string	`standard` `intra_city`
`parcel.items`	object[]
`parcel.items[].sku`	string
`parcel.items[].name` مطلوب	string
`parcel.items[].qty`	integer
`parcel.items[].price`	number
`metadata`	object	بياناتك أنت (حتى 4 كيلوبايت) — تعود كما أرسلتها في الرد وفي `store_order.updated`.
`delivery_code`	string	رمزك لزبونك: كل طرود الطلب تُسلَّم عند بابها مقابله. لا نرسله لأحد. بلا هذا الحقل تُسلَّم الطرود بلا رمز كما اليوم. استبدله بـ`POST /store-orders/{externalId}/delivery-code`.
`seller_ref`	string	سوق متعدد البائعين — طلب من بائع واحد، مسجّل عبر `/sellers`. يُستلم من بابه.
`seller`	SellerInput	البائع برقمه عندك، وباب استلام طروده (إحداثيات أو رمز توصيل).
`packages`	StoreOrderPackageInput[]	طلب من أكثر من بائع: طرد لكل بائع، يُستلم من بابه ويصل للزبون منفصلاً ويُدفع عند بابه بحصته. مجموع `cod_amount` للطرود = تحصيل الطلب، وإلا رُفض الطلب برسالة تذكر الرقمين. بائع غير معروف يوقف الطلب كله (`failed` مع السبب) — لا يُشحن نصفه.

الردود

202 وصل وسُجِّل — اقرأ `status` لمعرفة ما جرى له

`store_order_id`	integer
`status`	string	`received` `ignored` `needs_address` `shipped` `failed`
`data`	StoreOrder	الطلب كما نراه — يعود في الرد، وفي `GET store-orders/{id}`، وفي webhook ‏`store_order.updated` (مع `changed`).

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

404 لا يوجد اتصال متجر بهذا الرقم

422 الحمولة غير مقروءة — الرسالة تُسمّي الحقل الناقص أو المتناقض

الطلب وطروده برقمه عندك

get /partner/v1/store-orders/{externalId}

الصلاحية shipments:read

الحالة، وسبب التوقف إن توقف، ولكل طرد رقم التتبع وحالته ورابط صفحة الزبون والملصق. Scope shipments:read.

المعاملات

externalId مطلوب في المسار · string

الردود

200 الطلب

data StoreOrder الطلب كما نراه — يعود في الرد، وفي GET store-orders/{id}، وفي webhook ‏store_order.updated (مع changed).

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

`message`	string
`errors`	object

404 لا يوجد طلب بهذا الرقم لهذا التاجر

ملصقات الطلب كله في ملف واحد

get /partner/v1/store-orders/{externalId}/labels.pdf

الصلاحية shipments:read

للوحة البائع تطبعها وتلصقها على الطرود. Scope shipments:read.

المعاملات

externalId مطلوب في المسار · string

الردود

200 PDF application/pdf

404 لا طلب بهذا الرقم، أو لم يُشحن بعد

بائعوك (سوق متعدد البائعين)

get /partner/v1/sellers

الصلاحية shipments:read

الردود

200 البائعون

data Seller[]

تسجيل بائع أو تحديثه برقمه عندك

post /partner/v1/sellers

الصلاحية shipments:write يقبل Idempotency-Key

باب الاستلام إحداثيات أو رمز توصيل — نصٌّ وحده لا يكفي ليجده الكابتن. نفس ref مرة ثانية يحدّث البائع. Scope shipments:write، وIdempotency-Key.

الجسم application/json

`ref` مطلوب	string
`name` مطلوب	string
`phone`	string
`lat`	number
`lng`	number
`tawseel_code`	string
`landmark`	string
`active`	boolean

الردود

201 سُجّل

data Seller

200 حُدّث

422 بيانات غير صالحة

`message`	string
`errors`	object

استبدال رمز تسليم الطلب

post /partner/v1/store-orders/{externalId}/delivery-code

الصلاحية shipments:write يقبل Idempotency-Key

كل طرد من الطلب لم يُسلَّم بعد يأخذ الرمز الجديد، وتبدأ محاولاته من الصفر.

المعاملات

externalId مطلوب في المسار · string

الجسم application/json

delivery_code مطلوب string

الردود

200 الطلب

data StoreOrder الطلب كما نراه — يعود في الرد، وفي GET store-orders/{id}، وفي webhook ‏store_order.updated (مع changed).

422 لا طرد ينتظر التسليم، أو الرمز ليس 4–6 أرقام

مرتجع بطلب الزبون

post /partner/v1/store-orders/{externalId}/returns

الصلاحية shipments:write يقبل Idempotency-Key

الزبون استلم طرداً ويريد إعادة شيء منه. يذهب كابتن إلى باب الزبون، ويتصل بالزبون نفسه، ثم يحمل القطعة إلى باب البائع الذي أرسلها، أو إلى باب التاجر لطرد بلا بائع. أعطوا الزبون tracking_code، فهو يقرؤه للكابتن عند الباب، أو اطبعوا له label_url.

يُقبل فقط بعد تسليم الطرد (delivered)، ويبقى الطرد الأصلي delivered.
لا تحصيل على المرتجع: استرداد المبلغ للزبون بينكم وبينه. ورسوم المرتجع (الشحن والاستلام) تصل فاتورتكم.
ref رقم المرتجع عندكم: إعادة الإرسال بنفس الرقم تعيد المرتجع نفسه (200). ومرتجع واحد مفتوح لكل طرد.
كل تغيّر يصلكم في store_order.updated ضمن packages[].returns، ولا يُكتب في حالة طلبكم.

المعاملات

externalId مطلوب في المسار · string رقم الطلب في متجرك

الجسم application/json

`ref` مطلوب	string
`package_ref`	string	الطرد الذي يُعاد منه — مطلوب إن كان في الطلب أكثر من طرد
`reason`	string
`items`	object[]
`items[].name` مطلوب	string
`items[].sku`	string
`items[].qty`	integer
`pieces`	integer
`weight_kg`	number

الردود

201 فُتح المرتجع، وطُلب الاستلام من باب الزبون

`data`	StoreOrderReturn	مرتجع بطلب الزبون — في رد فتحه، وفي `packages[].returns` من الطلب.
`order`	StoreOrder	الطلب كما نراه — يعود في الرد، وفي `GET store-orders/{id}`، وفي webhook ‏`store_order.updated` (مع `changed`).

200 المرتجع نفسه (أُرسل بالرقم من قبل)

404 لا يوجد طلب بهذا الرقم

422 لم يُسلَّم الطرد بعد، أو له مرتجع مفتوح، أو الطرد غير محدد أو غير معروف — والسبب في `message`

إلغاء مرتجع

post /partner/v1/store-orders/{externalId}/returns/{ref}/cancel

الصلاحية shipments:write يقبل Idempotency-Key

ما دامت القطعة عند الزبون. بعد أن يستلمها الكابتن يُرفض بـ422.

المعاملات

`externalId` مطلوب	في المسار · string
`ref` مطلوب	في المسار · string

الجسم application/json

reason string

الردود

200 أُلغي

data StoreOrderReturn مرتجع بطلب الزبون — في رد فتحه، وفي packages[].returns من الطلب.

404 لا مرتجع بهذا الرقم لهذا الطلب

422 استُلم من الزبون — لا يُلغى

إلغاء طلب متجر

post /partner/v1/store-orders/{externalId}/cancel

الصلاحية shipments:write يقبل Idempotency-Key

يُلغى ما دامت الشحنة لم تدخل شبكة التشغيل. بعد استلامها فعلياً يصبح الإلغاء إرجاع بضاعة ويُرفض بـ 422.

المعاملات

externalId مطلوب في المسار · string رقم الطلب في متجرك

الجسم application/json

reason string

الردود

200 أُلغي الطلب ومعه شحنته إن وُجدت

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

`message`	string
`errors`	object

403 المفتاح صالح لكنه لا يملك الصلاحية (Scope) المطلوبة لهذا المسار

`message`	string
`errors`	object

404 لا يوجد طلب بهذا الرقم لهذا التاجر

422 الشحنة دخلت شبكة التشغيل — الإلغاء غير مسموح عبر الواجهة

الأحداث

ما يمكن أن تشترك به نقطة إشعاراتك (تسجيل نقطة). * يعني كلها إلا ما يُطلب بالاسم.

shipment.created shipment.status_changed shipment.delivered shipment.returned store_order.updated express.status_changed express.location_updated delivery.code_failed delivery.code_locked webhook.test settlement.closed settlement.paid

الأشكال

Error

`message`	string
`errors`	object

Zone

`id`	string
`name`	string
`city`	string

Address

`id`	string
`label`	string
`phone`	string
`line1`	string
`line2`	string \| null
`city`	string
`zone_id`	string \| null
`lat`	number · double \| null
`lng`	number · double \| null
`is_masked`	boolean

MaskedAddress

عنوان مقنّع — يُرجع من lookup-phone فقط

`id` مطلوب	string
`label`	string	تسمية مقنّعة
`phone`	string	رقم هاتف مقنّع مثل 77****123
`city`	string
`zone_id`	string \| null
`is_masked` مطلوب	boolean	`true`

AddressCreate

`company_code`	string	رمز الشركة الخاص للعنوان، فريد داخلها. يُقبل في البحث مثل رمزنا.
`label` مطلوب	string
`phone` مطلوب	string
`line1` مطلوب	string
`line2`	string
`city` مطلوب	string
`zone_id`	string
`lat`	number · double
`lng`	number · double

Shipment

`id`	string
`tracking_number`	string
`tracking_code`	string
`reference`	string \| null	مرجعك للطرد كما أرسلته
`status`	string
`pickup_address_id`	string
`delivery_address_id`	string
`cod_amount`	number · float \| null
`sort_code`	string \| null	رمز الفرز: مركز الوجهة ثم فرع الوجهة، مثل «DMS › ALP-03». يُطبع كبيراً على ملصقك إن كنت تطبع ملصقاتك بنفسك. فارغ حين لا يُعرف فرع الوجهة بعد.
`created_at`	string · date-time

ShipmentCreate

Each end is given either as an address id or as a Tawseel code. An id is accepted only for an address this merchant created, already shipped to, or was given the code for; any other id answers 422 on that field. A code is the recipient's permission: it is accepted, and the id works from then on.

`sender_name` مطلوب	string
`sender_phone` مطلوب	string
`recipient_name` مطلوب	string
`recipient_phone` مطلوب	string
`reference`	string	اسمك أنت للطرد (رقم طلبك). يعود في كل webhook ويُبحث به في القائمة.
`pieces`	integer
`weight_kg`	number
`intake_method`	string	`pickup` `dropoff`
`pickup_address_id`	string	Required unless pickup_tawseel_code is given.
`delivery_address_id`	string	Required unless delivery_tawseel_code is given.
`pickup_tawseel_code`	string
`delivery_tawseel_code`	string
`cod_amount`	number · float
`notes`	string

LatLng

`lat` مطلوب	number
`lng` مطلوب	number

ExpressStatus

placed استُلم · searching نبحث عن كابتن · unassigned لم يقبله أحد بعد · assigned الكابتن في الطريق للمتجر · at_store في المتجر · picked_up في الطريق للزبون · at_customer عند الباب · delivered سُلّم · failed لم يُسلَّم · cancelled أُلغي

ExpressStoreInput

`ref` مطلوب	string	معرّف المتجر في تطبيقك
`name` مطلوب	string
`phone`	string \| null
`lat` مطلوب	number
`lng` مطلوب	number
`landmark`	string \| null
`payment_mode`	string	`captain_pays` `company_settles`
`prep_minutes`	integer \| null	وقت التجهيز المعتاد بالدقائق
`active`	boolean

ExpressStore

`id`	integer
`ref`	string
`name`	string
`phone`	string \| null
`lat`	number
`lng`	number
`payment_mode`	string	`captain_pays` `company_settles`
`prep_minutes`	integer \| null
`active`	boolean

ExpressOrderCreate

المتجر بـstore_ref (مسجّل عبر /express/stores) أو بـstore كاملاً فيُسجَّل معه.

`external_ref`	string	رقم الطلب في تطبيقك — يمنع التكرار
`store_ref`	string
`store`	ExpressStoreInput
`customer` مطلوب	object
`customer.name` مطلوب	string
`customer.phone` مطلوب	string
`dropoff` مطلوب	object	رمز توصيل، أو الدبوس الذي وضعه الزبون في تطبيقك.
`dropoff.tawseel_code`	string
`dropoff.lat`	number
`dropoff.lng`	number
`dropoff.landmark`	string
`dropoff.street`	string
`dropoff.building`	string
`dropoff.floor`	string
`dropoff.notes`	string
`items`	object[]
`items[].name` مطلوب	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].notes`	string
`subtotal`	number	قيمة الطلب حين لا تُرسل الأصناف
`delivery_fee`	number	إن لم يُرسل يُحسب بقواعد الشركة
`discount`	number	كوبون أو خصم عندك، بالمبلغ. يُطرح مما يقبضه الكابتن. لا يتجاوز قيمة الطلب مع رسم التوصيل (وإلا 422).
`discount_funded_by`	string	من يتحمّل الخصم: `merchant` (أنت) — المتجر يُدفع له كاملاً؛ `store` — يُطرح الخصم أيضاً مما يدفعه الكابتن للمتجر (حتى قيمة الأصناف). `merchant` `store`
`cod_amount`	number	اختياري — ما يقبضه الكابتن بالضبط، إن حسبته أنت (جزء مدفوع من محفظة، إكرامية، أي قاعدة لديك). بدونه: الأصناف + رسم التوصيل − الخصم. طلب `prepaid` لا يحمل مبلغاً هنا (422).
`store_payment`	number	اختياري — ما يدفعه الكابتن للمتجر عند الاستلام بالضبط (لمتجر `captain_pays` فقط). بدونه: قيمة الأصناف، ناقص الخصم إن كان على المتجر.
`payment_method` مطلوب	string	`cash` `prepaid`
`prep_minutes`	integer	إن لم يُرسل فوقت المتجر المعتاد
`ready_at`	string · date-time	طلب مجدول — جاهز في هذا الوقت (خلال 14 يوماً) بدل «بعد prep_minutes من الآن». لا يُعرض على كابتن إلا قرب موعده.
`metadata`	object	بياناتك أنت (حتى 4 كيلوبايت) — تعود كما أرسلتها في كل رد وwebhook.
`delivery_code`	string	رمزك أنت لزبونك (4–6 أرقام). نفحصه عند الباب بدل رمزنا، ولا نرسله لأحد. بلا هذا الحقل نولّد رمزنا (إن فعّلته الشركة) ونعيده في الرد كما اليوم. استبدله بـ`POST /express/{code}/delivery-code`.
`notes`	string

ExpressOrder

`code`	string
`external_ref`	string \| null
`status`	ExpressStatus	placed استُلم · searching نبحث عن كابتن · unassigned لم يقبله أحد بعد · assigned الكابتن في الطريق للمتجر · at_store في المتجر · picked_up في الطريق للزبون · at_customer عند الباب · delivered سُلّم · failed لم يُسلَّم · cancelled أُلغي `placed` `searching` `unassigned` `assigned` `at_store` `picked_up` `at_customer` `delivered` `failed` `cancelled`
`status_label`	string
`store`	object \| null
`store.id`	integer
`store.ref`	string
`store.name`	string
`customer`	object
`customer.name`	string
`customer.phone`	string
`dropoff`	object
`dropoff.tawseel_code`	string
`dropoff.lat`	number
`dropoff.lng`	number
`dropoff.landmark`	string
`items`	object[]
`items[].name`	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].notes`	string \| null
`payment`	object
`payment.currency`	string
`payment.method`	string	`cash` `prepaid`
`payment.subtotal`	number
`payment.delivery_fee`	number
`payment.discount`	number
`payment.discount_funded_by`	string \| null	`merchant` `store`
`payment.cod_amount`	number	ما يقبضه الكابتن عند الباب
`payment.store_payment`	number	ما يدفعه الكابتن للمتجر عند الاستلام
`delivery_code`	string \| null	الرمز الذي يُفحص عند الباب: رمزك إن أرسلته، وإلا رمزنا. يقرؤه الزبون للكابتن، ولا يُسجَّل الطلب «سُلّم» بدونه إلا باستثناء من الموزّع. لا يُرسَل للكابتن أبداً.
`verification`	string \| null	كيف سُلِّم — بالرمز، أو باستثناء من الموزّع (بسبب في `override_reason`)، أو بلا رمز يُطلب. null قبل التسليم. `code` `override` `none`
`verified_at`	string · date-time \| null
`override_reason`	string \| null	سبب الموزّع واسمه، حين `verification = override`
`tracking_url`	string · uri	صفحة تتبع للزبون على نطاق الشركة — أرسلها له إن لم يكن في تطبيقك تتبع. رابط سرّي لا يُخمَّن (ليس رقم الطلب).
`distance_km`	number \| null
`ready_at`	string · date-time \| null
`promised_at`	string · date-time \| null
`captain`	object \| null	من يحمل الطلب، منذ قبوله
`captain.name`	string
`captain.phone`	string
`cancel_reason`	string \| null
`metadata`	object \| null	كما أرسلته
`timeline`	object[]	كل خطوة بوقتها، بالترتيب
`timeline[].status`	ExpressStatus	placed استُلم · searching نبحث عن كابتن · unassigned لم يقبله أحد بعد · assigned الكابتن في الطريق للمتجر · at_store في المتجر · picked_up في الطريق للزبون · at_customer عند الباب · delivered سُلّم · failed لم يُسلَّم · cancelled أُلغي `placed` `searching` `unassigned` `assigned` `at_store` `picked_up` `at_customer` `delivered` `failed` `cancelled`
`timeline[].label`	string
`timeline[].at`	string · date-time
`timeline[].note`	string \| null
`created_at`	string · date-time

ExpressTracking

`code`	string
`status`	ExpressStatus	placed استُلم · searching نبحث عن كابتن · unassigned لم يقبله أحد بعد · assigned الكابتن في الطريق للمتجر · at_store في المتجر · picked_up في الطريق للزبون · at_customer عند الباب · delivered سُلّم · failed لم يُسلَّم · cancelled أُلغي `placed` `searching` `unassigned` `assigned` `at_store` `picked_up` `at_customer` `delivered` `failed` `cancelled`
`status_label`	string
`step`	integer \| null	الخطوة الحالية من الخمس في steps؛ null إن فشل الطلب أو أُلغي
`steps`	object[]	الخطوات الخمس التي ينتظرها الزبون، مع وقت أول بلوغ لكل منها
`steps[].key`	string	`received` `captain` `at_store` `on_the_way` `delivered`
`steps[].label`	string
`steps[].at`	string · date-time \| null
`store`	object \| null
`store.name`	string
`captain`	object \| null	ما دام الطلب جارياً فقط
`captain.name`	string
`captain.phone`	string
`position`	object \| null	من لحظة الإسناد حتى الباب، وإن كان حديثاً (صفحة الزبون العامة تُظهره من الاستلام فقط)
`position.lat`	number
`position.lng`	number
`position.heading`	integer \| null	الاتجاه بالدرجات من الشمال
`position.speed_kmh`	number \| null
`position.recorded_at`	string · date-time	متى أُخذ الموقع على هاتف الكابتن
`position.seconds_ago`	integer
`heading_to`	string \| null	إلى أين يتجه الكابتن الآن لهذا الطلب — المتجر حتى الاستلام، ثم الباب `pickup` `dropoff`
`target`	object \| null	النقطة التي يُحسب الوقت المتوقع إليها — ارسم خطك إليها
`target.lat`	number
`target.lng`	number
`eta`	object \| null	تقديري: قبل الاستلام وصول الكابتن للمتجر أو جهوزية الطلب أيهما أبعد ثم الطريق للباب؛ بعده الطريق للباب وحده؛ 0 والكابتن عند الباب. null بعد انتهاء الطلب.
`eta.minutes`	integer
`eta.at`	string · date-time
`final`	boolean	لن يتغيّر شيء بعد — توقّف عن السؤال
`cancel_reason`	string \| null
`tracking_url`	string · uri

ExpressLocationUpdated

حمولة webhook ‏express.location_updated (داخل data). مرة كل 10 ثوانٍ على الأكثر لكل طلب، من الإسناد حتى الباب.

`code`	string
`external_ref`	string \| null
`status`	ExpressStatus	placed استُلم · searching نبحث عن كابتن · unassigned لم يقبله أحد بعد · assigned الكابتن في الطريق للمتجر · at_store في المتجر · picked_up في الطريق للزبون · at_customer عند الباب · delivered سُلّم · failed لم يُسلَّم · cancelled أُلغي `placed` `searching` `unassigned` `assigned` `at_store` `picked_up` `at_customer` `delivered` `failed` `cancelled`
`position`	object
`position.lat`	number
`position.lng`	number
`position.heading`	integer \| null
`position.speed_kmh`	number \| null
`position.recorded_at`	string · date-time
`position.seconds_ago`	integer
`heading_to`	string	`pickup` `dropoff`
`target`	object
`target.lat`	number
`target.lng`	number
`eta`	object \| null
`eta.minutes`	integer
`eta.at`	string · date-time

SellerInput

البائع برقمه عندك، وباب استلام طروده (إحداثيات أو رمز توصيل).

`ref` مطلوب	string
`name` مطلوب	string
`phone`	string
`lat`	number
`lng`	number
`tawseel_code`	string
`landmark`	string
`active`	boolean

Seller

`ref`	string
`name`	string
`phone`	string \| null
`active`	boolean
`pickup`	object
`pickup.tawseel_code`	string \| null
`pickup.lat`	number \| null
`pickup.lng`	number \| null
`pickup.landmark`	string \| null

StoreOrderPackageInput

`ref` مطلوب	string	رقم الطرد عندك، فريد داخل الطلب
`seller_ref`	string
`seller`	SellerInput	البائع برقمه عندك، وباب استلام طروده (إحداثيات أو رمز توصيل).
`cod_amount`	number	حصة هذا الطرد مما يدفعه الزبون
`weight_kg`	number
`pieces`	integer
`items`	object[]
`items[].name`	string
`items[].sku`	string
`items[].qty`	integer
`items[].price`	number

Settlement

أسبوع تسوية للتحصيل؛ هو أيضاً شكل data في webhook ‏settlement.closed (مع settlement_id).

`id`	integer
`status`	string	`closed` `paid`
`currency`	string
`period_start`	string · date
`period_end`	string · date
`gross_cod`	number
`fees`	number
`net`	number
`items_count`	integer
`closed_at`	string · date-time
`paid_at`	string · date-time \| null
`payment_method`	string \| null
`links`	object
`links.self`	string
`links.items`	string
`links.sellers`	string	حين تكون وحدة المتاجر مفعّلة

SettlementItem

`id`	integer
`tracking_code`	string
`reference`	string \| null
`cod_amount`	number
`shipping_fee`	number
`cod_fee`	number
`net`	number	التحصيل ناقص الرسمين
`collected_at`	string · date-time
`store_order`	object \| null
`store_order.external_id`	string
`store_order.external_number`	string \| null
`store_order.package_ref`	string \| null
`seller`	object \| null
`seller.ref`	string
`seller.name`	string

SettlementShare

`parcels`	integer
`gross_cod`	number
`fees`	number
`net`	number

StoreOrderReturn

مرتجع بطلب الزبون — في رد فتحه، وفي packages[].returns من الطلب.

`ref`	string
`package_ref`	string
`reason`	string \| null
`items`	object[] \| null
`tracking_code`	string	يقرؤه الزبون للكابتن عند الباب
`reference`	string
`status`	string	حالة شحنة المرتجع — awaiting_pickup ← picked_up ← … ← delivered (وصل البائع)، أو cancelled
`tracking_url`	string · uri
`label_url`	string · uri
`created_at`	string · date-time

StoreOrder

الطلب كما نراه — يعود في الرد، وفي GET store-orders/{id}، وفي webhook ‏store_order.updated (مع changed).

`external_id`	string
`external_number`	string \| null
`status`	string	`received` `ignored` `needs_address` `ready` `shipped` `failed` `cancelled`
`reason`	string \| null	لماذا ينتظر أو توقف — بالعربية لمن يقرؤه
`payment`	object
`payment.method`	string	`cod` `prepaid`
`payment.cod_amount`	number
`payment.currency`	string
`packages`	object[]
`packages[].ref`	string
`packages[].seller_ref`	string \| null
`packages[].returns`	StoreOrderReturn[]	مرتجعات الزبون من هذا الطرد
`packages[].cod_amount`	number
`packages[].tracking_code`	string \| null
`packages[].reference`	string \| null
`packages[].status`	string \| null
`packages[].tracking_url`	string · uri \| null	صفحة التتبع للزبون
`packages[].label_url`	string · uri \| null	الملصق (بمفتاحك)
`packages[].verification`	string \| null	كيف سُلِّم الطرد `code` `override` `none`
`packages[].verified_at`	string · date-time \| null
`metadata`	object \| null	كما أرسلته
`changed`	object \| null	في webhook فقط — الطرد الذي تغيّر
`changed.tracking_code`	string
`changed.reference`	string \| null
`changed.status`	string
`received_at`	string · date-time

WebhookDelivery

`id`	integer
`event_id`	string
`event`	string
`status`	string	`pending` `success` `failed`
`attempts`	integer
`last_response`	string \| null	أول 500 حرف من ردّك أو الخطأ
`payload`	object
`created_at`	string · date-time
`updated_at`	string · date-time

RateQuote

`currency`	string
`amount`	number · float
`service`	string
`eta_hours`	integer \| null

WebhookEndpoint

`id`	string
`url`	string · uri
`events`	string[]
`active`	boolean
`created_at`	string · date-time