{ "openapi": "3.1.0", "info": { "title": "Delivery Syria Company API", "x-title-ar": "واجهة شركة التوصيل في Delivery Syria", "version": "v1", "summary": "Read your merchants, couriers and parcels, create parcels for your merchants, assign couriers and update statuses.", "x-summary-ar": "قراءة تجّارك ومناديبك وطرودك، وإنشاء طرود لتجّارك، وتعيين المناديب، وتحديث الحالات.", "description": "The company API (`/api/company/v1`) lets the system of a delivery company read its merchants, couriers and parcels, create parcels for its merchants, assign couriers and update parcel statuses. Everything is limited to your company. Every call is authenticated with a Bearer API key and every answer is JSON in the same envelope: `{\"success\": true, \"data\": ...}` (plus `meta` on paginated lists) or `{\"success\": false, \"error\": {\"code\", \"message\"}}`. Always send `Accept: application/json`.\n\nThis document was written from the application code and is checked against the real routes, validation rules and response shapes by automated tests. It describes only what the code does. There is no versioning header, no `Idempotency-Key` support and no \"try it out\" console, and the company API has no endpoints to manage webhook links (use the company panel). Rate limits are described on each operation: requests per minute per IP address, plus the limits of your plan.\n\nFor guides and explanations read the developer articles of the documentation center.", "x-description-ar": "تتيح واجهة الشركة (`/api/company/v1`) لنظام شركة التوصيل قراءة تجّارها ومناديبها وطرودها، وإنشاء طرود لتجّارها، وتعيين المناديب، وتحديث حالات الطرود. كل شيء مقيّد بشركتك. كل استدعاء يُوثَّق بمفتاح API في ترويسة Bearer، وكل ردّ بصيغة JSON وبالغلاف نفسه: `{\"success\": true, \"data\": ...}` (مع `meta` في القوائم المرقّمة) أو `{\"success\": false, \"error\": {\"code\", \"message\"}}`. أرسل دائماً `Accept: application/json`.\n\nكُتب هذا المستند من كود التطبيق، وتفحصه اختبارات آلية مقابل المسارات وقواعد التحقق وأشكال الردود الفعلية. وهو يصف ما يفعله الكود فقط. ولا توجد ترويسة للإصدار ولا دعم لـ `Idempotency-Key` ولا لوحة «جرّب الآن»، ولا تتضمن واجهة الشركة مسارات لإدارة روابط الويب هوك (استخدم لوحة الشركة). وحدود الطلبات موصوفة في كل عملية: طلبات في الدقيقة لكل عنوان IP، إضافة إلى حدود باقتك.\n\nللأدلة والشروحات اقرأ مقالات المطورين في مركز التوثيق.", "x-api-prefix": "/api/company/v1" }, "servers": [ { "url": "/api/company/v1", "description": "Relative to your platform host: `https://YOUR_DOMAIN/api/company/v1`.", "x-description-ar": "نسبي إلى نطاق منصتك: `https://YOUR_DOMAIN/api/company/v1`." } ], "security": [ { "bearerApiKey": [] } ], "tags": [ { "name": "Account", "description": "Your company, plan and usage.", "x-name-ar": "الحساب", "x-description-ar": "شركتك وباقتها واستهلاكها." }, { "name": "Merchants", "description": "Your merchants and their pickup locations.", "x-name-ar": "التجّار", "x-description-ar": "تجّارك وأماكن الاستلام لديهم." }, { "name": "Couriers", "description": "Your couriers (deliverymen) with their load.", "x-name-ar": "المناديب", "x-description-ar": "مناديبك مع حمولتهم." }, { "name": "Parcels", "description": "List and read parcels, create a parcel for a merchant, assign a courier and update the status.", "x-name-ar": "الطرود", "x-description-ar": "عرض الطرود وقراءتها، وإنشاء طرد لتاجر، وتعيين مندوب، وتحديث الحالة." }, { "name": "Webhook events", "description": "Messages the platform sends to the webhook links you register in the company panel. The company API has no endpoints to manage those links.", "x-name-ar": "أحداث الويب هوك", "x-description-ar": "الرسائل التي ترسلها المنصة إلى روابط الويب هوك التي تسجّلها في لوحة الشركة. ولا تتضمن واجهة الشركة مسارات لإدارة هذه الروابط." } ], "paths": { "/me": { "get": { "operationId": "getCompanyAccount", "tags": [ "Account" ], "summary": "Get your company account", "x-summary-ar": "جلب حساب شركتك", "description": "Returns your company, active plan (with its features) and the usage rows against the plan limits. A good first call to check the key.", "x-description-ar": "تُرجع شركتك وباقتها الفعّالة (مع ميزاتها) وصفوف الاستهلاك مقابل حدود الباقة. وهي أول استدعاء مناسب للتأكد من المفتاح.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Your company account.", "x-description-ar": "حساب شركتك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Account" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "company": { "id": 3, "name": "Example Delivery", "phone": "0900000000" }, "plan": { "name": "Example Plan", "expires_at": "2026-12-01 00:00:00", "features": [ { "feature": "Company API — 120 per minute / 20,000 per day", "enabled": true } ] }, "usage": [ { "name": "API requests today", "used": 1240, "limit": 20000 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.auth" ] } }, "/merchants": { "get": { "operationId": "listCompanyMerchants", "tags": [ "Merchants" ], "summary": "List your merchants", "x-summary-ar": "قائمة تجّارك", "description": "Your merchants with their pickup locations, ordered by id. Paginated: the answer has `meta`.", "x-description-ar": "تجّارك مع أماكن الاستلام لديهم، مرتّبين حسب المعرّف. الرد مرقّم ويتضمن `meta`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "q", "in": "query", "description": "Part of the business name or of the mobile number.", "x-description-ar": "جزء من الاسم التجاري أو من رقم الجوال.", "schema": { "type": "string" }, "example": "Example" }, { "name": "per_page", "in": "query", "description": "Page size, from 1 to 100 (default 50). A value outside the range is not rejected: it is clamped to the nearest limit and the effective value comes back in `meta.per_page`.", "x-description-ar": "حجم الصفحة من 1 إلى 100 (الافتراضي 50). القيمة خارج المجال لا تُرفض بل تُقرَّب إلى أقرب حدّ، وتعود القيمة الفعلية في `meta.per_page`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "A page of merchants.", "x-description-ar": "صفحة من التجّار.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Merchant" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "success", "data", "meta" ] }, "example": { "success": true, "data": [ { "id": 41, "business_name": "Example Shop", "contact_name": "Example Name", "phone": "0900000000", "email": "shop@example.com", "active": true, "pickup_locations": [ { "id": 7, "name": "Main branch", "address": "Example street, building 1", "phone": "0900000000", "default_shop": 1, "default": true } ] } ], "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.pagination" ] } }, "/deliverymen": { "get": { "operationId": "listCompanyCouriers", "tags": [ "Couriers" ], "summary": "List your couriers", "x-summary-ar": "قائمة مناديبك", "description": "All your couriers with their current load. The list is not paginated.", "x-description-ar": "كل مناديبك مع حمولتهم الحالية. القائمة غير مرقّمة.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Your couriers.", "x-description-ar": "مناديبك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Courier" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 5, "name": "Example Courier", "phone": "0900000001", "active": true, "open_parcels": 12, "parcel_limit": 50, "online": true, "available": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api" ] } }, "/parcels": { "get": { "operationId": "listCompanyParcels", "tags": [ "Parcels" ], "summary": "List your parcels", "x-summary-ar": "عرض طرودك", "description": "Lists the parcels of your company, newest first (by id), without `events`. Paginated: the answer has `meta`.", "x-description-ar": "تعرض طرود شركتك الأحدث أولاً (حسب المعرّف) دون `events`. الرد مرقّم ويتضمن `meta`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "merchant_id", "in": "query", "description": "Only the parcels of this merchant.", "x-description-ar": "طرود هذا التاجر فقط.", "schema": { "type": "integer" }, "example": 41 }, { "name": "deliveryman_id", "in": "query", "description": "Only the parcels held by this courier.", "x-description-ar": "الطرود التي يحملها هذا المندوب فقط.", "schema": { "type": "integer" }, "example": 5 }, { "name": "reference", "in": "query", "description": "Exact match on the merchant's reference.", "x-description-ar": "تطابق تام مع مرجع التاجر.", "schema": { "type": "string" }, "example": "ORDER-1043" }, { "name": "from", "in": "query", "description": "First creation day, `YYYY-MM-DD`, inclusive. The format is not validated: use only this one.", "x-description-ar": "أول يوم إنشاء `YYYY-MM-DD` شاملاً. لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "description": "Last creation day, `YYYY-MM-DD`, inclusive. The format is not validated: use only this one.", "x-description-ar": "آخر يوم إنشاء `YYYY-MM-DD` شاملاً. لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "updated_since", "in": "query", "description": "Only parcels updated at or after this time, `YYYY-MM-DD HH:MM:SS`. Useful for periodic synchronisation.", "x-description-ar": "الطرود المحدَّثة في هذا الوقت أو بعده فقط، بصيغة `YYYY-MM-DD HH:MM:SS`. مفيد للمزامنة الدورية.", "schema": { "type": "string" }, "example": "2026-01-01 10:00:00" }, { "name": "stage", "in": "query", "description": "Filter by stage. Unlike the merchant API an unknown value is rejected with `422 validation_failed`. `processing` matches only the status codes 2, 3, 4, 5, 6 and 19, so some parcels whose `stage` is `processing` are not returned by this filter. `awaiting_funds` is not accepted.", "x-description-ar": "تصفية حسب المرحلة. وعلى خلاف واجهة التاجر تُرفض القيمة المجهولة بالرمز `422 validation_failed`. تطابق `processing` رموز الحالة 2 و3 و4 و5 و6 و19 فقط، فبعض الطرود التي مرحلتها `processing` لا يعيدها هذا الفلتر. و`awaiting_funds` غير مقبولة.", "schema": { "type": "string", "enum": [ "pending", "processing", "out_for_delivery", "delivered", "partially_delivered", "returning", "returned" ] }, "example": "processing" }, { "name": "per_page", "in": "query", "description": "Page size, from 1 to 100 (default 20). A value outside the range is not rejected: it is clamped to the nearest limit and the effective value comes back in `meta.per_page`.", "x-description-ar": "حجم الصفحة من 1 إلى 100 (الافتراضي 20). القيمة خارج المجال لا تُرفض بل تُقرَّب إلى أقرب حدّ، وتعود القيمة الفعلية في `meta.per_page`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "A page of parcels.", "x-description-ar": "صفحة من الطرود.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "success", "data", "meta" ] }, "example": { "success": true, "data": [ { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } ], "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`validation_failed`: unknown `stage`. The message lists the available values; there is no `fields` object.", "x-description-ar": "`validation_failed`: قيمة `stage` مجهولة. تسرد الرسالة القيم المتاحة؛ ولا يوجد كائن `fields`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_failed": { "summary": "Unknown stage", "value": { "success": false, "error": { "code": "validation_failed", "message": "stage is unknown. Available: pending، processing، out_for_delivery، delivered، partially_delivered، returning، returned" } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.pagination" ] }, "post": { "operationId": "createCompanyParcel", "tags": [ "Parcels" ], "summary": "Create a parcel for one of your merchants", "x-summary-ar": "إنشاء طرد لأحد تجّارك", "description": "Creates a parcel on behalf of one of your merchants. The fee uses your company's pricing; nothing is taken from platform wallets. The same `reference` for the same merchant gives `409 duplicate_reference` whatever the status of the earlier parcel (treat it as \"already created\"); without a `reference` every call creates a new parcel. The governorate or the coordinates are required according to your company's pricing mode.", "x-description-ar": "تنشئ طرداً نيابةً عن أحد تجّارك. تستخدم الأجرة تسعير شركتك ولا يُؤخذ شيء من محافظ المنصة. المرجع `reference` نفسه للتاجر نفسه يعطي `409 duplicate_reference` أياً كانت حالة الطرد السابق (اعتبره «أُنشئ من قبل»)؛ وبلا `reference` ينشئ كل استدعاء طرداً جديداً. ويلزم إرسال المحافظة أو الإحداثيات بحسب آلية التسعير لدى شركتك.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParcelRequest" }, "example": { "merchant_id": 41, "reference": "ORDER-1043", "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1" }, "cod_amount": 25, "weight": 1 } } } }, "responses": { "201": { "description": "The parcel was created.", "x-description-ar": "تم إنشاء الطرد.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "processing", "status_code": 5, "status_label": "Received Warehouse", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": null } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "description": "`insufficient_balance`: the balance is not enough for the parcel fee. `subscription_expired`: your company subscription has ended.", "x-description-ar": "`insufficient_balance`: الرصيد لا يكفي لأجرة الطرد. `subscription_expired`: انتهى اشتراك شركتك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient_balance": { "summary": "Balance too low", "value": { "success": false, "error": { "code": "insufficient_balance", "message": "Insufficient wallet balance. Required: 7.00, available: 2.00" } } }, "subscription_expired": { "summary": "Subscription ended", "value": { "success": false, "error": { "code": "subscription_expired", "message": "Company subscription expired — renew the subscription from the company dashboard." } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`duplicate_reference`: the merchant already has a parcel with this `reference`. Fetch it with `GET /parcels?merchant_id=&reference=` (a bare `GET /parcels/{reference}` searches all your merchants).", "x-description-ar": "`duplicate_reference`: لدى التاجر طرد بالمرجع `reference` نفسه. اجلبه بـ `GET /parcels?merchant_id=&reference=` (أما `GET /parcels/{reference}` وحده فيبحث بين كل تجّارك).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "duplicate_reference": { "summary": "Reference already used", "value": { "success": false, "error": { "code": "duplicate_reference", "message": "A parcel with the same reference already exists for this merchant — use GET /parcels/ORDER-1043." } } } } } } }, "422": { "description": "`validation_failed`: `merchant_id` missing or not a merchant of your company (the error is on the field `merchant_id`), or another field is missing or wrong. `carrier_error`: the carrier could not process the parcel.", "x-description-ar": "`validation_failed`: `merchant_id` مفقود أو ليس تاجراً لدى شركتك (الخطأ على الحقل `merchant_id`)، أو حقل آخر مفقود أو خاطئ. `carrier_error`: تعذّرت معالجة الطرد لدى شركة الشحن.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_failed": { "summary": "Unknown merchant", "value": { "success": false, "error": { "code": "validation_failed", "message": "merchant_id is required and must be a merchant of your company (GET /merchants).", "fields": { "merchant_id": [ "Merchant not found in your company." ] } } } }, "carrier_error": { "summary": "Carrier refused", "value": { "success": false, "error": { "code": "carrier_error", "message": "Localized message from the carrier." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300, "route": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.versioning" ] } }, "/parcels/{tracking}": { "get": { "operationId": "getCompanyParcel", "tags": [ "Parcels" ], "summary": "Get one parcel with its events", "x-summary-ar": "جلب طرد واحد مع أحداثه", "description": "Takes a tracking number or a `reference` and returns the parcel with `events` in time order.", "x-description-ar": "تأخذ رقم تتبع أو `reference` وتُرجع الطرد مع `events` بترتيب زمني.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "tracking", "in": "path", "required": true, "description": "A tracking number, or the `reference` the merchant sent (the newest match among the parcels of ALL your merchants wins, so two merchants that share a reference value can give you the other merchant's parcel: prefer the tracking number).", "x-description-ar": "رقم التتبع، أو `reference` الذي أرسله التاجر (يُعتمد أحدث تطابق بين طرود كل تجّارك، فإن تشارك تاجران قيمة المرجع نفسها قد تحصل على طرد التاجر الآخر: فضّل رقم التتبع).", "schema": { "type": "string" }, "example": "DS-000000" } ], "responses": { "200": { "description": "The parcel with its events.", "x-description-ar": "الطرد مع أحداثه.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/ParcelWithEvents" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" }, "events": [ { "status_code": 1, "stage": "pending", "status_label": "Pending", "note": "Parcel created (api)", "at": "2026-01-01T10:00:00+00:00" }, { "status_code": 5, "stage": "processing", "status_label": "Received Warehouse", "note": null, "at": "2026-01-01T10:00:01+00:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no parcel with this tracking number or reference at your company.", "x-description-ar": "`not_found`: لا يوجد طرد بهذا الرقم أو المرجع لدى شركتك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "Unknown parcel", "value": { "success": false, "error": { "code": "not_found", "message": "No parcel with this number in your company." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api" ] } }, "/parcels/{tracking}/assign": { "post": { "operationId": "assignCompanyParcelCourier", "tags": [ "Parcels" ], "summary": "Assign a courier", "x-summary-ar": "تعيين مندوب", "description": "Assigns a courier of your company. Assign parcels that are at the warehouse or hub (status Received Warehouse or Received by hub) or already assigned. A parcel already with that courier (status Delivery Man Assign or Delivery Re-Schedule) is returned unchanged. A parcel whose status has no transition to Delivery Man Assign, such as a pending one or one still in pickup, is refused by the workflow and the API answers `500 server_error`: check `status_code` first. If your company requires couriers to be online and this one is offline you get `422` on the field `delivery_man_id`.", "x-description-ar": "تعيّن مندوباً من مناديب شركتك. عيّن الطرود الموجودة في المستودع أو المركز (الحالة «مستلم في المستودع» أو «مستلم في المركز») أو المعيّنة أصلاً. والطرد الذي مع المندوب نفسه (الحالة «تعيين مندوب» أو «إعادة جدولة التسليم») يُرجع دون تغيير. والطرد الذي لا انتقال في حالته إلى «تعيين مندوب»، كالمعلّق أو الذي ما زال في الاستلام، يرفضه مسار العمل وتردّ الواجهة `500 server_error`: تحقق من `status_code` أولاً. وإذا كانت شركتك تشترط اتصال المناديب وهذا المندوب غير متصل تحصل على `422` على الحقل `delivery_man_id`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "tracking", "in": "path", "required": true, "description": "A tracking number, or the `reference` the merchant sent (the newest match among the parcels of ALL your merchants wins, so two merchants that share a reference value can give you the other merchant's parcel: prefer the tracking number).", "x-description-ar": "رقم التتبع، أو `reference` الذي أرسله التاجر (يُعتمد أحدث تطابق بين طرود كل تجّارك، فإن تشارك تاجران قيمة المرجع نفسها قد تحصل على طرد التاجر الآخر: فضّل رقم التتبع).", "schema": { "type": "string" }, "example": "DS-000000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRequest" }, "example": { "deliveryman_id": 5, "note": "Call before arriving", "force": false } } } }, "responses": { "200": { "description": "The parcel after the assignment.", "x-description-ar": "الطرد بعد التعيين.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no parcel with this number at your company.", "x-description-ar": "`not_found`: لا يوجد طرد بهذا الرقم لدى شركتك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "Unknown parcel", "value": { "success": false, "error": { "code": "not_found", "message": "No parcel with this number in your company." } } } } } } }, "409": { "description": "`deliveryman_full`: the courier already holds the maximum number of open parcels. Send `force: true` to go beyond the limit.", "x-description-ar": "`deliveryman_full`: يحمل المندوب أصلاً الحد الأقصى من الطرود المفتوحة. أرسل `force: true` لتجاوز الحد.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "deliveryman_full": { "summary": "Courier full", "value": { "success": false, "error": { "code": "deliveryman_full", "message": "The courier has reached the parcel limit (50 / 50 undelivered). Send force=true to bypass the limit." } } } } } } }, "422": { "description": "`validation_failed`: `deliveryman_id` missing or not one of your couriers (only `message`, no `fields`), or the courier is offline (field `delivery_man_id`).", "x-description-ar": "`validation_failed`: `deliveryman_id` مفقود أو ليس أحد مناديبك (الرسالة فقط دون `fields`)، أو المندوب غير متصل (الحقل `delivery_man_id`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_failed": { "summary": "Unknown courier", "value": { "success": false, "error": { "code": "validation_failed", "message": "deliveryman_id is required and must be a courier of your company (GET /deliverymen)." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.versioning" ] } }, "/parcels/{tracking}/status": { "post": { "operationId": "updateCompanyParcelStatus", "tags": [ "Parcels" ], "summary": "Update the status of a parcel", "x-summary-ar": "تحديث حالة طرد", "description": "Applies a status change through the parcel workflow: `received`, `deliver`, `partial`, `fail`, `reschedule` or `returned`. Parcels sent to an external shipping carrier cannot be changed here (`409 not_allowed`). A change the workflow does not allow, or a `collected` above the COD amount, gives `409 invalid_transition` with the reason in the message. Mark a parcel delivered only after assigning a courier.", "x-description-ar": "تطبّق تغيير حالة عبر مسار عمل الطرد: `received` أو `deliver` أو `partial` أو `fail` أو `reschedule` أو `returned`. والطرود المرسلة إلى شركة شحن خارجية لا يمكن تغييرها هنا (`409 not_allowed`). والتغيير الذي لا يسمح به مسار العمل، أو `collected` الأكبر من مبلغ التحصيل، يعطي `409 invalid_transition` مع السبب في الرسالة. لا تسجّل الطرد مسلَّماً قبل تعيين مندوب.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "tracking", "in": "path", "required": true, "description": "A tracking number, or the `reference` the merchant sent (the newest match among the parcels of ALL your merchants wins, so two merchants that share a reference value can give you the other merchant's parcel: prefer the tracking number).", "x-description-ar": "رقم التتبع، أو `reference` الذي أرسله التاجر (يُعتمد أحدث تطابق بين طرود كل تجّارك، فإن تشارك تاجران قيمة المرجع نفسها قد تحصل على طرد التاجر الآخر: فضّل رقم التتبع).", "schema": { "type": "string" }, "example": "DS-000000" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "example": { "action": "partial", "collected": 15, "note": "One item returned" } } } }, "responses": { "200": { "description": "The parcel after the change.", "x-description-ar": "الطرد بعد التغيير.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "delivered", "status_code": 9, "status_label": "Delivered", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 25, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionExpired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no parcel with this number at your company.", "x-description-ar": "`not_found`: لا يوجد طرد بهذا الرقم لدى شركتك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "Unknown parcel", "value": { "success": false, "error": { "code": "not_found", "message": "No parcel with this number in your company." } } } } } } }, "409": { "description": "`not_allowed`: the parcel is with an external carrier, which controls its status. `invalid_transition`: the action does not fit the current status, or `collected` is too high.", "x-description-ar": "`not_allowed`: الطرد لدى شركة شحن خارجية هي التي تتحكم بحالته. `invalid_transition`: الإجراء لا يناسب الحالة الحالية، أو `collected` أعلى من المسموح.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_allowed": { "summary": "External carrier", "value": { "success": false, "error": { "code": "not_allowed", "message": "This parcel is with an external shipping company — its status updates from them automatically." } } }, "invalid_transition": { "summary": "Wrong status", "value": { "success": false, "error": { "code": "invalid_transition", "message": "Localized text that names the action, the current status and the reason." } } } } } } }, "422": { "description": "`validation_failed`: unknown `action` (message only), or `partial` without a numeric `collected` (field `collected`).", "x-description-ar": "`validation_failed`: `action` مجهول (الرسالة فقط)، أو `partial` دون `collected` رقمي (الحقل `collected`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_failed": { "summary": "Missing collected amount", "value": { "success": false, "error": { "code": "validation_failed", "message": "Partial delivery requires collected (the amount collected).", "fields": { "collected": [ "Partial delivery requires collected (the amount collected)." ] } } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 300 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.company-api", "developers.versioning" ] } } }, "webhooks": { "parcel.created": { "post": { "operationId": "webhookParcelCreated", "tags": [ "Webhook events" ], "summary": "Parcel created", "x-summary-ar": "طرد جديد", "description": "A parcel was created for one of your merchants. A new parcel normally sends this and then `parcel.status_changed` (status 5). Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "أُنشئ طرد لأحد تجّارك. الطرد الجديد يرسل عادةً هذا الحدث ثم `parcel.status_changed` (الحالة 5). تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelCreated" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.created", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.status_changed": { "post": { "operationId": "webhookParcelStatusChanged", "tags": [ "Webhook events" ], "summary": "Parcel status changed", "x-summary-ar": "تغيّرت حالة الطرد", "description": "Any status change made through the parcel workflow. One change can send this and a stage event, each with its own event id. Not sent by the dedicated staff pickup and hub forms or by some undo forms: read the parcel when you need its current state. Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "أي تغيير في الحالة عبر مسار عمل الطرد. وقد يرسل التغيير الواحد هذا الحدث وحدث المرحلة، لكل منهما معرّف حدث خاص. لا يُرسل من نماذج الموظفين المخصصة للاستلام والمراكز ولا من بعض نماذج التراجع: اقرأ الطرد عندما تحتاج إلى حالته الحالية. تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelStatusChanged" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.status_changed", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.out_for_delivery": { "post": { "operationId": "webhookParcelOutForDelivery", "tags": [ "Webhook events" ], "summary": "Out for delivery", "x-summary-ar": "خرج للتوصيل", "description": "The parcel is with a courier (statuses 7 and 8). Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "الطرد مع المندوب (الحالتان 7 و8). تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelOutForDelivery" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.out_for_delivery", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.delivered": { "post": { "operationId": "webhookParcelDelivered", "tags": [ "Webhook events" ], "summary": "Delivered", "x-summary-ar": "تم التسليم", "description": "The parcel was delivered, fully or partially (statuses 9 and 32). `data.cod_collected` has the collected amount. Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "سُلِّم الطرد كاملاً أو جزئياً (الحالتان 9 و32). يتضمن `data.cod_collected` المبلغ المحصَّل. تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelDelivered" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.delivered", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.returning": { "post": { "operationId": "webhookParcelReturning", "tags": [ "Webhook events" ], "summary": "Returning", "x-summary-ar": "قيد الإرجاع", "description": "Delivery failed and the parcel is on its way back. Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "تعذّر التسليم والطرد في طريق العودة. تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelReturning" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.returning", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.returned": { "post": { "operationId": "webhookParcelReturned", "tags": [ "Webhook events" ], "summary": "Returned to the merchant", "x-summary-ar": "رُدّ للتاجر", "description": "The merchant received the returned parcel (statuses 30 and 13). Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "استلم التاجر الطرد المرتجع (الحالتان 30 و13). تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelReturned" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.returned", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.cancelled": { "post": { "operationId": "webhookParcelCancelled", "tags": [ "Webhook events" ], "summary": "Cancelled", "x-summary-ar": "أُلغي", "description": "The connected external carrier reported the parcel as cancelled. Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "أبلغت شركة الشحن الخارجية المربوطة بإلغاء الطرد. تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelCancelled" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.cancelled", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } }, "parcel.awaiting_funds": { "post": { "operationId": "webhookParcelAwaitingFunds", "tags": [ "Webhook events" ], "summary": "Awaiting funds", "x-summary-ar": "بانتظار الرصيد", "description": "The order was saved but the merchant's balance is too low. Sent to the webhook links you register in the company panel (Integrations and API, then Webhook), for the parcels of your company only; the `data` object is the company parcel object with `merchant` and `deliveryman`.", "x-description-ar": "حُفظ الطلب لكن رصيد التاجر لا يكفي. تُرسل إلى روابط الويب هوك التي تسجّلها في لوحة الشركة (الربط والـ API ثم Webhook) لطرود شركتك فقط؛ وكائن `data` هو كائن طرد الشركة مع `merchant` و`deliveryman`.", "parameters": [ { "$ref": "#/components/parameters/DsEvent" }, { "$ref": "#/components/parameters/DsEventId" }, { "$ref": "#/components/parameters/DsDelivery" }, { "$ref": "#/components/parameters/DsAttempt" }, { "$ref": "#/components/parameters/DsTimestamp" }, { "$ref": "#/components/parameters/DsSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventParcelAwaitingFunds" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "parcel.awaiting_funds", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": 1043, "tracking_number": "DS-000000", "reference": "ORDER-1043", "stage": "out_for_delivery", "status_code": 7, "status_label": "Delivery Man Assign", "company_id": 3, "company_name": "Example Delivery", "external_tracking_number": null, "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1", "lat": null, "lng": null }, "cod_amount": 25, "cod_collected": 0, "weight_kg": 1.5, "charges": { "delivery_fee": 6, "platform_fee": 1 }, "delivery_attempts": 0, "note": null, "tracking_url": "https://YOUR_DOMAIN/t/DS-000000", "created_at": "2026-01-01T10:00:00+00:00", "updated_at": "2026-01-01T12:10:00+00:00", "merchant": { "id": 41, "name": "Example Shop" }, "deliveryman": { "id": 5, "name": "Example Courier" } } } } } }, "responses": { "2XX": { "description": "Answer with any 2xx status within 10 seconds to confirm receipt. Anything else (including 3xx: redirects are not followed, a timeout or a connection error) counts as a failed attempt and is retried (8 attempts in all).", "x-description-ar": "ردّ بأي حالة 2xx خلال 10 ثوانٍ لتأكيد الاستلام. أي ردّ آخر (بما فيه 3xx لأن التحويلات لا تُتبع، أو انتهاء المهلة، أو خطأ الاتصال) يُحتسب محاولة فاشلة وتُعاد (8 محاولات إجمالاً)." } } } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "description": "The error envelope returned by every error raised by the API code itself.", "x-description-ar": "غلاف الخطأ الذي ترجعه كل الأخطاء الصادرة عن كود الـ API نفسه.", "properties": { "success": { "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Short snake_case code. Build your logic on this value, not on `message`.", "x-description-ar": "رمز قصير بصيغة snake_case. ابنِ منطق برنامجك على هذه القيمة لا على `message`.", "enum": [ "unauthenticated", "invalid_key", "account_inactive", "subscription_expired", "plan_feature", "rate_limited", "not_found", "duplicate_reference", "deliveryman_full", "not_allowed", "invalid_transition", "insufficient_balance", "validation_failed", "carrier_error", "server_error" ] }, "message": { "type": "string", "description": "Human-readable text in the request language (Arabic by default, English with `Accept-Language: en`). A few messages exist only in Arabic; never branch on the text.", "x-description-ar": "نص مقروء بلغة الطلب (العربية افتراضياً والإنجليزية مع `Accept-Language: en`). بعض الرسائل موجودة بالعربية فقط، فلا تبنِ منطقك على النص." }, "fields": { "type": "object", "description": "Present on most `validation_failed` errors: field name to a list of messages. Field names are the platform's internal ones (`customer_name`, `customer_phone`, `customer_address`, `customer_city`, `lat`, `long`, `shop_id` instead of `pickup_location_id`).", "x-description-ar": "يظهر في معظم أخطاء `validation_failed`: اسم الحقل ثم قائمة رسائله. أسماء الحقول هي الأسماء الداخلية للمنصة (`customer_name` و`customer_phone` و`customer_address` و`customer_city` و`lat` و`long` و`shop_id` بدل `pickup_location_id`).", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "retry_after": { "type": "integer", "description": "Seconds to wait. Present on `rate_limited`.", "x-description-ar": "عدد الثواني المطلوب انتظارها. يظهر مع `rate_limited`." }, "reference": { "type": "string", "description": "Support reference. Present on `server_error`.", "x-description-ar": "مرجع للدعم. يظهر مع `server_error`." }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status your endpoint answered with, or `null` when it did not answer. Present on `delivery_failed`.", "x-description-ar": "حالة HTTP التي ردّ بها نظامك، أو `null` إن لم يردّ. تظهر مع `delivery_failed`." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "ThrottleError": { "type": "object", "description": "Framework answer for the IP and route limits (a different shape from the error envelope).", "x-description-ar": "ردّ الإطار عند تجاوز حدود عنوان IP والمسار (بشكل مختلف عن غلاف الخطأ).", "properties": { "message": { "type": "string", "description": "Always English: `Too Many Attempts.`", "x-description-ar": "بالإنجليزية دائماً: `Too Many Attempts.`" } }, "required": [ "message" ] }, "Meta": { "type": "object", "description": "Pagination block. There are no links and no cursor.", "x-description-ar": "كتلة الترقيم. لا توجد روابط ولا مؤشر (cursor).", "properties": { "page": { "type": "integer", "description": "Current page.", "x-description-ar": "الصفحة الحالية." }, "per_page": { "type": "integer", "description": "Effective page size.", "x-description-ar": "حجم الصفحة الفعلي." }, "total": { "type": "integer", "description": "Number of records after the filters.", "x-description-ar": "عدد السجلات بعد تطبيق الفلاتر." }, "last_page": { "type": "integer", "description": "Number of pages (1 when there are no results).", "x-description-ar": "عدد الصفحات (1 عند عدم وجود نتائج)." } }, "required": [ "page", "per_page", "total", "last_page" ] }, "ParcelEvent": { "type": "object", "description": "One entry of the parcel history.", "x-description-ar": "عنصر واحد من تاريخ الطرد.", "properties": { "status_code": { "type": "integer", "description": "Exact internal status code of that step.", "x-description-ar": "رمز الحالة الداخلي الدقيق لتلك الخطوة." }, "stage": { "type": "string", "description": "Simplified stage of that step.", "x-description-ar": "المرحلة المبسطة لتلك الخطوة.", "enum": [ "pending", "processing", "out_for_delivery", "delivered", "partially_delivered", "returning", "returned" ] }, "status_label": { "type": "string", "description": "Status label in the request language.", "x-description-ar": "تسمية الحالة بلغة الطلب." }, "note": { "type": [ "string", "null" ], "description": "Free-text note recorded with the event.", "x-description-ar": "ملاحظة نصية مسجّلة مع الحدث." }, "at": { "type": [ "string", "null" ], "description": "Time of the event (ISO 8601 with a UTC offset).", "x-description-ar": "وقت الحدث (ISO 8601 مع فرق التوقيت عن UTC).", "format": "date-time" } }, "required": [ "status_code", "stage", "status_label", "note", "at" ] }, "Parcel": { "type": "object", "description": "A parcel as returned by the API and carried by webhooks (same fields every time).", "x-description-ar": "الطرد كما ترجعه الواجهة وكما تحمله رسائل الويب هوك (الحقول نفسها دائماً).", "properties": { "id": { "type": "integer", "description": "Parcel id.", "x-description-ar": "معرّف الطرد." }, "tracking_number": { "type": "string", "description": "Tracking number. Use it in `{tracking}` paths and on the public tracking page.", "x-description-ar": "رقم التتبع. استخدمه في مسارات `{tracking}` وفي صفحة التتبع العامة." }, "reference": { "type": [ "string", "null" ], "description": "Your own reference (order number) sent at creation.", "x-description-ar": "مرجعك الخاص (رقم الطلب) المرسل عند الإنشاء." }, "stage": { "type": "string", "description": "Simplified, stable state. Prefer it to `status_code` in your logic: `awaiting_funds` (saved, waiting for the wallet balance), `pending` (status 1), `out_for_delivery` (7, 8), `delivered` (9), `partially_delivered` (32), `returning` (11, 12, 24, 26, 27), `returned` (13, 30) and `processing` (every other status).", "x-description-ar": "حالة مبسطة وثابتة. يفضّل الاعتماد عليها بدل `status_code` في منطق برنامجك: `awaiting_funds` (محفوظ بانتظار رصيد المحفظة)، و`pending` (الحالة 1)، و`out_for_delivery` (7 و8)، و`delivered` (9)، و`partially_delivered` (32)، و`returning` (11 و12 و24 و26 و27)، و`returned` (13 و30)، و`processing` (كل حالة أخرى).", "enum": [ "pending", "processing", "out_for_delivery", "delivered", "partially_delivered", "returning", "returned", "awaiting_funds" ] }, "status_code": { "type": "integer", "description": "Exact internal status code (for example 1 Pending, 5 Received Warehouse, 7 Delivery Man Assign, 9 Delivered, 13 Returned Merchant, 32 Partial Delivered).", "x-description-ar": "رمز الحالة الداخلي الدقيق (مثلاً 1 معلّق، 5 مستلم في المستودع، 7 تعيين مندوب، 9 تم التسليم، 13 رُدّ للتاجر، 32 تسليم جزئي)." }, "status_label": { "type": "string", "description": "Label of the status in the request language.", "x-description-ar": "تسمية الحالة بلغة الطلب." }, "company_id": { "type": "integer", "description": "Delivery company or carrier that handles the parcel.", "x-description-ar": "شركة التوصيل أو الشحن التي تتولى الطرد." }, "company_name": { "type": [ "string", "null" ], "description": "Name of that company.", "x-description-ar": "اسم تلك الشركة." }, "external_tracking_number": { "type": [ "string", "null" ], "description": "Tracking number at the external shipping carrier, when the parcel was sent to one.", "x-description-ar": "رقم التتبع لدى شركة الشحن الخارجية إن أُرسل الطرد إليها." }, "recipient": { "type": "object", "description": "The recipient of the parcel.", "x-description-ar": "مستلم الطرد.", "properties": { "name": { "type": [ "string", "null" ], "description": "Recipient name.", "x-description-ar": "اسم المستلم." }, "phone": { "type": [ "string", "null" ], "description": "Recipient phone.", "x-description-ar": "هاتف المستلم." }, "governorate": { "type": [ "string", "null" ], "description": "Recipient governorate.", "x-description-ar": "محافظة المستلم." }, "address": { "type": [ "string", "null" ], "description": "Recipient address.", "x-description-ar": "عنوان المستلم." }, "lat": { "type": [ "number", "null" ], "description": "Latitude of the recipient.", "x-description-ar": "خط عرض موقع المستلم." }, "lng": { "type": [ "number", "null" ], "description": "Longitude of the recipient.", "x-description-ar": "خط طول موقع المستلم." } }, "required": [ "name", "phone", "governorate", "address", "lat", "lng" ] }, "cod_amount": { "type": "number", "description": "Cash-on-delivery amount to collect, always in US dollars.", "x-description-ar": "مبلغ التحصيل عند الاستلام، بالدولار الأمريكي دائماً." }, "cod_collected": { "type": "number", "description": "Amount collected so far, in US dollars (the collected amount for a partial delivery).", "x-description-ar": "المبلغ المحصَّل حتى الآن بالدولار (المبلغ المحصَّل عند التسليم الجزئي)." }, "weight_kg": { "type": [ "number", "null" ], "description": "Parcel weight in kilograms.", "x-description-ar": "وزن الطرد بالكيلوغرام." }, "charges": { "type": "object", "description": "Fees of the parcel.", "x-description-ar": "رسوم الطرد.", "properties": { "delivery_fee": { "type": "number", "description": "Delivery fee in US dollars (the carrier cost for a carrier parcel).", "x-description-ar": "أجرة التوصيل بالدولار (تكلفة شركة الشحن لطرد الشحن)." }, "platform_fee": { "type": "number", "description": "Platform fee in US dollars.", "x-description-ar": "رسم المنصة بالدولار." } }, "required": [ "delivery_fee", "platform_fee" ] }, "delivery_attempts": { "type": "integer", "description": "Number of delivery attempts.", "x-description-ar": "عدد محاولات التسليم." }, "note": { "type": [ "string", "null" ], "description": "Note sent with the parcel.", "x-description-ar": "الملاحظة المرسلة مع الطرد." }, "tracking_url": { "type": "string", "description": "Public tracking page of the parcel.", "x-description-ar": "صفحة التتبع العامة للطرد.", "format": "uri" }, "created_at": { "type": [ "string", "null" ], "description": "Creation time (ISO 8601 with a UTC offset).", "x-description-ar": "وقت الإنشاء (ISO 8601 مع فرق التوقيت عن UTC).", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "description": "Last update time (ISO 8601 with a UTC offset).", "x-description-ar": "وقت آخر تحديث (ISO 8601 مع فرق التوقيت عن UTC).", "format": "date-time" }, "merchant": { "type": [ "object", "null" ], "description": "The merchant that owns the parcel.", "x-description-ar": "التاجر صاحب الطرد.", "properties": { "id": { "type": "integer", "description": "Merchant id.", "x-description-ar": "معرّف التاجر." }, "name": { "type": [ "string", "null" ], "description": "Business name of the merchant.", "x-description-ar": "الاسم التجاري للتاجر." } }, "required": [ "id", "name" ] }, "deliveryman": { "type": [ "object", "null" ], "description": "The courier holding the parcel, or null when none does.", "x-description-ar": "المندوب الذي يحمل الطرد، أو null إن لم يكن لدى أحد.", "properties": { "id": { "type": "integer", "description": "Courier id.", "x-description-ar": "معرّف المندوب." }, "name": { "type": [ "string", "null" ], "description": "Courier name.", "x-description-ar": "اسم المندوب." } }, "required": [ "id", "name" ] } }, "required": [ "id", "tracking_number", "reference", "stage", "status_code", "status_label", "company_id", "company_name", "external_tracking_number", "recipient", "cod_amount", "cod_collected", "weight_kg", "charges", "delivery_attempts", "note", "tracking_url", "created_at", "updated_at", "merchant", "deliveryman" ] }, "ParcelWithEvents": { "type": "object", "description": "The parcel object plus its history (`events`). Returned when one parcel is fetched.", "x-description-ar": "كائن الطرد مع تاريخه (`events`). يُرجَع عند جلب طرد واحد.", "properties": { "id": { "type": "integer", "description": "Parcel id.", "x-description-ar": "معرّف الطرد." }, "tracking_number": { "type": "string", "description": "Tracking number. Use it in `{tracking}` paths and on the public tracking page.", "x-description-ar": "رقم التتبع. استخدمه في مسارات `{tracking}` وفي صفحة التتبع العامة." }, "reference": { "type": [ "string", "null" ], "description": "Your own reference (order number) sent at creation.", "x-description-ar": "مرجعك الخاص (رقم الطلب) المرسل عند الإنشاء." }, "stage": { "type": "string", "description": "Simplified, stable state. Prefer it to `status_code` in your logic: `awaiting_funds` (saved, waiting for the wallet balance), `pending` (status 1), `out_for_delivery` (7, 8), `delivered` (9), `partially_delivered` (32), `returning` (11, 12, 24, 26, 27), `returned` (13, 30) and `processing` (every other status).", "x-description-ar": "حالة مبسطة وثابتة. يفضّل الاعتماد عليها بدل `status_code` في منطق برنامجك: `awaiting_funds` (محفوظ بانتظار رصيد المحفظة)، و`pending` (الحالة 1)، و`out_for_delivery` (7 و8)، و`delivered` (9)، و`partially_delivered` (32)، و`returning` (11 و12 و24 و26 و27)، و`returned` (13 و30)، و`processing` (كل حالة أخرى).", "enum": [ "pending", "processing", "out_for_delivery", "delivered", "partially_delivered", "returning", "returned", "awaiting_funds" ] }, "status_code": { "type": "integer", "description": "Exact internal status code (for example 1 Pending, 5 Received Warehouse, 7 Delivery Man Assign, 9 Delivered, 13 Returned Merchant, 32 Partial Delivered).", "x-description-ar": "رمز الحالة الداخلي الدقيق (مثلاً 1 معلّق، 5 مستلم في المستودع، 7 تعيين مندوب، 9 تم التسليم، 13 رُدّ للتاجر، 32 تسليم جزئي)." }, "status_label": { "type": "string", "description": "Label of the status in the request language.", "x-description-ar": "تسمية الحالة بلغة الطلب." }, "company_id": { "type": "integer", "description": "Delivery company or carrier that handles the parcel.", "x-description-ar": "شركة التوصيل أو الشحن التي تتولى الطرد." }, "company_name": { "type": [ "string", "null" ], "description": "Name of that company.", "x-description-ar": "اسم تلك الشركة." }, "external_tracking_number": { "type": [ "string", "null" ], "description": "Tracking number at the external shipping carrier, when the parcel was sent to one.", "x-description-ar": "رقم التتبع لدى شركة الشحن الخارجية إن أُرسل الطرد إليها." }, "recipient": { "type": "object", "description": "The recipient of the parcel.", "x-description-ar": "مستلم الطرد.", "properties": { "name": { "type": [ "string", "null" ], "description": "Recipient name.", "x-description-ar": "اسم المستلم." }, "phone": { "type": [ "string", "null" ], "description": "Recipient phone.", "x-description-ar": "هاتف المستلم." }, "governorate": { "type": [ "string", "null" ], "description": "Recipient governorate.", "x-description-ar": "محافظة المستلم." }, "address": { "type": [ "string", "null" ], "description": "Recipient address.", "x-description-ar": "عنوان المستلم." }, "lat": { "type": [ "number", "null" ], "description": "Latitude of the recipient.", "x-description-ar": "خط عرض موقع المستلم." }, "lng": { "type": [ "number", "null" ], "description": "Longitude of the recipient.", "x-description-ar": "خط طول موقع المستلم." } }, "required": [ "name", "phone", "governorate", "address", "lat", "lng" ] }, "cod_amount": { "type": "number", "description": "Cash-on-delivery amount to collect, always in US dollars.", "x-description-ar": "مبلغ التحصيل عند الاستلام، بالدولار الأمريكي دائماً." }, "cod_collected": { "type": "number", "description": "Amount collected so far, in US dollars (the collected amount for a partial delivery).", "x-description-ar": "المبلغ المحصَّل حتى الآن بالدولار (المبلغ المحصَّل عند التسليم الجزئي)." }, "weight_kg": { "type": [ "number", "null" ], "description": "Parcel weight in kilograms.", "x-description-ar": "وزن الطرد بالكيلوغرام." }, "charges": { "type": "object", "description": "Fees of the parcel.", "x-description-ar": "رسوم الطرد.", "properties": { "delivery_fee": { "type": "number", "description": "Delivery fee in US dollars (the carrier cost for a carrier parcel).", "x-description-ar": "أجرة التوصيل بالدولار (تكلفة شركة الشحن لطرد الشحن)." }, "platform_fee": { "type": "number", "description": "Platform fee in US dollars.", "x-description-ar": "رسم المنصة بالدولار." } }, "required": [ "delivery_fee", "platform_fee" ] }, "delivery_attempts": { "type": "integer", "description": "Number of delivery attempts.", "x-description-ar": "عدد محاولات التسليم." }, "note": { "type": [ "string", "null" ], "description": "Note sent with the parcel.", "x-description-ar": "الملاحظة المرسلة مع الطرد." }, "tracking_url": { "type": "string", "description": "Public tracking page of the parcel.", "x-description-ar": "صفحة التتبع العامة للطرد.", "format": "uri" }, "created_at": { "type": [ "string", "null" ], "description": "Creation time (ISO 8601 with a UTC offset).", "x-description-ar": "وقت الإنشاء (ISO 8601 مع فرق التوقيت عن UTC).", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "description": "Last update time (ISO 8601 with a UTC offset).", "x-description-ar": "وقت آخر تحديث (ISO 8601 مع فرق التوقيت عن UTC).", "format": "date-time" }, "merchant": { "type": [ "object", "null" ], "description": "The merchant that owns the parcel.", "x-description-ar": "التاجر صاحب الطرد.", "properties": { "id": { "type": "integer", "description": "Merchant id.", "x-description-ar": "معرّف التاجر." }, "name": { "type": [ "string", "null" ], "description": "Business name of the merchant.", "x-description-ar": "الاسم التجاري للتاجر." } }, "required": [ "id", "name" ] }, "deliveryman": { "type": [ "object", "null" ], "description": "The courier holding the parcel, or null when none does.", "x-description-ar": "المندوب الذي يحمل الطرد، أو null إن لم يكن لدى أحد.", "properties": { "id": { "type": "integer", "description": "Courier id.", "x-description-ar": "معرّف المندوب." }, "name": { "type": [ "string", "null" ], "description": "Courier name.", "x-description-ar": "اسم المندوب." } }, "required": [ "id", "name" ] }, "events": { "type": "array", "description": "History of the parcel in time order. Present only when one parcel is fetched.", "x-description-ar": "تاريخ الطرد بترتيب زمني. يظهر فقط عند جلب طرد واحد.", "items": { "$ref": "#/components/schemas/ParcelEvent" } } }, "required": [ "id", "tracking_number", "reference", "stage", "status_code", "status_label", "company_id", "company_name", "external_tracking_number", "recipient", "cod_amount", "cod_collected", "weight_kg", "charges", "delivery_attempts", "note", "tracking_url", "created_at", "updated_at", "merchant", "deliveryman", "events" ], "x-extends": "Parcel" }, "Account": { "type": "object", "description": "Your company account.", "x-description-ar": "حساب شركتك.", "properties": { "company": { "type": "object", "description": "Your company.", "x-description-ar": "شركتك.", "properties": { "id": { "type": "integer", "description": "Company id.", "x-description-ar": "معرّف الشركة." }, "name": { "type": [ "string", "null" ], "description": "Company name.", "x-description-ar": "اسم الشركة." }, "phone": { "type": [ "string", "null" ], "description": "Company phone.", "x-description-ar": "هاتف الشركة." } }, "required": [ "id", "name", "phone" ] }, "plan": { "type": [ "object", "null" ], "description": "Active subscription, or null when there is none.", "x-description-ar": "الاشتراك الفعّال، أو null إن لم يوجد.", "properties": { "name": { "type": [ "string", "null" ], "description": "Plan name.", "x-description-ar": "اسم الباقة." }, "expires_at": { "type": "string", "description": "Subscription expiry (`YYYY-MM-DD HH:MM:SS`).", "x-description-ar": "انتهاء الاشتراك (`YYYY-MM-DD HH:MM:SS`)." }, "features": { "type": "array", "description": "Plan features.", "x-description-ar": "ميزات الباقة.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Display label in the request language (it can include the limits, such as the API per-minute and per-day figures).", "x-description-ar": "تسمية للعرض بلغة الطلب (وقد تتضمن الحدود مثل أرقام الـ API في الدقيقة وفي اليوم)." }, "enabled": { "type": "boolean", "description": "Whether the plan includes it.", "x-description-ar": "هل تتضمنها الباقة." } }, "required": [ "feature", "enabled" ] } } }, "required": [ "name", "expires_at", "features" ] }, "usage": { "type": "array", "description": "Usage against the plan limits.", "x-description-ar": "الاستهلاك مقابل حدود الباقة.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What is counted, in the request language (for example API requests today, webhook URLs, merchants).", "x-description-ar": "ما يُعدّ، بلغة الطلب (مثل طلبات الـ API اليوم وروابط الويب هوك والتجّار)." }, "used": { "type": "integer", "description": "Amount used.", "x-description-ar": "الكمية المستعملة." }, "limit": { "type": [ "integer", "null" ], "description": "The limit, or null when unlimited.", "x-description-ar": "الحدّ، أو null عند عدم وجود حد." } }, "required": [ "name", "used", "limit" ] } } }, "required": [ "company", "plan", "usage" ] }, "Merchant": { "type": "object", "description": "One of your merchants.", "x-description-ar": "أحد تجّارك.", "properties": { "id": { "type": "integer", "description": "Send it as `merchant_id` when you create a parcel.", "x-description-ar": "أرسله على أنه `merchant_id` عند إنشاء طرد." }, "business_name": { "type": "string", "description": "Business name.", "x-description-ar": "الاسم التجاري." }, "contact_name": { "type": [ "string", "null" ], "description": "Contact person.", "x-description-ar": "الشخص المسؤول." }, "phone": { "type": [ "string", "null" ], "description": "Mobile number.", "x-description-ar": "رقم الجوال." }, "email": { "type": [ "string", "null" ], "description": "Email address.", "x-description-ar": "البريد الإلكتروني." }, "active": { "type": "boolean", "description": "Whether the merchant is active.", "x-description-ar": "هل التاجر فعّال." }, "pickup_locations": { "type": "array", "description": "The merchant's pickup locations.", "x-description-ar": "أماكن الاستلام لدى التاجر.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Send it as `pickup_location_id`.", "x-description-ar": "أرسله على أنه `pickup_location_id`." }, "name": { "type": [ "string", "null" ], "description": "Location name.", "x-description-ar": "اسم المكان." }, "address": { "type": [ "string", "null" ], "description": "Address.", "x-description-ar": "العنوان." }, "phone": { "type": [ "string", "null" ], "description": "Contact phone.", "x-description-ar": "هاتف التواصل." }, "default_shop": { "type": "integer", "description": "Default flag as 0 or 1 (same meaning as `default`).", "x-description-ar": "علامة الافتراضي بالقيمة 0 أو 1 (بالمعنى نفسه لـ `default`).", "enum": [ 0, 1 ] }, "default": { "type": "boolean", "description": "True for the merchant's default location.", "x-description-ar": "تكون true لمكان الاستلام الافتراضي للتاجر." } }, "required": [ "id", "name", "address", "phone", "default_shop", "default" ] } } }, "required": [ "id", "business_name", "contact_name", "phone", "email", "active", "pickup_locations" ] }, "Courier": { "type": "object", "description": "One of your couriers (deliverymen).", "x-description-ar": "أحد مناديبك.", "properties": { "id": { "type": "integer", "description": "Send it as `deliveryman_id`.", "x-description-ar": "أرسله على أنه `deliveryman_id`." }, "name": { "type": [ "string", "null" ], "description": "Courier name.", "x-description-ar": "اسم المندوب." }, "phone": { "type": [ "string", "null" ], "description": "Courier mobile number.", "x-description-ar": "رقم جوال المندوب." }, "active": { "type": "boolean", "description": "Whether the courier account is active.", "x-description-ar": "هل حساب المندوب فعّال." }, "open_parcels": { "type": "integer", "description": "Parcels in status Delivery Man Assign or Delivery Re-Schedule that have an event for this courier: an approximation of what the courier holds (the assign dialog in the panel counts the same way).", "x-description-ar": "الطرود في الحالتين «تعيين مندوب» و«إعادة جدولة التسليم» التي لها حدث لهذا المندوب: تقدير لما يحمله المندوب (ويعدّ مربع التعيين في اللوحة بالطريقة نفسها)." }, "parcel_limit": { "type": "integer", "description": "The courier's parcel limit (5 when none is set).", "x-description-ar": "حدّ طرود المندوب (5 عند عدم ضبط حد)." }, "online": { "type": "boolean", "description": "The courier's duty flag (connected to the app).", "x-description-ar": "علامة دوام المندوب (متصل بالتطبيق)." }, "available": { "type": "boolean", "description": "False when the courier is not active, or when your company requires couriers to be online and this one is not.", "x-description-ar": "تكون false إذا كان المندوب غير فعّال، أو إذا كانت شركتك تشترط اتصال المناديب وهذا المندوب غير متصل." } }, "required": [ "id", "name", "phone", "active", "open_parcels", "parcel_limit", "online", "available" ] }, "CreateParcelRequest": { "type": "object", "description": "Fields of the parcel. The fee is calculated with your company's pricing. Nothing is taken from platform wallets: it is deducted from the merchant's balance with your company only when the merchant's delivery-fee setting is \"from their balance in advance\". The other fields follow the same rules as in the merchant API (`company_id`, `use_own_account`, `warehouse_items` and `wait_for_balance` are not supported: the parcel belongs to your company).", "x-description-ar": "حقول الطرد. تُحسب الأجرة بتسعير شركتك. ولا يُؤخذ شيء من محافظ المنصة: تُخصم من رصيد التاجر لدى شركتك فقط عندما يكون إعداد أجرة التوصيل للتاجر «من رصيده مقدماً». وباقي الحقول بالقواعد نفسها في واجهة التاجر (ولا يدعم هذا المسار `company_id` و`use_own_account` و`warehouse_items` و`wait_for_balance`: فالطرد يتبع شركتك).", "properties": { "merchant_id": { "type": "integer", "description": "The merchant the parcel is created for: an `id` from `GET /merchants`. It must be a merchant of your company.", "x-description-ar": "التاجر الذي يُنشأ الطرد له: قيمة `id` من `GET /merchants`. يجب أن يكون تاجراً لدى شركتك." }, "recipient": { "type": "object", "description": "The recipient. Each field may instead be sent flat at the top level (`customer_name`, `customer_phone`, `customer_address`, `customer_city`, `lat`, `long`); the nested form is the documented one.", "x-description-ar": "المستلم. يمكن بدلاً من ذلك إرسال كل حقل مسطحاً في المستوى الأعلى (`customer_name` و`customer_phone` و`customer_address` و`customer_city` و`lat` و`long`)؛ والشكل المتداخل هو الموثَّق.", "properties": { "name": { "type": "string", "description": "Recipient name.", "x-description-ar": "اسم المستلم.", "maxLength": 191, "x-internal-field": "customer_name" }, "phone": { "type": "string", "description": "Recipient phone number: digits, spaces, `+`, `-` and parentheses, 6 to 30 characters.", "x-description-ar": "رقم هاتف المستلم: أرقام ومسافات و`+` و`-` وأقواس، من 6 إلى 30 محرفاً.", "maxLength": 30, "pattern": "^[+0-9\\s\\-()]{6,30}$", "x-internal-field": "customer_phone" }, "address": { "type": "string", "description": "Recipient address.", "x-description-ar": "عنوان المستلم.", "maxLength": 1000, "x-internal-field": "customer_address" }, "governorate": { "type": "string", "description": "Governorate name (English `name` or Arabic `name_ar` from `GET /governorates`). If you send the id, send it as a string such as `\"3\"`: a JSON number is rejected. Needed for governorate pricing; otherwise the platform tries to find it from the address, then from the coordinates.", "x-description-ar": "اسم المحافظة (`name` بالإنجليزية أو `name_ar` بالعربية من `GET /governorates`). وإن أرسلت المعرّف فأرسله نصاً مثل `\"3\"` لأن الرقم في JSON يُرفض. مطلوب للتسعير حسب المحافظة، وإلا تحاول المنصة استنتاجها من العنوان ثم من الإحداثيات.", "maxLength": 120, "x-internal-field": "customer_city", "x-aliases": [ "customer_city", "city" ] }, "lat": { "type": "number", "description": "Recipient latitude. Required for distance pricing (`per_km`, `km_kg`).", "x-description-ar": "خط عرض موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`).", "minimum": -90, "maximum": 90, "x-internal-field": "lat" }, "lng": { "type": "number", "description": "Recipient longitude. Required for distance pricing (`per_km`, `km_kg`).", "x-description-ar": "خط طول موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`).", "minimum": -180, "maximum": 180, "x-internal-field": "long", "x-aliases": [ "long" ] } }, "required": [ "name", "phone", "address" ] }, "reference": { "type": "string", "description": "The merchant's own reference (order number), up to 191 characters. A reference the merchant already used gives `409 duplicate_reference`; unlike the merchant API the old parcel is not returned.", "x-description-ar": "مرجع التاجر الخاص (رقم الطلب) بحد أقصى 191 محرفاً. المرجع الذي استخدمه التاجر من قبل يعطي `409 duplicate_reference`؛ وعلى خلاف واجهة التاجر لا يُرجَع الطرد القديم.", "maxLength": 191, "x-internal-field": "invoice_no", "x-aliases": [ "invoice_no" ] }, "cod_amount": { "type": "number", "description": "Cash-on-delivery amount the recipient pays, from 0 to 100,000,000 US dollars (a non-USD amount is converted to USD at the platform rate before the limit is checked). 0 means prepaid.", "x-description-ar": "مبلغ التحصيل عند الاستلام الذي يدفعه المستلم، من 0 إلى 100,000,000 دولار أمريكي (يُحوَّل المبلغ بغير الدولار إلى الدولار بسعر المنصة قبل فحص الحد). القيمة 0 تعني مدفوع مسبقاً.", "minimum": 0, "maximum": 100000000, "default": 0, "x-internal-field": "cod_amount" }, "currency": { "type": "string", "description": "Currency code of `cod_amount` (case-insensitive). The amount is stored in US dollars, so `cod_amount` in parcel objects is always USD. A company may accept only some currencies. A missing exchange rate gives `422`.", "x-description-ar": "رمز عملة `cod_amount` (لا فرق بين الأحرف الكبيرة والصغيرة). يُخزَّن المبلغ بالدولار، لذا يكون `cod_amount` في كائنات الطرد بالدولار دائماً. وقد لا تقبل الشركة إلا بعض العملات. وغياب سعر الصرف يعطي `422`.", "enum": [ "USD", "SYP", "SAR", "AED", "QAR", "KWD", "JOD", "IQD", "EGP", "LBP", "TRY", "EUR" ], "default": "USD", "x-internal-field": "cod_currency", "x-aliases": [ "cod_currency" ] }, "weight": { "type": "number", "description": "Weight in kilograms, from 0.01 to 1000. Default 1. For internal pricing the weight is rounded up to a whole kilogram (minimum 1).", "x-description-ar": "الوزن بالكيلوغرام من 0.01 إلى 1000. الافتراضي 1. في التسعير الداخلي يُقرَّب الوزن إلى كيلوغرام كامل (الحد الأدنى 1).", "minimum": 0.01, "maximum": 1000, "default": 1, "x-internal-field": "weight", "x-aliases": [ "weight_kg" ] }, "pickup_location_id": { "type": "integer", "description": "One of the merchant's pickup locations (`pickup_locations` in `GET /merchants`). The merchant's default location is used when omitted. Errors are reported on the field `shop_id`.", "x-description-ar": "أحد أماكن الاستلام لدى التاجر (`pickup_locations` في `GET /merchants`). يُستخدم المكان الافتراضي للتاجر عند عدم الإرسال. وتُبلَّغ الأخطاء على الحقل `shop_id`.", "x-internal-field": "shop_id", "x-aliases": [ "shop_id" ] }, "note": { "type": "string", "description": "Note for the delivery company, up to 2000 characters.", "x-description-ar": "ملاحظة لشركة التوصيل بحد أقصى 2000 محرف.", "maxLength": 2000, "x-internal-field": "note" }, "shipping_paid_by": { "type": "string", "description": "Who pays the shipping fee, for carriers that support the choice: `sender`, `customer` (the recipient) or `included_in_cod`.", "x-description-ar": "من يدفع أجرة الشحن، لشركات الشحن التي تدعم الاختيار: `sender` (المرسل) أو `customer` (المستلم) أو `included_in_cod` (ضمن مبلغ التحصيل).", "enum": [ "sender", "customer", "included_in_cod" ], "x-internal-field": "shipping_paid_by" } }, "required": [ "merchant_id", "recipient" ] }, "AssignRequest": { "type": "object", "description": "Body of the assignment.", "x-description-ar": "جسم طلب التعيين.", "properties": { "deliveryman_id": { "type": "integer", "description": "The courier: an `id` from `GET /deliverymen`. It must be one of your couriers.", "x-description-ar": "المندوب: قيمة `id` من `GET /deliverymen`. يجب أن يكون أحد مناديبك." }, "note": { "type": "string", "description": "Optional note recorded with the assignment.", "x-description-ar": "ملاحظة اختيارية تُسجَّل مع التعيين." }, "force": { "type": "boolean", "description": "Send `true` to go beyond the courier's parcel limit.", "x-description-ar": "أرسل `true` لتجاوز حدّ طرود المندوب." } }, "required": [ "deliveryman_id" ] }, "StatusRequest": { "type": "object", "description": "Body of the status update.", "x-description-ar": "جسم طلب تحديث الحالة.", "properties": { "action": { "type": "string", "description": "The change to apply: `received` (Received Warehouse), `deliver` (Delivered), `partial` (partly delivered; `collected` is required), `fail` (Return to Courier, stage `returning`), `reschedule` (back to the warehouse for a new dispatch, counts one attempt) or `returned` (return received by the merchant, final).", "x-description-ar": "التغيير المطلوب: `received` (مستلم في المستودع) أو `deliver` (تم التسليم) أو `partial` (تسليم جزئي؛ `collected` مطلوب) أو `fail` (إرجاع إلى المندوب، المرحلة `returning`) أو `reschedule` (عودة إلى المستودع لتوزيع جديد وتُحسب محاولة) أو `returned` (استلم التاجر المرتجع، نهائي).", "enum": [ "received", "deliver", "partial", "fail", "reschedule", "returned" ] }, "collected": { "type": "number", "description": "Amount collected, in US dollars. Required for `partial`; it cannot exceed the COD amount.", "x-description-ar": "المبلغ المحصَّل بالدولار. مطلوب مع `partial`؛ ولا يجوز أن يتجاوز مبلغ التحصيل.", "minimum": 0 }, "note": { "type": "string", "description": "Optional note recorded with the change.", "x-description-ar": "ملاحظة اختيارية تُسجَّل مع التغيير." } }, "required": [ "action" ] }, "WebhookEventParcelCreated": { "type": "object", "description": "Message body of `parcel.created`.", "x-description-ar": "جسم الرسالة `parcel.created`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.created" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelStatusChanged": { "type": "object", "description": "Message body of `parcel.status_changed`.", "x-description-ar": "جسم الرسالة `parcel.status_changed`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.status_changed" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelOutForDelivery": { "type": "object", "description": "Message body of `parcel.out_for_delivery`.", "x-description-ar": "جسم الرسالة `parcel.out_for_delivery`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.out_for_delivery" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelDelivered": { "type": "object", "description": "Message body of `parcel.delivered`.", "x-description-ar": "جسم الرسالة `parcel.delivered`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.delivered" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelReturning": { "type": "object", "description": "Message body of `parcel.returning`.", "x-description-ar": "جسم الرسالة `parcel.returning`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.returning" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelReturned": { "type": "object", "description": "Message body of `parcel.returned`.", "x-description-ar": "جسم الرسالة `parcel.returned`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.returned" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelCancelled": { "type": "object", "description": "Message body of `parcel.cancelled`.", "x-description-ar": "جسم الرسالة `parcel.cancelled`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.cancelled" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventParcelAwaitingFunds": { "type": "object", "description": "Message body of `parcel.awaiting_funds`.", "x-description-ar": "جسم الرسالة `parcel.awaiting_funds`.", "properties": { "id": { "type": "string", "description": "Event id (`evt_` plus 24 lowercase characters); the same as the `X-DS-Event-Id` header.", "x-description-ar": "معرّف الحدث (`evt_` يليه 24 حرفاً صغيراً)؛ وهو نفسه ترويسة `X-DS-Event-Id`.", "pattern": "^evt_[a-z0-9]{24}$" }, "event": { "const": "parcel.awaiting_funds" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Parcel" } }, "required": [ "id", "event", "created_at", "data" ] } }, "responses": { "Unauthenticated": { "description": "Missing or unknown API key. `unauthenticated`: no key in an `Authorization: Bearer` header. `invalid_key`: the key is unknown (renewed, revoked, mistyped, or of another type: only the company key `ck_...` works here).", "x-description-ar": "مفتاح الـ API مفقود أو غير معروف. `unauthenticated`: لا مفتاح في ترويسة `Authorization: Bearer`. `invalid_key`: المفتاح غير معروف (جُدِّد أو أُلغي أو كُتب خطأً أو هو من نوع آخر: مفتاح الشركة `ck_...` وحده يعمل هنا).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "unauthenticated": { "summary": "No key", "value": { "success": false, "error": { "code": "unauthenticated", "message": "Send the key in the header: Authorization: Bearer " } } }, "invalid_key": { "summary": "Unknown key", "value": { "success": false, "error": { "code": "invalid_key", "message": "The key is invalid or revoked. Generate a new key from the company dashboard ← Integrations and API." } } } } } } }, "SubscriptionExpired": { "description": "The company subscription has ended (`subscription_expired`). Platform-owned and merchant-owned companies are exempt from the subscription check.", "x-description-ar": "انتهى اشتراك الشركة (`subscription_expired`). والشركات المملوكة للمنصة أو لتاجر مستثناة من فحص الاشتراك.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "subscription_expired": { "summary": "Subscription ended", "value": { "success": false, "error": { "code": "subscription_expired", "message": "Company subscription expired — renew the subscription from the company dashboard." } } } } } } }, "Forbidden": { "description": "Access refused. `account_inactive`: the key's user or the company is suspended or missing. `plan_feature`: the company plan does not include the API feature.", "x-description-ar": "الوصول مرفوض. `account_inactive`: مستخدم المفتاح أو الشركة موقوف أو غير موجود. `plan_feature`: باقة الشركة لا تتضمن ميزة الـ API.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "account_inactive": { "summary": "Suspended company", "value": { "success": false, "error": { "code": "account_inactive", "message": "Company account suspended." } } }, "plan_feature": { "summary": "Plan without the API", "value": { "success": false, "error": { "code": "plan_feature", "message": "Localized text that names the feature and the plan problem." } } } } } } }, "TooManyRequests": { "description": "Rate limit. Two different answers share this status. (1) Plan limit (per minute or per day): the JSON error envelope with `error.code` `rate_limited`, `error.retry_after` and a `Retry-After` header. (2) IP or route limit: the framework answers before the API code runs, with `{\"message\": \"Too Many Attempts.\"}` (JSON only when you send `Accept: application/json`; otherwise an HTML page) and the headers `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.", "x-description-ar": "تجاوز حدّ الطلبات. يشترك في هذه الحالة ردّان مختلفان: (1) حدّ الباقة (في الدقيقة أو في اليوم): غلاف الخطأ بصيغة JSON مع `error.code` بقيمة `rate_limited` و`error.retry_after` وترويسة `Retry-After`. (2) حدّ عنوان IP أو المسار: يردّ الإطار قبل تنفيذ كود الـ API بـ `{\"message\": \"Too Many Attempts.\"}` (بصيغة JSON فقط عند إرسال `Accept: application/json`، وإلا صفحة HTML) مع الترويسات `Retry-After` و`X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset`.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ThrottleError" } ] }, "examples": { "plan_limit": { "summary": "Plan limit", "value": { "success": false, "error": { "code": "rate_limited", "message": "Localized text with the limit and the wait time", "retry_after": 42 } } }, "ip_limit": { "summary": "IP or route limit", "value": { "message": "Too Many Attempts." } } } } } }, "ServerError": { "description": "Unexpected server error. The message quotes a short reference that support can find in the logs; repeat the request only if its outcome is unknown.", "x-description-ar": "خطأ غير متوقع في الخادم. تتضمن الرسالة مرجعاً قصيراً يستطيع الدعم العثور عليه في السجلات؛ أعد الطلب فقط إذا كانت نتيجته مجهولة.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "server_error": { "summary": "Server error", "value": { "success": false, "error": { "code": "server_error", "message": "An error occurred on our side. If it happens again, contact support and mention reference E000000.", "reference": "E000000" } } } } } } } }, "parameters": { "AcceptLanguage": { "name": "Accept-Language", "in": "header", "description": "Language of error messages and labels (status labels, event notes, names). If the value starts with `en` the answer is in English; any other value or no header gives Arabic. Machine-readable fields never change.", "x-description-ar": "لغة رسائل الأخطاء والتسميات (تسمية الحالة وملاحظات الأحداث والأسماء). إذا بدأت القيمة بـ `en` جاء الرد بالإنجليزية، وأي قيمة أخرى أو غياب الترويسة يعطي العربية. الحقول المقروءة آلياً لا تتغير أبداً.", "schema": { "type": "string", "examples": [ "en" ] } }, "Page": { "name": "page", "in": "query", "description": "Page number, starting at 1. An invalid value or a value below 1 is treated as 1. A page beyond the last one returns an empty list.", "x-description-ar": "رقم الصفحة ويبدأ من 1. القيمة غير الصالحة أو الأصغر من 1 تُعامل على أنها 1. والصفحة بعد الأخيرة تعيد قائمة فارغة.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "DsEvent": { "name": "X-DS-Event", "in": "header", "required": true, "description": "The event name (for example `parcel.delivered`, or `ping` for a test).", "x-description-ar": "اسم الحدث (مثل `parcel.delivered`، أو `ping` للاختبار).", "schema": { "type": "string" } }, "DsEventId": { "name": "X-DS-Event-Id", "in": "header", "required": true, "description": "Event id, `evt_` plus 24 lowercase characters. The same for every attempt and every endpoint of the event: use it to ignore duplicates.", "x-description-ar": "معرّف الحدث، `evt_` يليه 24 حرفاً صغيراً. هو نفسه في كل محاولة ولكل رابط: استخدمه لتجاهل التكرار.", "schema": { "type": "string", "pattern": "^evt_[a-z0-9]{24}$" } }, "DsDelivery": { "name": "X-DS-Delivery", "in": "header", "required": true, "description": "UUID of this message to this endpoint. The same across attempts.", "x-description-ar": "معرّف UUID لهذه الرسالة إلى هذا الرابط. هو نفسه عبر المحاولات.", "schema": { "type": "string", "format": "uuid" } }, "DsAttempt": { "name": "X-DS-Attempt", "in": "header", "required": true, "description": "Attempt number, starting at 1.", "x-description-ar": "رقم المحاولة ويبدأ من 1.", "schema": { "type": "integer", "minimum": 1 } }, "DsTimestamp": { "name": "X-DS-Timestamp", "in": "header", "required": true, "description": "Send time in Unix seconds, renewed on every attempt. It is part of the signed text.", "x-description-ar": "وقت الإرسال بثواني Unix ويتجدد في كل محاولة. وهو جزء من النص الموقَّع.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "DsSignature": { "name": "X-DS-Signature", "in": "header", "required": true, "description": "`sha256=` followed by the lowercase hex of HMAC-SHA256 with the endpoint's signing key (`whsec_...`, the whole string) over the text `X-DS-Timestamp + \".\" + raw request body`. Compare in constant time.", "x-description-ar": "`sha256=` يليه التمثيل السداسي بأحرف صغيرة لـ HMAC-SHA256 بمفتاح توقيع الرابط (`whsec_...` بالسلسلة كاملة) على النص `X-DS-Timestamp + \".\" + جسم الطلب الخام`. قارن بدالة زمنها ثابت.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } } }, "headers": { "X-RateLimit-Limit": { "description": "The request limit of the counter that has the fewest requests left among the IP-address limits that applied to this request (per minute). Plan limits are not reflected here.", "x-description-ar": "حدّ الطلبات للعدّاد الأقل رصيداً بين حدود عنوان IP التي طُبّقت على هذا الطلب (في الدقيقة). لا تنعكس حدود الباقة في هذه الترويسة.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in that counter for the current one-minute window.", "x-description-ar": "عدد الطلبات المتبقية في ذلك العدّاد ضمن نافذة الدقيقة الحالية.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the blocked counter becomes available again. Sent only with the framework 429 response.", "x-description-ar": "الوقت (بالثواني بتوقيت Unix) الذي يصبح فيه العدّاد المحجوب متاحاً من جديد. يُرسل مع ردّ 429 الصادر عن الإطار فقط.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before repeating the request.", "x-description-ar": "عدد الثواني التي يجب انتظارها قبل إعادة الطلب.", "schema": { "type": "integer", "minimum": 0 } } }, "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Company API key (ck_...)", "description": "The API key of your delivery company in the `Authorization` header: `Authorization: Bearer YOUR_COMPANY_API_KEY`. Only this header is read; a key in the query string or in the body is ignored. A company admin creates the key in the company panel (Integrations and API). It works only on `/api/company/v1`: a merchant key gives `invalid_key`. WooCommerce `ck_...` consumer keys are a different thing and never work here.", "x-description-ar": "مفتاح الـ API الخاص بشركة التوصيل لديك في ترويسة `Authorization`: `Authorization: Bearer YOUR_COMPANY_API_KEY`. تُقرأ هذه الترويسة فقط؛ والمفتاح في الاستعلام أو في الجسم يُتجاهل. ينشئ مدير الشركة المفتاح من لوحة الشركة (الربط والـ API). وهو يعمل على `/api/company/v1` فقط: مفتاح التاجر يعطي `invalid_key`. أما مفاتيح WooCommerce التي تبدأ بـ `ck_` فهي شيء مختلف ولا تعمل هنا أبداً." } } }, "x-rate-limit-notes": { "description": "Three layers apply. (1) A general limit of 60 requests per minute per IP address on every `/api` request. (2) Route limits, counted per IP address on ONE shared counter: the group limit of 300 per minute, and 120 for `POST /parcels`; because a `POST /parcels` request is counted by both the group and the route, one IP address can create at most about 60 parcels per minute. (3) Plan limits per company, per minute and per day (`429 rate_limited` with `Retry-After`). The limits that apply to each operation are listed on that operation.", "x-description-ar": "تُطبَّق ثلاث طبقات. (1) حدّ عام قدره 60 طلباً في الدقيقة لكل عنوان IP على كل طلب `/api`. (2) حدود المسارات، وتُحتسب لكل عنوان IP على عدّاد واحد مشترك: حدّ المجموعة 300 في الدقيقة، و120 لـ `POST /parcels`؛ ولأن طلب `POST /parcels` يُحسب على المجموعة وعلى المسار معاً، فلا يستطيع عنوان IP واحد إنشاء أكثر من نحو 60 طرداً في الدقيقة. (3) حدود الباقة لكل شركة في الدقيقة وفي اليوم (`429 rate_limited` مع `Retry-After`). وتُذكر الحدود المطبّقة على كل عملية في العملية نفسها." } }