{ "openapi": "3.1.0", "info": { "title": "Delivery Syria Merchant API", "x-title-ar": "واجهة التاجر في Delivery Syria", "version": "v1", "summary": "Price, create, list, track and cancel parcels, read the wallet statement and manage webhook endpoints.", "x-summary-ar": "تسعير الطرود وإنشاؤها وعرضها وتتبّعها وإلغاؤها، وقراءة كشف المحفظة، وإدارة روابط الويب هوك.", "description": "The merchant API (`/api/v1`) lets the system of a platform merchant work with parcels and the wallet. 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. 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/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/v1" }, "servers": [ { "url": "/api/v1", "description": "Relative to your platform host: `https://YOUR_DOMAIN/api/v1`.", "x-description-ar": "نسبي إلى نطاق منصتك: `https://YOUR_DOMAIN/api/v1`." } ], "security": [ { "bearerApiKey": [] } ], "tags": [ { "name": "Account", "description": "Your merchant profile, plan and wallet balances.", "x-name-ar": "الحساب", "x-description-ar": "ملف التاجر وباقته وأرصدة محافظه." }, { "name": "Lookups", "description": "Reference lists you need before creating a parcel: delivery companies and carriers, governorates, pickup locations and warehouse stock.", "x-name-ar": "قوائم الاختيار", "x-description-ar": "قوائم مرجعية تحتاجها قبل إنشاء الطرد: شركات التوصيل والشحن والمحافظات وأماكن الاستلام ومخزون المستودعات." }, { "name": "Pricing", "description": "Price a parcel without creating it.", "x-name-ar": "التسعير", "x-description-ar": "احتساب سعر الطرد دون إنشائه." }, { "name": "Parcels", "description": "Create, list, track and cancel parcels.", "x-name-ar": "الطرود", "x-description-ar": "إنشاء الطرود وعرضها وتتبّعها وإلغاؤها." }, { "name": "Statement", "description": "Wallet statement for a period.", "x-name-ar": "كشف الحساب", "x-description-ar": "كشف حساب المحفظة لفترة." }, { "name": "Webhook endpoints", "description": "Manage the URLs that receive your notifications. The messages themselves are described under Webhook events.", "x-name-ar": "روابط الويب هوك", "x-description-ar": "إدارة العناوين التي تستقبل إشعاراتك. أما الرسائل نفسها فمشروحة ضمن أحداث الويب هوك." }, { "name": "Webhook events", "description": "Messages the platform sends to your endpoints (outgoing webhooks): headers, signature and body of every event.", "x-name-ar": "أحداث الويب هوك", "x-description-ar": "الرسائل التي ترسلها المنصة إلى روابطك (الويب هوك الصادر): الترويسات والتوقيع وجسم كل حدث." } ], "paths": { "/me": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Get your account", "x-summary-ar": "جلب حسابك", "description": "Returns your merchant id, business name, plan and wallet balances. It is a good first call to check the key.", "x-description-ar": "تُرجع معرّف التاجر والاسم التجاري والباقة وأرصدة المحافظ. وهي أول استدعاء مناسب للتأكد من المفتاح.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Your 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": { "merchant_id": 12, "business_name": "Example Shop", "plan": { "name": "Example Plan", "expires_on": "2026-12-01", "active": true }, "balances": { "recharge": 150.5, "cod_due": 320, "held": 0, "company_due": 0 }, "currency": "$" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api", "developers.auth" ] } }, "/companies": { "get": { "operationId": "listCompanies", "tags": [ "Lookups" ], "summary": "List delivery companies and carriers", "x-summary-ar": "قائمة شركات التوصيل والشحن", "description": "Lists the delivery companies and shipping carriers you can use. Send an `id` as `company_id` when you quote or create a parcel. The list is not paginated.", "x-description-ar": "تعرض شركات التوصيل وشركات الشحن التي يمكنك استخدامها. أرسل قيمة `id` على أنها `company_id` عند التسعير أو إنشاء الطرد. القائمة غير مرقّمة.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Companies you can use.", "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/DeliveryCompany" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 3, "name": "Example Delivery", "type": "delivery_company", "pricing_mode": "governorate", "supports_own_account": false, "coverage": null }, { "id": 5, "name": "Example Carrier", "type": "carrier", "pricing_mode": "carrier_quote", "supports_own_account": true, "coverage": { "SY": [] } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/governorates": { "get": { "operationId": "listGovernorates", "tags": [ "Lookups" ], "summary": "List governorates", "x-summary-ar": "قائمة المحافظات", "description": "Returns `id`, `name` and `name_ar` for every active governorate. Send `name` or `name_ar` in `recipient.governorate`. The list is not paginated.", "x-description-ar": "تُرجع `id` و`name` و`name_ar` لكل محافظة فعّالة. أرسل `name` أو `name_ar` في `recipient.governorate`. القائمة غير مرقّمة.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Active governorates.", "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/Governorate" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 1, "name": "Damascus", "name_ar": "دمشق" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/pickup-locations": { "get": { "operationId": "listPickupLocations", "tags": [ "Lookups" ], "summary": "List your pickup locations", "x-summary-ar": "قائمة أماكن الاستلام لديك", "description": "Returns your pickup locations, default first. When you omit `pickup_location_id` on a parcel, the default location is used. Add locations in the merchant panel. The list is not paginated.", "x-description-ar": "تُرجع أماكن الاستلام لديك والافتراضي أولاً. عند عدم إرسال `pickup_location_id` مع الطرد يُستخدم المكان الافتراضي. أضف الأماكن من لوحة التاجر. القائمة غير مرقّمة.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Your pickup locations.", "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/PickupLocation" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 7, "name": "Main branch", "phone": "0900000000", "address": "Example street, building 1", "lat": null, "lng": null, "default": true, "warehouse_id": null, "active": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/warehouse/stock": { "get": { "operationId": "getWarehouseStock", "tags": [ "Lookups" ], "summary": "Get your warehouse stock", "x-summary-ar": "جلب بضاعتك في المستودعات", "description": "For each active warehouse allocation: the warehouse, its pickup location id (use it as `pickup_location_id` to ship from this stock), pallets and the items with quantities. Returns an empty list when you have no active allocation.", "x-description-ar": "لكل حجز مستودع فعّال: المستودع ومعرّف مكان الاستلام الخاص به (استخدمه على أنه `pickup_location_id` للشحن من هذا المخزون) والمنصّات والأصناف بكمياتها. تُرجع قائمة فارغة عند عدم وجود حجز فعّال.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Stock per warehouse allocation.", "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/WarehouseStock" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "warehouse_id": 1, "warehouse": "Example Warehouse", "pickup_location_id": 9, "pallets": 2, "items": [ { "item_id": 5, "sku": "A1", "name": "Example item", "qty": 20, "reserved": 2, "available": 18 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/quote": { "post": { "operationId": "quoteParcel", "tags": [ "Pricing" ], "summary": "Price a parcel without creating it", "x-summary-ar": "تسعير طرد دون إنشائه", "description": "Calculates the price of a parcel on the server without creating it or charging anything. It takes the same fields as `POST /parcels` and only `company_id` is required, but the fields the price needs depend on the company's `pricing_mode` (see `GET /companies`): `governorate` needs `recipient.governorate` (or an address the platform can map, or coordinates); `per_kg` needs `weight`; `per_km` needs `recipient.lat` and `recipient.lng` and a pickup location with a map position; `km_kg` needs both; `carrier_quote` asks the carrier for its price. For internal pricing the weight is rounded up to a whole kilogram and a company minimum fee is applied. The answer differs for a delivery company and for a carrier (see `Quote`).", "x-description-ar": "تحسب سعر الطرد على الخادم دون إنشائه ودون خصم أي مبلغ. تأخذ الحقول نفسها المستخدمة في `POST /parcels` والمطلوب فقط `company_id`، لكن الحقول التي يحتاجها السعر تعتمد على `pricing_mode` للشركة (انظر `GET /companies`): `governorate` يحتاج `recipient.governorate` (أو عنواناً تستطيع المنصة ربطه بمحافظة، أو إحداثيات)؛ و`per_kg` يحتاج `weight`؛ و`per_km` يحتاج `recipient.lat` و`recipient.lng` ومكان استلام له موقع على الخريطة؛ و`km_kg` يحتاج الاثنين؛ و`carrier_quote` يطلب السعر من شركة الشحن. وفي التسعير الداخلي يُقرَّب الوزن إلى كيلوغرام كامل ويُطبَّق الحد الأدنى للأجرة عند الشركة. ويختلف الرد بين شركة التوصيل وشركة الشحن (انظر `Quote`).", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "example": { "company_id": 3, "recipient": { "governorate": "Damascus" }, "weight": 2 } } } }, "responses": { "200": { "description": "The quote.", "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/Quote" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "pricing_mode": "governorate", "pricing_label": "Fixed amount per governorate", "governorate": "Damascus", "distance_km": 0, "weight_kg": 2, "delivery_fee": 6, "platform_fee": 1, "charged_now": 7 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`validation_failed`: `company_id` missing or not available to you, or a field the pricing needs is missing. `quote_failed`: the price could not be calculated. `carrier_error`: the carrier refused or could not price it.", "x-description-ar": "`validation_failed`: `company_id` مفقود أو غير متاح لك، أو ينقص حقل يحتاجه التسعير. `quote_failed`: تعذّر حساب السعر. `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": "Missing company", "value": { "success": false, "error": { "code": "validation_failed", "message": "company_id is required — get the list from GET /companies", "fields": { "company_id": [ "company_id is required — get the list from GET /companies" ] } } } }, "quote_failed": { "summary": "Price not calculated", "value": { "success": false, "error": { "code": "quote_failed", "message": "Could not calculate the price." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/parcels": { "get": { "operationId": "listParcels", "tags": [ "Parcels" ], "summary": "List your parcels", "x-summary-ar": "عرض طرودك", "description": "Lists your parcels, newest first (by id), without `events`. Parcels in the `awaiting_funds` stage are not listed (fetch one by tracking number or reference). Paginated: the answer has `meta`.", "x-description-ar": "تعرض طرودك الأحدث أولاً (حسب المعرّف) دون `events`. الطرود في المرحلة `awaiting_funds` لا تُعرض (اجلب الواحد منها برقم التتبع أو المرجع). الرد مرقّم ويتضمن `meta`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "reference", "in": "query", "description": "Exact match on the `reference` you sent at creation.", "x-description-ar": "تطابق تام مع `reference` الذي أرسلته عند الإنشاء.", "schema": { "type": "string" }, "example": "ORDER-1043" }, { "name": "from", "in": "query", "description": "First creation day, `YYYY-MM-DD`, inclusive (UTC). The format is not validated: use only this one.", "x-description-ar": "أول يوم إنشاء `YYYY-MM-DD` شاملاً (بتوقيت UTC). لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "description": "Last creation day, `YYYY-MM-DD`, inclusive (UTC). The format is not validated: use only this one.", "x-description-ar": "آخر يوم إنشاء `YYYY-MM-DD` شاملاً (بتوقيت UTC). لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "stage", "in": "query", "description": "Filter by the `stage` of the parcel. Only these six values filter; any other value (including `processing`, `awaiting_funds` and typos) is silently ignored and everything comes back unfiltered.", "x-description-ar": "تصفية حسب `stage` للطرد. هذه القيم الست فقط تُصفّي؛ وأي قيمة أخرى (ومنها `processing` و`awaiting_funds` والأخطاء الإملائية) تُتجاهل بصمت ويعود كل شيء دون تصفية.", "schema": { "type": "string", "enum": [ "pending", "out_for_delivery", "delivered", "partially_delivered", "returning", "returned" ] }, "example": "out_for_delivery", "x-unknown-value-behavior": "ignored" }, { "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" } ], "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api", "developers.pagination" ] }, "post": { "operationId": "createParcel", "tags": [ "Parcels" ], "summary": "Create a parcel", "x-summary-ar": "إنشاء طرد", "description": "Creates a parcel. The delivery fee is calculated on the server and charged to your wallet. Send the same `reference` again to retry safely: you get the existing parcel back with `\"duplicate\": true` (HTTP 200) and nothing is charged (parcels that were refunded or expired do not count). There is no `Idempotency-Key` header. A merchant with no active plan is rejected with `plan_feature` before the parcel is processed; a reached parcel quota gives `422` on the field `plan`. If an external carrier rejects the parcel, nothing is created or charged (`carrier_error`).", "x-description-ar": "تنشئ طرداً. تُحسب أجرة التوصيل على الخادم وتُخصم من محفظتك. أرسل `reference` نفسه مجدداً لإعادة المحاولة بأمان: تحصل على الطرد الموجود مع `\"duplicate\": true` (HTTP 200) ولا يُخصم أي مبلغ (الطرود المستردّة أو المنتهية لا تُحتسب). لا توجد ترويسة `Idempotency-Key`. التاجر بلا باقة فعّالة يُرفض بالرمز `plan_feature` قبل معالجة الطرد، وبلوغ حصة الطرود يعطي `422` على الحقل `plan`. وإذا رفضت شركة شحن خارجية الطرد فلا يُنشأ شيء ولا يُخصم شيء (`carrier_error`).", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParcelRequest" }, "example": { "company_id": 3, "reference": "ORDER-1043", "recipient": { "name": "Example Name", "phone": "0900000000", "governorate": "Damascus", "address": "Example street, building 1" }, "cod_amount": 25, "weight": 1.5, "note": "Call before arriving" } } } }, "responses": { "200": { "description": "A parcel with the same `reference` already exists: it is returned unchanged with `duplicate: true`.", "x-description-ar": "يوجد طرد بالمرجع `reference` نفسه: يُرجع كما هو مع `duplicate: true`.", "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" }, "duplicate": { "const": true } }, "required": [ "success", "data", "duplicate" ] }, "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" }, "duplicate": true } } } }, "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" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "description": "`insufficient_balance`: the wallet balance is not enough (the message gives the required and available amounts). Send `wait_for_balance: true` to keep the parcel as `awaiting_funds` instead.", "x-description-ar": "`insufficient_balance`: رصيد المحفظة لا يكفي (تذكر الرسالة المبلغ المطلوب والمتاح). أرسل `wait_for_balance: true` لحفظ الطرد بالمرحلة `awaiting_funds` بدلاً من ذلك.", "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" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`validation_failed`: a field is missing or wrong (`fields` lists them, using the platform's internal field names), or `company_id` is not available to you, or the quota (`plan`) is used up. `carrier_error`: the external carrier rejected the parcel or the carrier account is not usable.", "x-description-ar": "`validation_failed`: حقل مفقود أو خاطئ (يسردها `fields` بأسماء المنصة الداخلية)، أو `company_id` غير متاح لك، أو استُنفدت الحصة (`plan`). `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": "Missing recipient phone", "value": { "success": false, "error": { "code": "validation_failed", "message": "The customer phone field is required.", "fields": { "customer_phone": [ "The customer phone field is required." ] } } } }, "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": 120, "route": 60 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api", "developers.versioning" ] } }, "/parcels/{tracking}": { "get": { "operationId": "getParcel", "tags": [ "Parcels" ], "summary": "Get one parcel with its events", "x-summary-ar": "جلب طرد واحد مع أحداثه", "description": "Takes a tracking number or a `reference` (the newest match wins) and returns the parcel with `events` in time order. Also finds parcels in the `awaiting_funds` stage.", "x-description-ar": "تأخذ رقم تتبع أو `reference` (يُعتمد أحدث تطابق) وتُرجع الطرد مع `events` بترتيب زمني. وتجد أيضاً الطرود في المرحلة `awaiting_funds`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "tracking", "in": "path", "required": true, "description": "A tracking number, or the `reference` you sent when creating the parcel (the newest match wins; a reference may resolve to a different parcel than you expect, so cancel by 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", "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" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no parcel with this tracking number or reference in your account (a cancelled parcel no longer exists).", "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 for your account." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/parcels/{tracking}/cancel": { "post": { "operationId": "cancelParcel", "tags": [ "Parcels" ], "summary": "Cancel a parcel and refund the fee", "x-summary-ar": "إلغاء طرد واسترجاع الأجرة", "description": "Cancels a parcel and refunds what was charged at creation. It works only while the status is Pending or Received Warehouse and the parcel has no `external_tracking_number`. The parcel is deleted (a second call gives `404`). An API cancellation does not send a `parcel.cancelled` webhook.", "x-description-ar": "تلغي الطرد وتسترجع ما خُصم عند الإنشاء. لا تعمل إلا ما دامت الحالة «معلّق» أو «مستلم في المستودع» وليس للطرد `external_tracking_number`. يُحذف الطرد (والاستدعاء الثاني يعطي `404`). والإلغاء عبر الـ API لا يرسل ويب هوك `parcel.cancelled`.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "tracking", "in": "path", "required": true, "description": "A tracking number, or the `reference` you sent when creating the parcel (the newest match wins; a reference may resolve to a different parcel than you expect, so cancel by tracking number).", "x-description-ar": "رقم التتبع، أو `reference` الذي أرسلته عند إنشاء الطرد (يُعتمد أحدث تطابق؛ وقد يشير المرجع إلى طرد غير الذي تقصده، لذا ألغِ برقم التتبع).", "schema": { "type": "string" }, "example": "DS-000000" } ], "responses": { "200": { "description": "The parcel was cancelled and refunded.", "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/CancelResult" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "tracking_number": "DS-000000", "cancelled": true, "refunded": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no parcel with this number in your account.", "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 for your account." } } } } } } }, "409": { "description": "`not_cancellable`: the parcel left the Pending or Received Warehouse status, or it went to an external carrier.", "x-description-ar": "`not_cancellable`: خرج الطرد من الحالة «معلّق» أو «مستلم في المستودع»، أو أُرسل إلى شركة شحن خارجية.", "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_cancellable": { "summary": "Already on its way", "value": { "success": false, "error": { "code": "not_cancellable", "message": "The parcel is out for delivery or sent to the shipping company — it cannot be cancelled from here." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api", "developers.versioning" ] } }, "/statement": { "get": { "operationId": "getStatement", "tags": [ "Statement" ], "summary": "Get your wallet statement", "x-summary-ar": "جلب كشف حساب المحفظة", "description": "Your wallet statement for a period: opening and closing balance per wallet, a summary per movement type and every movement (oldest first). Amounts are in US dollars. Paginated: `meta` counts the `lines`; `wallets` and `by_category` cover the whole period.", "x-description-ar": "كشف حساب محفظتك لفترة: الرصيد الافتتاحي والختامي لكل محفظة، وملخص لكل نوع حركة، وكل الحركات (الأقدم أولاً). المبالغ بالدولار. الرد مرقّم: `meta` يعدّ `lines`، أما `wallets` و`by_category` فتغطيان الفترة كلها.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "from", "in": "query", "description": "First day, `YYYY-MM-DD`. Default: the first day of the current month. Accepted only as a literal `YYYY-MM-DD`; otherwise ignored. If `from` is after `to` they are swapped; a range longer than 366 days is shortened by moving `from`.", "x-description-ar": "أول يوم `YYYY-MM-DD`. الافتراضي: أول يوم في الشهر الحالي. يُقبل بصيغة `YYYY-MM-DD` حرفياً فقط وإلا يُتجاهل. وإذا جاء `from` بعد `to` تُبدَّل القيمتان، والمدى الأطول من 366 يوماً يُقصَّر بتحريك `from`.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "description": "Last day, `YYYY-MM-DD`. Default: today. Same rules as `from`.", "x-description-ar": "آخر يوم `YYYY-MM-DD`. الافتراضي: اليوم. بالقواعد نفسها المطبّقة على `from`.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "wallet", "in": "query", "description": "Only this wallet: `recharge` (shipping balance), `held` (reserved amounts), `return` (cash-on-delivery dues) or `payout_pending`. Any other value is ignored.", "x-description-ar": "هذه المحفظة فقط: `recharge` (رصيد الشحن) أو `held` (المبالغ المحجوزة) أو `return` (مستحقات التحصيل) أو `payout_pending`. أي قيمة أخرى تُتجاهل.", "schema": { "type": "string", "enum": [ "recharge", "held", "return", "payout_pending" ] }, "x-unknown-value-behavior": "ignored" }, { "name": "category", "in": "query", "description": "Only this movement type, for example `parcel_created`. Lowercase letters and underscores (2 to 60 characters); it is not checked against known types, so an unknown value returns no lines.", "x-description-ar": "هذا النوع من الحركات فقط، مثل `parcel_created`. أحرف لاتينية صغيرة وشرطات سفلية (من 2 إلى 60 محرفاً)؛ ولا يُتحقق منه من قائمة الأنواع المعروفة، فالقيمة المجهولة لا تعيد أي سطر.", "schema": { "type": "string", "pattern": "^[a-z_]{2,60}$" }, "example": "parcel_created" }, { "name": "per_page", "in": "query", "description": "Page size, from 1 to 500 (default 100). 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 إلى 500 (الافتراضي 100). القيمة خارج المجال لا تُرفض بل تُقرَّب إلى أقرب حدّ، وتعود القيمة الفعلية في `meta.per_page`.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "The statement.", "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/Statement" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "success", "data", "meta" ] }, "example": { "success": true, "data": { "period": { "from": "2026-01-01", "to": "2026-01-31" }, "currency": "USD", "wallets": [ { "wallet": "recharge", "name": "Shipping balance", "opening": 50, "credits": 200, "debits": 132.5, "closing": 117.5, "count": 41 } ], "by_category": [ { "category": "parcel_created", "name": "Parcel creation fee", "credits": 0, "debits": 132.5, "count": 38 } ], "lines": [ { "id": 9811, "date": "2026-01-02T10:14:00+00:00", "wallet": "recharge", "wallet_name": "Shipping balance", "type": "parcel_created", "type_name": "Parcel creation fee", "credit": 0, "debit": 3.5, "balance": 46.5, "description": "Example description", "parcel": "DS-000000" } ] }, "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120, "route": 30 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.merchant-api" ] } }, "/webhooks/events": { "get": { "operationId": "listWebhookEvents", "tags": [ "Webhook endpoints" ], "summary": "List the events you can subscribe to", "x-summary-ar": "قائمة الأحداث التي يمكنك الاشتراك بها", "description": "Lists the event names with their short name and description in the request language. Send `*` or exact names in `events` when you create an endpoint. `ping` is not listed because it cannot be selected.", "x-description-ar": "تعرض أسماء الأحداث مع اسمها المختصر ووصفها بلغة الطلب. أرسل `*` أو أسماءً بعينها في `events` عند إنشاء الرابط. لا تُعرض `ping` لأنها لا تُختار.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "The 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": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventInfo" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "event": "parcel.delivered", "name": "Delivered", "description": "The parcel was delivered (fully or partially) — includes the collected amount." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.webhooks" ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhook endpoints" ], "summary": "List your webhook endpoints", "x-summary-ar": "قائمة روابط الويب هوك لديك", "description": "Lists your webhook endpoints. The signing key is never included. The list is not paginated.", "x-description-ar": "تعرض روابط الويب هوك لديك. لا يُرجَع مفتاح التوقيع أبداً. القائمة غير مرقّمة.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Your endpoints.", "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/Webhook" } } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": [ { "id": 7, "name": "ERP", "url": "https://example.com/hooks/delivery", "events": [ "parcel.delivered", "parcel.returned" ], "active": true, "disabled_reason": null, "last_status": null, "last_error": null, "last_sent_at": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.webhooks" ] }, "post": { "operationId": "createWebhook", "tags": [ "Webhook endpoints" ], "summary": "Add a webhook endpoint", "x-summary-ar": "إضافة رابط ويب هوك", "description": "Creates an endpoint and returns its signing key (`secret`) once. Needs a plan with the webhooks feature (`403 plan_feature`) and allows at most 10 endpoints, or your plan's limit if lower (`422 limit_reached`). The URL must be `https`, public, without user name or password, on port 443 or 8443. How messages are signed and retried: see the webhook articles.", "x-description-ar": "تنشئ رابطاً وتُرجع مفتاح توقيعه (`secret`) مرة واحدة. تحتاج باقة فيها ميزة الويب هوك (`403 plan_feature`) وتتيح 10 روابط كحد أقصى، أو حدّ باقتك إن كان أقل (`422 limit_reached`). يجب أن يكون العنوان `https` وعاماً وبلا اسم مستخدم أو كلمة مرور وعلى المنفذ 443 أو 8443. وطريقة توقيع الرسائل وإعادة إرسالها في مقالات الويب هوك.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "name": "ERP", "url": "https://example.com/hooks/delivery", "events": [ "parcel.delivered", "parcel.returned" ] } } } }, "responses": { "201": { "description": "The endpoint 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/WebhookWithSecret" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 7, "name": "ERP", "url": "https://example.com/hooks/delivery", "events": [ "parcel.delivered", "parcel.returned" ], "active": true, "disabled_reason": null, "last_status": null, "last_error": null, "last_sent_at": null, "secret": "whsec_EXAMPLE_ONLY_NOT_A_REAL_SECRET" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`validation_failed`: a field is missing or wrong (the URL must be https, public, port 443 or 8443; each event must be `*` or an exact name). `limit_reached`: you already have the maximum number of endpoints.", "x-description-ar": "`validation_failed`: حقل مفقود أو خاطئ (يجب أن يكون العنوان https وعاماً وعلى المنفذ 443 أو 8443، وكل حدث `*` أو اسماً بعينه). `limit_reached`: لديك أصلاً العدد الأقصى من الروابط.", "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": "Not https", "value": { "success": false, "error": { "code": "validation_failed", "message": "The URL must start with https://", "fields": { "url": [ "The URL must start with https://" ] } } } }, "limit_reached": { "summary": "Too many endpoints", "value": { "success": false, "error": { "code": "limit_reached", "message": "You have reached your plan limit: 10 webhook links." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120, "route": 20 }, "x-plan-features": [ "api", "webhooks" ], "x-help-keys": [ "developers.webhooks", "developers.webhooks.verify" ] } }, "/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "tags": [ "Webhook endpoints" ], "summary": "Edit a webhook endpoint", "x-summary-ar": "تعديل رابط ويب هوك", "description": "Edits `name`, `url`, `events` or `active`; send only what you want to change. Turning `active` on again resets the failure counter and clears the suspension reason.", "x-description-ar": "تعدّل `name` أو `url` أو `events` أو `active`؛ أرسل ما تريد تغييره فقط. تفعيل `active` من جديد يصفّر عدّاد الإخفاق ويمسح سبب الإيقاف.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "id", "in": "path", "required": true, "description": "Id of the webhook endpoint (from `GET /webhooks`).", "x-description-ar": "معرّف رابط الويب هوك (من `GET /webhooks`).", "schema": { "type": "integer" }, "example": 7 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "example": { "active": true } } } }, "responses": { "200": { "description": "The updated endpoint.", "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/Webhook" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "id": 7, "name": "ERP", "url": "https://example.com/hooks/delivery", "events": [ "parcel.delivered", "parcel.returned" ], "active": true, "disabled_reason": null, "last_status": null, "last_error": null, "last_sent_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no such webhook endpoint in your account.", "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 webhook endpoint", "value": { "success": false, "error": { "code": "not_found", "message": "Link not found." } } } } } } }, "422": { "description": "`validation_failed`: a field is wrong (same rules as on creation).", "x-description-ar": "`validation_failed`: حقل خاطئ (بالقواعد نفسها عند الإنشاء).", "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": "Not https", "value": { "success": false, "error": { "code": "validation_failed", "message": "The URL must start with https://", "fields": { "url": [ "The URL must start with https://" ] } } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.webhooks", "developers.webhooks.retries" ] }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhook endpoints" ], "summary": "Delete a webhook endpoint", "x-summary-ar": "حذف رابط ويب هوك", "description": "Deletes the endpoint. Messages still waiting for a retry are marked failed when their time comes.", "x-description-ar": "تحذف الرابط. الرسائل التي ما زالت بانتظار إعادة الإرسال تُعلَّم فاشلة عند حلول موعدها.", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "id", "in": "path", "required": true, "description": "Id of the webhook endpoint (from `GET /webhooks`).", "x-description-ar": "معرّف رابط الويب هوك (من `GET /webhooks`).", "schema": { "type": "integer" }, "example": 7 } ], "responses": { "200": { "description": "The endpoint was deleted.", "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/DeleteResult" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no such webhook endpoint in your account.", "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 webhook endpoint", "value": { "success": false, "error": { "code": "not_found", "message": "Link not found." } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.webhooks" ] } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhook endpoints" ], "summary": "Send a test message", "x-summary-ar": "إرسال رسالة اختبار", "description": "Sends a signed `ping` message to the endpoint and reports the HTTP status your system answered with. A successful test resets the failure counter. It is limited to 10 requests per minute on the route (about 5 in practice, see the rate-limit notes).", "x-description-ar": "ترسل رسالة `ping` موقَّعة إلى الرابط وتبلغك بحالة HTTP التي ردّ بها نظامك. الاختبار الناجح يصفّر عدّاد الإخفاق. وهي محدودة بـ 10 طلبات في الدقيقة على مستوى المسار (نحو 5 عملياً، انظر ملاحظات حدود الطلبات).", "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" }, { "name": "id", "in": "path", "required": true, "description": "Id of the webhook endpoint (from `GET /webhooks`).", "x-description-ar": "معرّف رابط الويب هوك (من `GET /webhooks`).", "schema": { "type": "integer" }, "example": 7 } ], "responses": { "200": { "description": "Your system answered with a 2xx status.", "x-description-ar": "ردّ نظامك بحالة 2xx.", "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/TestResult" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "delivered": true, "response_status": 200 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`not_found`: no such webhook endpoint in your account.", "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 webhook endpoint", "value": { "success": false, "error": { "code": "not_found", "message": "Link not found." } } } } } } }, "422": { "description": "`delivery_failed`: the message did not arrive (non-2xx answer, redirect, timeout or connection error). `response_status` has the status your system returned, or null.", "x-description-ar": "`delivery_failed`: لم تصل الرسالة (ردّ غير 2xx أو تحويل أو انتهاء مهلة أو خطأ اتصال). يحمل `response_status` الحالة التي أعادها نظامك، أو null.", "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": { "delivery_failed": { "summary": "Your system refused", "value": { "success": false, "error": { "code": "delivery_failed", "message": "Not delivered: your system answered 500", "response_status": 500 } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-rate-limit": { "general": 60, "group": 120, "route": 10 }, "x-plan-features": [ "api" ], "x-help-keys": [ "developers.webhooks", "developers.webhooks.verify" ] } } }, "webhooks": { "parcel.created": { "post": { "operationId": "webhookParcelCreated", "tags": [ "Webhook events" ], "summary": "Parcel created", "x-summary-ar": "طرد جديد", "description": "A parcel was created (from the panel, the API or a connected store). A new parcel normally sends this and then `parcel.status_changed` (status 5).", "x-description-ar": "أُنشئ طرد (من اللوحة أو الـ API أو متجر مربوط). الطرد الجديد يرسل عادةً هذا الحدث ثم `parcel.status_changed` (الحالة 5).", "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" } } } } }, "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, including the automatic move to status 5 right after creation. 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.", "x-description-ar": "أي تغيير في الحالة عبر مسار عمل الطرد، ومنه الانتقال التلقائي إلى الحالة 5 بعد الإنشاء مباشرة. وقد يرسل التغيير الواحد هذا الحدث وحدث المرحلة (لكل منهما معرّف حدث خاص). لا يُرسل من نماذج الموظفين المخصصة للاستلام والمراكز ولا من بعض نماذج التراجع: اقرأ الطرد عندما تحتاج إلى حالته الحالية.", "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" } } } } }, "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 the courier (statuses 7 and 8).", "x-description-ar": "الطرد مع المندوب (الحالتان 7 و8).", "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" } } } } }, "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.", "x-description-ar": "سُلِّم الطرد كاملاً أو جزئياً (الحالتان 9 و32). يتضمن `data.cod_collected` المبلغ المحصَّل.", "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" } } } } }, "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.", "x-description-ar": "تعذّر التسليم والطرد في طريق العودة.", "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" } } } } }, "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).", "x-description-ar": "استلم التاجر الطرد المرتجع (الحالتان 30 و13).", "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" } } } } }, "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 and the amount went back to your balance. Not sent when you cancel with `POST /parcels/{tracking}/cancel`.", "x-description-ar": "أبلغت شركة الشحن الخارجية المربوطة بإلغاء الطرد وعاد المبلغ إلى رصيدك. لا يُرسل عند الإلغاء عبر `POST /parcels/{tracking}/cancel`.", "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" } } } } }, "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 your balance is too low (with `wait_for_balance`, or store orders). It is completed when you top up.", "x-description-ar": "حُفظ الطلب لكن رصيدك لا يكفي (مع `wait_for_balance` أو طلبات المتاجر). يكتمل عند شحن الرصيد.", "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" } } } } }, "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 محاولات إجمالاً)." } } } }, "wallet.topup": { "post": { "operationId": "webhookWalletTopup", "tags": [ "Webhook events" ], "summary": "Balance topped up", "x-summary-ar": "شُحن الرصيد", "description": "Balance was added to your recharge (shipping) wallet by an approved top-up request or an online payment. Merchants only.", "x-description-ar": "أُضيف رصيد إلى محفظة الشحن لديك بطلب شحن تمت الموافقة عليه أو بدفع إلكتروني. للتجّار فقط.", "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/WebhookEventWalletTopup" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "wallet.topup", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": "topup_1", "method": "bank_transfer", "source": "manual", "amount": 100, "currency": "USD", "recharge_balance": 150 } } } } }, "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 محاولات إجمالاً)." } } } }, "wallet.withdrawal": { "post": { "operationId": "webhookWalletWithdrawal", "tags": [ "Webhook events" ], "summary": "Withdrawal decided", "x-summary-ar": "تقرّر طلب السحب", "description": "A payout withdrawal request was approved or rejected. Merchants only.", "x-description-ar": "قُبل طلب سحب المستحقات أو رُفض. للتجّار فقط.", "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/WebhookEventWalletWithdrawal" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "wallet.withdrawal", "created_at": "2026-01-01T12:10:00+00:00", "data": { "id": "withdrawal_1", "status": "approved", "reference": null, "note": null, "amount": 50, "currency": "USD", "recharge_balance": 150 } } } } }, "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 محاولات إجمالاً)." } } } }, "ping": { "post": { "operationId": "webhookPing", "tags": [ "Webhook events" ], "summary": "Test message", "x-summary-ar": "رسالة اختبار", "description": "Sent by `POST /webhooks/{id}/test` (and the panel's \"Send test\"). It cannot be selected as an event and is not retried automatically.", "x-description-ar": "تُرسل عبر `POST /webhooks/{id}/test` (وزر «إرسال تجربة» في اللوحة). لا يمكن اختيارها حدثاً ولا تُعاد تلقائياً.", "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/WebhookEventPing" }, "example": { "id": "evt_abcdefghijklmnopqrstuvwx", "event": "ping", "created_at": "2026-01-01T12:10:00+00:00", "data": { "message": "Test message from Delivery Syria" } } } } }, "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", "api_not_allowed", "plan_feature", "rate_limited", "not_found", "not_cancellable", "insufficient_balance", "validation_failed", "quote_failed", "carrier_error", "limit_reached", "delivery_failed", "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" } }, "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" ] }, "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" }, "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", "events" ], "x-extends": "Parcel" }, "Account": { "type": "object", "description": "Your account.", "x-description-ar": "حسابك.", "properties": { "merchant_id": { "type": "integer", "description": "Your merchant id.", "x-description-ar": "معرّف حسابك كتاجر." }, "business_name": { "type": [ "string", "null" ], "description": "Business name of the merchant.", "x-description-ar": "الاسم التجاري للتاجر." }, "plan": { "type": [ "object", "null" ], "description": "Latest subscription, or null when there is no subscription record.", "x-description-ar": "آخر اشتراك، أو null عند عدم وجود سجل اشتراك.", "properties": { "name": { "type": [ "string", "null" ], "description": "Plan name.", "x-description-ar": "اسم الباقة." }, "expires_on": { "type": "string", "description": "Subscription expiry date (`YYYY-MM-DD`).", "x-description-ar": "تاريخ انتهاء الاشتراك (`YYYY-MM-DD`).", "format": "date" }, "active": { "type": "boolean", "description": "Whether the plan is currently active.", "x-description-ar": "هل الباقة فعّالة حالياً." } }, "required": [ "name", "expires_on", "active" ] }, "balances": { "type": "object", "description": "Wallet balances in US dollars.", "x-description-ar": "أرصدة المحافظ بالدولار.", "properties": { "recharge": { "type": "number", "description": "Shipping balance (recharge wallet), in US dollars.", "x-description-ar": "رصيد الشحن (محفظة الشحن) بالدولار." }, "cod_due": { "type": "number", "description": "Cash-on-delivery dues (return wallet), in US dollars.", "x-description-ar": "مستحقات التحصيل عند الاستلام (محفظة المستحقات) بالدولار." }, "held": { "type": "number", "description": "Reserved amounts, in US dollars.", "x-description-ar": "المبالغ المحجوزة بالدولار." }, "company_due": { "type": "number", "description": "Company dues, in US dollars.", "x-description-ar": "مستحقات الشركة بالدولار." } }, "required": [ "recharge", "cod_due", "held", "company_due" ] }, "currency": { "type": "string", "description": "The platform's configured currency symbol (`$` by default). It is not the unit of the balances, which are always US dollars; `GET /statement` returns the code `USD`.", "x-description-ar": "رمز عملة المنصة المضبوط (`$` افتراضياً). وهو ليس وحدة الأرصدة التي تكون بالدولار دائماً؛ أما `GET /statement` فيُرجع الرمز `USD`." } }, "required": [ "merchant_id", "business_name", "plan", "balances", "currency" ] }, "DeliveryCompany": { "type": "object", "description": "A delivery company or carrier you can use.", "x-description-ar": "شركة توصيل أو شحن يمكنك استخدامها.", "properties": { "id": { "type": "integer", "description": "Send it as `company_id`.", "x-description-ar": "أرسله على أنه `company_id`." }, "name": { "type": "string", "description": "Company name.", "x-description-ar": "اسم الشركة." }, "type": { "type": "string", "description": "`delivery_company` or `carrier` (an external shipping carrier).", "x-description-ar": "`delivery_company` أو `carrier` (شركة شحن خارجية).", "enum": [ "delivery_company", "carrier" ] }, "pricing_mode": { "type": "string", "description": "How the price is calculated: `governorate` (fixed amount per governorate), `per_kg`, `per_km`, `km_kg`, or `carrier_quote` (the carrier's own price). Shown as `per_km` for a delivery company that has no stored mode.", "x-description-ar": "طريقة احتساب السعر: `governorate` (مبلغ ثابت حسب المحافظة) أو `per_kg` أو `per_km` أو `km_kg` أو `carrier_quote` (سعر شركة الشحن نفسها). تظهر `per_km` لشركة توصيل لا تحمل آلية محفوظة.", "enum": [ "governorate", "per_kg", "per_km", "km_kg", "carrier_quote" ] }, "supports_own_account": { "type": "boolean", "description": "True when the carrier allows merchant accounts and you have linked yours.", "x-description-ar": "تكون true عندما تسمح شركة الشحن بحسابات التجّار وتكون قد ربطتَ حسابك بها." }, "coverage": { "type": [ "object", "null" ], "description": "`null` when the company has no restriction; otherwise country code to the list of governorate names it covers (`[]` means all governorates of the country).", "x-description-ar": "`null` عندما لا تقيّد الشركة التغطية؛ وإلا فرمز الدولة ثم قائمة أسماء المحافظات التي تغطيها (`[]` تعني كل محافظات الدولة).", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "name", "type", "pricing_mode", "supports_own_account", "coverage" ] }, "Governorate": { "type": "object", "description": "An active governorate.", "x-description-ar": "محافظة فعّالة.", "properties": { "id": { "type": "integer", "description": "Governorate id. When you send it in `recipient.governorate`, send it as a string.", "x-description-ar": "معرّف المحافظة. عند إرساله في `recipient.governorate` أرسله نصاً." }, "name": { "type": "string", "description": "English name.", "x-description-ar": "الاسم بالإنجليزية." }, "name_ar": { "type": "string", "description": "Arabic name.", "x-description-ar": "الاسم بالعربية." } }, "required": [ "id", "name", "name_ar" ] }, "PickupLocation": { "type": "object", "description": "One of your pickup locations.", "x-description-ar": "أحد أماكن الاستلام لديك.", "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": "اسم المكان." }, "phone": { "type": [ "string", "null" ], "description": "Contact phone.", "x-description-ar": "هاتف التواصل." }, "address": { "type": [ "string", "null" ], "description": "Address.", "x-description-ar": "العنوان." }, "lat": { "type": [ "number", "null" ], "description": "Latitude.", "x-description-ar": "خط العرض." }, "lng": { "type": [ "number", "null" ], "description": "Longitude.", "x-description-ar": "خط الطول." }, "default": { "type": "boolean", "description": "True for the default location (used when `pickup_location_id` is omitted).", "x-description-ar": "تكون true للمكان الافتراضي (يُستخدم عند عدم إرسال `pickup_location_id`)." }, "warehouse_id": { "type": [ "integer", "null" ], "description": "Warehouse id when this is a warehouse pickup location, otherwise null.", "x-description-ar": "معرّف المستودع عندما يكون المكان مستودعاً، وإلا null." }, "active": { "type": "boolean", "description": "Whether the location can be used.", "x-description-ar": "هل يمكن استخدام المكان." } }, "required": [ "id", "name", "phone", "address", "lat", "lng", "default", "warehouse_id", "active" ] }, "WarehouseStock": { "type": "object", "description": "Your stock in one warehouse allocation.", "x-description-ar": "بضاعتك في حجز مستودع واحد.", "properties": { "warehouse_id": { "type": "integer", "description": "Warehouse id.", "x-description-ar": "معرّف المستودع." }, "warehouse": { "type": [ "string", "null" ], "description": "Warehouse name.", "x-description-ar": "اسم المستودع." }, "pickup_location_id": { "type": "integer", "description": "Pickup location of this allocation: use it as `pickup_location_id` to ship from this stock.", "x-description-ar": "مكان الاستلام لهذا الحجز: استخدمه على أنه `pickup_location_id` للشحن من هذا المخزون." }, "pallets": { "type": "integer", "description": "Pallets allocated.", "x-description-ar": "عدد المنصّات المحجوزة." }, "items": { "type": "array", "description": "Stock items.", "x-description-ar": "أصناف المخزون.", "items": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "Stock item id.", "x-description-ar": "معرّف صنف المخزون." }, "sku": { "type": [ "string", "null" ], "description": "Product code.", "x-description-ar": "رمز المنتج." }, "name": { "type": [ "string", "null" ], "description": "Product name.", "x-description-ar": "اسم المنتج." }, "qty": { "type": "integer", "description": "Quantity in stock.", "x-description-ar": "الكمية في المخزون." }, "reserved": { "type": "integer", "description": "Quantity reserved for other parcels.", "x-description-ar": "الكمية المحجوزة لطرود أخرى." }, "available": { "type": "integer", "description": "Quantity you can still ship.", "x-description-ar": "الكمية التي ما زال بإمكانك شحنها." } }, "required": [ "item_id", "sku", "name", "qty", "reserved", "available" ] } } }, "required": [ "warehouse_id", "warehouse", "pickup_location_id", "pallets", "items" ] }, "QuoteDeliveryCompany": { "type": "object", "description": "Quote for a delivery company.", "x-description-ar": "تسعيرة لشركة توصيل.", "properties": { "pricing_mode": { "type": "string", "description": "The pricing mode used.", "x-description-ar": "آلية التسعير المستخدمة.", "enum": [ "governorate", "per_kg", "per_km", "km_kg" ] }, "pricing_label": { "type": [ "string", "null" ], "description": "Label of the pricing mode in the request language.", "x-description-ar": "تسمية آلية التسعير بلغة الطلب." }, "governorate": { "type": [ "string", "null" ], "description": "Governorate used for governorate pricing, otherwise null.", "x-description-ar": "المحافظة المستخدمة في التسعير حسب المحافظة، وإلا null." }, "distance_km": { "type": "number", "description": "Distance used (0 unless the mode uses distance).", "x-description-ar": "المسافة المستخدمة (0 ما لم تعتمد الآلية على المسافة)." }, "weight_kg": { "type": "number", "description": "Weight used, rounded up to a whole kilogram (minimum 1).", "x-description-ar": "الوزن المستخدم مقرَّباً إلى كيلوغرام كامل (الحد الأدنى 1)." }, "delivery_fee": { "type": "number", "description": "Delivery fee in US dollars.", "x-description-ar": "أجرة التوصيل بالدولار." }, "platform_fee": { "type": "number", "description": "Platform fee in US dollars.", "x-description-ar": "رسم المنصة بالدولار." }, "charged_now": { "type": "number", "description": "Amount charged to your wallet at creation: delivery fee plus platform fee, or only the platform fee for your own internal delivery company.", "x-description-ar": "المبلغ الذي يُخصم من محفظتك عند الإنشاء: أجرة التوصيل مع رسم المنصة، أو رسم المنصة فقط لشركة التوصيل الداخلية الخاصة بك." } }, "required": [ "pricing_mode", "pricing_label", "governorate", "distance_km", "weight_kg", "delivery_fee", "platform_fee", "charged_now" ] }, "QuoteCarrier": { "type": "object", "description": "Quote for an external carrier: a different, smaller object. It has no `pricing_label`, `governorate`, `distance_km`, `weight_kg` or `delivery_fee`.", "x-description-ar": "تسعيرة لشركة شحن خارجية: كائن مختلف وأصغر. لا يتضمن `pricing_label` ولا `governorate` ولا `distance_km` ولا `weight_kg` ولا `delivery_fee`.", "properties": { "pricing_mode": { "const": "carrier_quote" }, "carrier": { "type": "string", "description": "Carrier name.", "x-description-ar": "اسم شركة الشحن." }, "account": { "type": "string", "description": "Which account would be used: the platform account or your own account at the carrier.", "x-description-ar": "الحساب الذي سيُستخدم: حساب المنصة أو حسابك الخاص لدى الشركة.", "enum": [ "platform_account", "merchant_account" ] }, "carrier_fee": { "type": "number", "description": "The carrier's price in the carrier's currency.", "x-description-ar": "سعر شركة الشحن بعملتها." }, "carrier_currency": { "type": "string", "description": "Currency of `carrier_fee`.", "x-description-ar": "عملة `carrier_fee`." }, "carrier_fee_usd": { "type": "number", "description": "The carrier's price in US dollars.", "x-description-ar": "سعر شركة الشحن بالدولار." }, "platform_fee": { "type": "number", "description": "Platform fee in US dollars.", "x-description-ar": "رسم المنصة بالدولار." }, "charged_now": { "type": "number", "description": "Amount charged to your wallet at creation, in US dollars.", "x-description-ar": "المبلغ المخصوم من محفظتك عند الإنشاء بالدولار." }, "held_now": { "type": "number", "description": "Amount held until delivery (your own account at the carrier), in US dollars.", "x-description-ar": "المبلغ المحجوز حتى التسليم (حسابك الخاص لدى الشركة) بالدولار." }, "required_balance": { "type": "number", "description": "Balance that must be available in your wallet, in US dollars.", "x-description-ar": "الرصيد الذي يجب أن يتوفر في محفظتك بالدولار." }, "shipping_paid_by": { "type": "string", "description": "Who pays the shipping fee (`sender`, `customer` or `included_in_cod`).", "x-description-ar": "من يدفع أجرة الشحن (`sender` أو `customer` أو `included_in_cod`)." }, "receiver_pays": { "type": "number", "description": "Amount the recipient pays on delivery, in US dollars.", "x-description-ar": "المبلغ الذي يدفعه المستلم عند التسليم بالدولار." }, "net_after_delivery": { "type": "number", "description": "Your net amount after delivery, in US dollars.", "x-description-ar": "صافي مبلغك بعد التسليم بالدولار." }, "destination": { "type": [ "string", "null" ], "description": "Destination note from the carrier.", "x-description-ar": "ملاحظة الوجهة من شركة الشحن." }, "currency": { "const": "USD" } }, "required": [ "pricing_mode", "carrier", "account", "carrier_fee", "carrier_currency", "carrier_fee_usd", "platform_fee", "charged_now", "held_now", "required_balance", "shipping_paid_by", "receiver_pays", "net_after_delivery", "destination", "currency" ] }, "Quote": { "oneOf": [ { "$ref": "#/components/schemas/QuoteDeliveryCompany" }, { "$ref": "#/components/schemas/QuoteCarrier" } ], "description": "The shape depends on the company: a delivery company gives `QuoteDeliveryCompany`, a carrier gives `QuoteCarrier` (tell them apart with `pricing_mode`).", "x-description-ar": "يعتمد الشكل على الشركة: شركة التوصيل تعطي `QuoteDeliveryCompany` وشركة الشحن تعطي `QuoteCarrier` (ميّز بينهما بـ `pricing_mode`)." }, "QuoteRequest": { "type": "object", "description": "The same fields as creation (without `warehouse_items`). Only `company_id` is required here; the other fields you must send depend on the company's `pricing_mode`.", "x-description-ar": "الحقول نفسها المستخدمة عند الإنشاء (دون `warehouse_items`). المطلوب هنا `company_id` فقط، أما الحقول الأخرى التي يجب إرسالها فتعتمد على `pricing_mode` للشركة.", "properties": { "company_id": { "type": "integer", "description": "Delivery company or carrier, an `id` from `GET /companies`. It must be available to your account.", "x-description-ar": "شركة التوصيل أو الشحن، قيمة `id` من `GET /companies`. يجب أن تكون متاحة لحسابك.", "x-internal-field": "company_id" }, "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" ] } } }, "reference": { "type": "string", "description": "Your own reference (order number). It does not affect the price.", "x-description-ar": "مرجعك الخاص (رقم الطلب). لا يؤثر في السعر.", "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 your pickup locations (`GET /pickup-locations`). Your default location is used when omitted. Errors are reported on the field `shop_id`.", "x-description-ar": "أحد أماكن الاستلام لديك (`GET /pickup-locations`). يُستخدم مكانك الافتراضي عند عدم الإرسال. وتُبلَّغ الأخطاء على الحقل `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" }, "use_own_account": { "type": "boolean", "description": "Ship with your own account at a carrier that allows merchant accounts. It fails with `carrier_error` when the carrier allows them and you have not linked yours; it is ignored when the carrier does not allow them, and has no effect on delivery companies.", "x-description-ar": "الشحن بحسابك الخاص لدى شركة شحن تسمح بحسابات التجّار. يفشل بالرمز `carrier_error` إن كانت الشركة تسمح بها ولم تربط حسابك، ويُتجاهل إن كانت لا تسمح بها، ولا أثر له على شركات التوصيل.", "x-internal-field": "use_own_account" }, "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": [ "company_id" ] }, "CreateParcelRequest": { "type": "object", "description": "Parcel fields. The platform validates them with the same rules on creation; the price is always calculated on the server.", "x-description-ar": "حقول الطرد. تتحقق المنصة منها بالقواعد نفسها عند الإنشاء، ويُحسب السعر دائماً على الخادم.", "properties": { "company_id": { "type": "integer", "description": "Delivery company or carrier, an `id` from `GET /companies`. It must be available to your account.", "x-description-ar": "شركة التوصيل أو الشحن، قيمة `id` من `GET /companies`. يجب أن تكون متاحة لحسابك.", "x-internal-field": "company_id" }, "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": "Your own unique reference (order number), up to 191 characters. It makes retries safe: sending the same reference again returns the existing parcel with `\"duplicate\": true` instead of creating a new one.", "x-description-ar": "مرجعك الخاص الفريد (رقم الطلب) بحد أقصى 191 محرفاً. يجعل إعادة المحاولة آمنة: إرسال المرجع نفسه مجدداً يُرجع الطرد الموجود مع `\"duplicate\": true` بدل إنشاء طرد جديد.", "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 your pickup locations (`GET /pickup-locations`). Your default location is used when omitted. Errors are reported on the field `shop_id`.", "x-description-ar": "أحد أماكن الاستلام لديك (`GET /pickup-locations`). يُستخدم مكانك الافتراضي عند عدم الإرسال. وتُبلَّغ الأخطاء على الحقل `shop_id`.", "x-internal-field": "shop_id", "x-aliases": [ "shop_id" ] }, "warehouse_items": { "type": "array", "description": "Products shipped from your stock. Required when the pickup location is a warehouse; ignored otherwise. Also accepted as `items`.", "x-description-ar": "المنتجات التي تُشحن من مخزونك. مطلوبة عندما يكون مكان الاستلام مستودعاً، وتُهمل في غير ذلك. وتُقبل أيضاً باسم `items`.", "items": { "type": "object", "description": "A stock line: `qty` plus either `sku` or `item_id`.", "x-description-ar": "سطر مخزون: `qty` مع `sku` أو `item_id`.", "properties": { "sku": { "type": "string", "description": "Product code (SKU) of the stock item.", "x-description-ar": "رمز المنتج (SKU) في المخزون." }, "item_id": { "type": "integer", "description": "Stock item id (alternative to `sku`).", "x-description-ar": "معرّف صنف المخزون (بديل لـ `sku`)." }, "qty": { "type": "integer", "description": "Quantity to ship with the parcel; must not exceed the available quantity.", "x-description-ar": "الكمية التي تخرج مع الطرد؛ يجب ألا تتجاوز الكمية المتاحة.", "minimum": 1 } }, "required": [ "qty" ] }, "x-aliases": [ "items" ] }, "note": { "type": "string", "description": "Note for the delivery company, up to 2000 characters.", "x-description-ar": "ملاحظة لشركة التوصيل بحد أقصى 2000 محرف.", "maxLength": 2000, "x-internal-field": "note" }, "use_own_account": { "type": "boolean", "description": "Ship with your own account at a carrier that allows merchant accounts. It fails with `carrier_error` when the carrier allows them and you have not linked yours; it is ignored when the carrier does not allow them, and has no effect on delivery companies.", "x-description-ar": "الشحن بحسابك الخاص لدى شركة شحن تسمح بحسابات التجّار. يفشل بالرمز `carrier_error` إن كانت الشركة تسمح بها ولم تربط حسابك، ويُتجاهل إن كانت لا تسمح بها، ولا أثر له على شركات التوصيل.", "x-internal-field": "use_own_account" }, "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" }, "wait_for_balance": { "type": "boolean", "description": "When the wallet balance is short, keep the parcel as `awaiting_funds` (answer `201`, hidden from `GET /parcels`) instead of failing with `402`. An hourly job completes it when the balance is enough and cancels it after 24 hours.", "x-description-ar": "عند عدم كفاية رصيد المحفظة يُحفظ الطرد بالمرحلة `awaiting_funds` (الرد `201` ويُخفى عن `GET /parcels`) بدل الفشل بالرمز `402`. تُكمله مهمة كل ساعة عند توفر الرصيد وتلغيه بعد 24 ساعة." } }, "required": [ "company_id", "recipient" ] }, "CancelResult": { "type": "object", "description": "Result of a cancellation.", "x-description-ar": "نتيجة الإلغاء.", "properties": { "tracking_number": { "type": "string", "description": "Tracking number of the cancelled parcel.", "x-description-ar": "رقم تتبع الطرد الملغى." }, "cancelled": { "const": true }, "refunded": { "const": true } }, "required": [ "tracking_number", "cancelled", "refunded" ] }, "Statement": { "type": "object", "description": "Wallet statement for a period. All amounts are in US dollars.", "x-description-ar": "كشف المحفظة لفترة. كل المبالغ بالدولار.", "properties": { "period": { "type": "object", "description": "The period actually applied.", "x-description-ar": "الفترة المطبّقة فعلياً.", "properties": { "from": { "type": "string", "description": "First day (`YYYY-MM-DD`).", "x-description-ar": "أول يوم (`YYYY-MM-DD`).", "format": "date" }, "to": { "type": "string", "description": "Last day (`YYYY-MM-DD`).", "x-description-ar": "آخر يوم (`YYYY-MM-DD`).", "format": "date" } }, "required": [ "from", "to" ] }, "currency": { "const": "USD" }, "wallets": { "type": "array", "description": "Opening and closing balance per wallet. Covers the whole period regardless of the page.", "x-description-ar": "الرصيد الافتتاحي والختامي لكل محفظة. تغطي الفترة كلها بصرف النظر عن الصفحة.", "items": { "type": "object", "properties": { "wallet": { "type": "string", "description": "Wallet code.", "x-description-ar": "رمز المحفظة.", "enum": [ "recharge", "held", "return", "payout_pending" ] }, "name": { "type": "string", "description": "Wallet label in the request language.", "x-description-ar": "تسمية المحفظة بلغة الطلب." }, "opening": { "type": "number", "description": "Balance before the period.", "x-description-ar": "الرصيد قبل الفترة." }, "credits": { "type": "number", "description": "Total credits in the period.", "x-description-ar": "مجموع الإيداعات في الفترة." }, "debits": { "type": "number", "description": "Total debits in the period.", "x-description-ar": "مجموع السحوبات في الفترة." }, "closing": { "type": "number", "description": "Balance at the end of the period.", "x-description-ar": "الرصيد في نهاية الفترة." }, "count": { "type": "integer", "description": "Number of movements.", "x-description-ar": "عدد الحركات." } }, "required": [ "wallet", "name", "opening", "credits", "debits", "closing", "count" ] } }, "by_category": { "type": "array", "description": "Summary per movement type. Covers the whole period regardless of the page.", "x-description-ar": "ملخص لكل نوع حركة. يغطي الفترة كلها بصرف النظر عن الصفحة.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Movement type code, for example `parcel_created`.", "x-description-ar": "رمز نوع الحركة، مثل `parcel_created`." }, "name": { "type": "string", "description": "Label of the type in the request language.", "x-description-ar": "تسمية النوع بلغة الطلب." }, "credits": { "type": "number", "description": "Credits of this type.", "x-description-ar": "إيداعات هذا النوع." }, "debits": { "type": "number", "description": "Debits of this type.", "x-description-ar": "سحوبات هذا النوع." }, "count": { "type": "integer", "description": "Number of movements.", "x-description-ar": "عدد الحركات." } }, "required": [ "category", "name", "credits", "debits", "count" ] } }, "lines": { "type": "array", "description": "The movements of the requested page, oldest first (date, then id). Paging applies to this list only.", "x-description-ar": "حركات الصفحة المطلوبة، الأقدم أولاً (التاريخ ثم المعرّف). يسري الترقيم على هذه القائمة فقط.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Movement id.", "x-description-ar": "معرّف الحركة." }, "date": { "type": "string", "description": "Time of the movement (ISO 8601).", "x-description-ar": "وقت الحركة (ISO 8601).", "format": "date-time" }, "wallet": { "type": "string", "description": "Wallet code.", "x-description-ar": "رمز المحفظة." }, "wallet_name": { "type": "string", "description": "Wallet label.", "x-description-ar": "تسمية المحفظة." }, "type": { "type": "string", "description": "Movement type code.", "x-description-ar": "رمز نوع الحركة." }, "type_name": { "type": "string", "description": "Label of the type.", "x-description-ar": "تسمية النوع." }, "credit": { "type": "number", "description": "Credit amount (0 for a debit).", "x-description-ar": "مبلغ الإيداع (0 للسحب)." }, "debit": { "type": "number", "description": "Debit amount (0 for a credit).", "x-description-ar": "مبلغ السحب (0 للإيداع)." }, "balance": { "type": "number", "description": "Wallet balance after the movement.", "x-description-ar": "رصيد المحفظة بعد الحركة." }, "description": { "type": [ "string", "null" ], "description": "Description of the movement.", "x-description-ar": "وصف الحركة." }, "parcel": { "type": [ "string", "null" ], "description": "Tracking number when the movement relates to a parcel.", "x-description-ar": "رقم التتبع عندما تتعلق الحركة بطرد." } }, "required": [ "id", "date", "wallet", "wallet_name", "type", "type_name", "credit", "debit", "balance", "description", "parcel" ] } } }, "required": [ "period", "currency", "wallets", "by_category", "lines" ] }, "WebhookEventName": { "type": "string", "description": "An event name accepted by the API: `*` (all events) or one exact event. Group names such as `parcel.*` are rejected here although the panel accepts them.", "x-description-ar": "اسم حدث تقبله الواجهة: `*` (كل الأحداث) أو حدث واحد بعينه. أسماء المجموعات مثل `parcel.*` تُرفض هنا مع أن اللوحة تقبلها.", "enum": [ "*", "parcel.created", "parcel.status_changed", "parcel.out_for_delivery", "parcel.delivered", "parcel.returning", "parcel.returned", "parcel.cancelled", "parcel.awaiting_funds", "wallet.topup", "wallet.withdrawal" ] }, "WebhookEventInfo": { "type": "object", "description": "An event you can subscribe to.", "x-description-ar": "حدث يمكنك الاشتراك به.", "properties": { "event": { "type": "string", "description": "Event name.", "x-description-ar": "اسم الحدث.", "enum": [ "parcel.created", "parcel.status_changed", "parcel.out_for_delivery", "parcel.delivered", "parcel.returning", "parcel.returned", "parcel.cancelled", "parcel.awaiting_funds", "wallet.topup", "wallet.withdrawal" ] }, "name": { "type": "string", "description": "Short name in the request language.", "x-description-ar": "اسم مختصر بلغة الطلب." }, "description": { "type": "string", "description": "When it is sent, in the request language.", "x-description-ar": "متى يُرسل، بلغة الطلب." } }, "required": [ "event", "name", "description" ] }, "Webhook": { "type": "object", "description": "A webhook endpoint (the signing key is never included).", "x-description-ar": "رابط ويب هوك (لا يُرجَع مفتاح التوقيع أبداً).", "properties": { "id": { "type": "integer", "description": "Endpoint id.", "x-description-ar": "معرّف الرابط." }, "name": { "type": [ "string", "null" ], "description": "Label you gave the endpoint.", "x-description-ar": "التسمية التي أعطيتها للرابط." }, "url": { "type": "string", "description": "HTTPS URL that receives the messages.", "x-description-ar": "عنوان HTTPS الذي يستقبل الرسائل." }, "events": { "type": "array", "description": "Subscribed events; `[\"*\"]` means all events.", "x-description-ar": "الأحداث المشترك بها؛ `[\"*\"]` تعني كل الأحداث.", "items": { "type": "string" } }, "active": { "type": "boolean", "description": "False when disabled, including automatic suspension after 40 consecutive failed attempts.", "x-description-ar": "تكون false عند التعطيل، ومنه الإيقاف التلقائي بعد 40 محاولة فاشلة متتالية." }, "disabled_reason": { "type": [ "string", "null" ], "description": "Why the endpoint was suspended automatically.", "x-description-ar": "سبب إيقاف الرابط تلقائياً." }, "last_status": { "type": [ "integer", "null" ], "description": "HTTP status of the last delivery attempt.", "x-description-ar": "حالة HTTP لآخر محاولة إرسال." }, "last_error": { "type": [ "string", "null" ], "description": "Error of the last failed attempt.", "x-description-ar": "خطأ آخر محاولة فاشلة." }, "last_sent_at": { "type": [ "string", "null" ], "description": "Time of the last attempt (ISO 8601).", "x-description-ar": "وقت آخر محاولة (ISO 8601).", "format": "date-time" } }, "required": [ "id", "name", "url", "events", "active", "disabled_reason", "last_status", "last_error", "last_sent_at" ] }, "WebhookWithSecret": { "type": "object", "description": "A webhook endpoint, including its signing key (shown once).", "x-description-ar": "رابط ويب هوك مع مفتاح التوقيع (يظهر مرة واحدة).", "properties": { "id": { "type": "integer", "description": "Endpoint id.", "x-description-ar": "معرّف الرابط." }, "name": { "type": [ "string", "null" ], "description": "Label you gave the endpoint.", "x-description-ar": "التسمية التي أعطيتها للرابط." }, "url": { "type": "string", "description": "HTTPS URL that receives the messages.", "x-description-ar": "عنوان HTTPS الذي يستقبل الرسائل." }, "events": { "type": "array", "description": "Subscribed events; `[\"*\"]` means all events.", "x-description-ar": "الأحداث المشترك بها؛ `[\"*\"]` تعني كل الأحداث.", "items": { "type": "string" } }, "active": { "type": "boolean", "description": "False when disabled, including automatic suspension after 40 consecutive failed attempts.", "x-description-ar": "تكون false عند التعطيل، ومنه الإيقاف التلقائي بعد 40 محاولة فاشلة متتالية." }, "disabled_reason": { "type": [ "string", "null" ], "description": "Why the endpoint was suspended automatically.", "x-description-ar": "سبب إيقاف الرابط تلقائياً." }, "last_status": { "type": [ "integer", "null" ], "description": "HTTP status of the last delivery attempt.", "x-description-ar": "حالة HTTP لآخر محاولة إرسال." }, "last_error": { "type": [ "string", "null" ], "description": "Error of the last failed attempt.", "x-description-ar": "خطأ آخر محاولة فاشلة." }, "last_sent_at": { "type": [ "string", "null" ], "description": "Time of the last attempt (ISO 8601).", "x-description-ar": "وقت آخر محاولة (ISO 8601).", "format": "date-time" }, "secret": { "type": "string", "description": "Signing key (`whsec_` plus 40 characters). It is returned only in this response: store it now.", "x-description-ar": "مفتاح التوقيع (`whsec_` يليه 40 محرفاً). يُرجع في هذا الرد فقط: احفظه الآن." } }, "required": [ "id", "name", "url", "events", "active", "disabled_reason", "last_status", "last_error", "last_sent_at", "secret" ] }, "CreateWebhookRequest": { "type": "object", "description": "Body of `POST /webhooks`.", "x-description-ar": "جسم الطلب `POST /webhooks`.", "properties": { "name": { "type": [ "string", "null" ], "description": "Optional label, up to 100 characters.", "x-description-ar": "تسمية اختيارية بحد أقصى 100 محرف.", "maxLength": 100 }, "url": { "type": "string", "description": "HTTPS URL, up to 500 characters. The host must resolve to public addresses only, with no user name or password, on port 443 or 8443. Redirects are not followed.", "x-description-ar": "عنوان HTTPS بحد أقصى 500 محرف. يجب أن يُحلّ النطاق إلى عناوين عامة فقط، دون اسم مستخدم أو كلمة مرور، وعلى المنفذ 443 أو 8443. ولا تُتبع التحويلات.", "format": "uri", "maxLength": 500, "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "events": { "type": "array", "description": "Events to receive: at least one entry, each `*` or an exact event name.", "x-description-ar": "الأحداث المطلوب استقبالها: عنصر واحد على الأقل، كل منها `*` أو اسم حدث بعينه.", "items": { "$ref": "#/components/schemas/WebhookEventName" }, "minItems": 1 }, "active": { "type": "boolean", "description": "Whether the endpoint is enabled (default true).", "x-description-ar": "هل الرابط مفعّل (الافتراضي true)." } }, "required": [ "url", "events" ] }, "UpdateWebhookRequest": { "type": "object", "description": "Body of `PATCH /webhooks/{id}`. Send only the fields you want to change.", "x-description-ar": "جسم الطلب `PATCH /webhooks/{id}`. أرسل الحقول التي تريد تغييرها فقط.", "properties": { "name": { "type": [ "string", "null" ], "description": "Label, up to 100 characters.", "x-description-ar": "التسمية بحد أقصى 100 محرف.", "maxLength": 100 }, "url": { "type": "string", "description": "New HTTPS URL (same rules as on creation).", "x-description-ar": "عنوان HTTPS الجديد (بالقواعد نفسها عند الإنشاء).", "format": "uri", "maxLength": 500, "pattern": "^[Hh][Tt][Tt][Pp][Ss]://" }, "events": { "type": "array", "description": "New list of events (at least one).", "x-description-ar": "القائمة الجديدة للأحداث (واحد على الأقل).", "items": { "$ref": "#/components/schemas/WebhookEventName" }, "minItems": 1 }, "active": { "type": "boolean", "description": "Turning it on again resets the failure counter and clears the suspension reason.", "x-description-ar": "تفعيله من جديد يصفّر عدّاد الإخفاق ويمسح سبب الإيقاف." } } }, "TestResult": { "type": "object", "description": "Result of a successful test message.", "x-description-ar": "نتيجة رسالة اختبار ناجحة.", "properties": { "delivered": { "const": true }, "response_status": { "type": "integer", "description": "HTTP status your endpoint answered with.", "x-description-ar": "حالة HTTP التي ردّ بها نظامك." } }, "required": [ "delivered", "response_status" ] }, "DeleteResult": { "type": "object", "description": "Result of a deletion.", "x-description-ar": "نتيجة الحذف.", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ] }, "WalletTopupData": { "type": "object", "description": "Data of `wallet.topup`.", "x-description-ar": "بيانات `wallet.topup`.", "properties": { "id": { "type": "string", "description": "Identifier of the top-up (`topup_` or `payment_`).", "x-description-ar": "معرّف عملية الشحن (`topup_` أو `payment_`)." }, "method": { "type": [ "string", "null" ], "description": "Payment method or gateway.", "x-description-ar": "طريقة الدفع أو البوابة." }, "source": { "type": "string", "description": "`manual` (approved top-up request) or `gateway` (online payment).", "x-description-ar": "`manual` (طلب شحن تمت الموافقة عليه) أو `gateway` (دفع إلكتروني).", "enum": [ "manual", "gateway" ] }, "reference": { "type": [ "string", "null" ], "description": "Payment reference. Present for `gateway` only.", "x-description-ar": "مرجع الدفع. يظهر مع `gateway` فقط." }, "amount": { "type": "number", "description": "Amount in US dollars.", "x-description-ar": "المبلغ بالدولار." }, "currency": { "const": "USD" }, "recharge_balance": { "type": "number", "description": "Shipping balance after the event, in US dollars.", "x-description-ar": "رصيد الشحن بعد الحدث بالدولار." } }, "required": [ "id", "method", "source", "amount", "currency", "recharge_balance" ] }, "WalletWithdrawalData": { "type": "object", "description": "Data of `wallet.withdrawal`.", "x-description-ar": "بيانات `wallet.withdrawal`.", "properties": { "id": { "type": "string", "description": "Identifier of the withdrawal (`withdrawal_`).", "x-description-ar": "معرّف السحب (`withdrawal_`)." }, "status": { "type": "string", "description": "`approved` or `rejected`.", "x-description-ar": "`approved` أو `rejected`.", "enum": [ "approved", "rejected" ] }, "reference": { "type": [ "string", "null" ], "description": "Payout reference. Present when `approved`.", "x-description-ar": "مرجع الدفع. يظهر عند `approved`." }, "note": { "type": [ "string", "null" ], "description": "Administrator note. Present when `rejected`.", "x-description-ar": "ملاحظة الإدارة. تظهر عند `rejected`." }, "amount": { "type": "number", "description": "Amount in US dollars.", "x-description-ar": "المبلغ بالدولار." }, "currency": { "const": "USD" }, "recharge_balance": { "type": "number", "description": "Shipping balance after the event, in US dollars.", "x-description-ar": "رصيد الشحن بعد الحدث بالدولار." } }, "required": [ "id", "status", "amount", "currency", "recharge_balance" ] }, "PingData": { "type": "object", "description": "Data of the `ping` test message.", "x-description-ar": "بيانات رسالة الاختبار `ping`.", "properties": { "message": { "type": "string", "description": "Localized test text.", "x-description-ar": "نص اختبار مترجم." } }, "required": [ "message" ] }, "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" ] }, "WebhookEventWalletTopup": { "type": "object", "description": "Message body of `wallet.topup`.", "x-description-ar": "جسم الرسالة `wallet.topup`.", "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": "wallet.topup" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WalletTopupData" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventWalletWithdrawal": { "type": "object", "description": "Message body of `wallet.withdrawal`.", "x-description-ar": "جسم الرسالة `wallet.withdrawal`.", "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": "wallet.withdrawal" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WalletWithdrawalData" } }, "required": [ "id", "event", "created_at", "data" ] }, "WebhookEventPing": { "type": "object", "description": "Message body of the `ping` test message.", "x-description-ar": "جسم رسالة الاختبار `ping`.", "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": "ping" }, "created_at": { "type": "string", "description": "Time the event was created (ISO 8601).", "x-description-ar": "وقت إنشاء الحدث (ISO 8601).", "format": "date-time" }, "data": { "$ref": "#/components/schemas/PingData" } }, "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).", "x-description-ar": "مفتاح الـ API مفقود أو غير معروف. `unauthenticated`: لا مفتاح في ترويسة `Authorization: Bearer`. `invalid_key`: المفتاح غير معروف (جُدِّد أو أُلغي أو كُتب خطأً أو هو من نوع آخر).", "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 merchant dashboard." } } } } } } }, "Forbidden": { "description": "Access refused. `account_inactive`: the user or the merchant profile is suspended or missing. `api_not_allowed`: the merchant belongs to a delivery company (the API is for platform merchants only). `plan_feature`: the plan does not include the API (or, for `POST /webhooks`, the webhooks feature), or the merchant has no active plan.", "x-description-ar": "الوصول مرفوض. `account_inactive`: المستخدم أو ملف التاجر موقوف أو غير موجود. `api_not_allowed`: التاجر تابع لشركة توصيل (الواجهة لتجّار المنصة فقط). `plan_feature`: الباقة لا تتضمن الـ API (أو ميزة الويب هوك عند `POST /webhooks`)، أو لا توجد للتاجر باقة فعّالة.", "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 account", "value": { "success": false, "error": { "code": "account_inactive", "message": "Merchant account suspended or not found." } } }, "api_not_allowed": { "summary": "Company merchant", "value": { "success": false, "error": { "code": "api_not_allowed", "message": "Your account belongs to a delivery company — the API is for platform merchant accounts only." } } }, "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": "API key (sk_...)", "description": "Your merchant developer API key in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. Only this header is read; a key in the query string or in the body is ignored. Create the key in the merchant panel (Webhook and API, then the Developer API key). It works only on `/api/v1`: other keys (store integrations, the company key) give `invalid_key`.", "x-description-ar": "مفتاح الـ API الخاص بالمطوّر لديك في ترويسة `Authorization`: `Authorization: Bearer YOUR_API_KEY`. تُقرأ هذه الترويسة فقط؛ والمفتاح في الاستعلام أو في الجسم يُتجاهل. أنشئ المفتاح من لوحة التاجر (الويب هوك والـ API ثم مفتاح API للمطورين). وهو يعمل على `/api/v1` فقط: المفاتيح الأخرى (ربط المتاجر ومفتاح الشركة) تعطي `invalid_key`." } } }, "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 120 per minute, and 60 / 30 / 20 / 10 for `POST /parcels`, `GET /statement`, `POST /webhooks` and `POST /webhooks/{id}/test`; because a request to a route with its own limit is counted by both the group and the route, a route with its own limit allows only about half of it from one IP address. (3) Plan limits per account, 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 على عدّاد واحد مشترك: حدّ المجموعة 120 في الدقيقة، و60 و30 و20 و10 لكل من `POST /parcels` و`GET /statement` و`POST /webhooks` و`POST /webhooks/{id}/test`؛ ولأن الطلب إلى مسار له حدّ خاص يُحسب على المجموعة وعلى المسار معاً، فإن المسار ذا الحدّ الخاص لا يتيح من عنوان IP واحد إلا نحو نصفه. (3) حدود الباقة لكل حساب في الدقيقة وفي اليوم (`429 rate_limited` مع `Retry-After`). وتُذكر الحدود المطبّقة على كل عملية في العملية نفسها." } }