الاصطلاحات
القواعد التالية تسري على كل نقاط النهاية، فتتعلمها مرة واحدة.
كل نقاط النهاية تحت /api/public/v1. الإصدار جزء من المسار. ووثيقة OpenAPI المولَّدة تُقدَّم مباشرة أيضاً على /api/public/v1/openapi.json. اكتب عملاءك البرمجيين بحيث يتجاهلون حقول الرد التي لا يعرفونها، فلا تكسرهم الحقول الاختيارية الجديدة.
- الطلبات والردود بصيغة JSON ترميز UTF-8. أرسل
Content-Type: application/jsonمع الطلبات التي لها جسم. والاستثناء الوحيد بوليصة الشحن وهي ملف PDF. - أسماء الحقول بنمط
camelCase. - القيم المعدّدة (Enums) نصوص لا أرقام:
"serviceType": "delivery"و"serviceTier": "sameDay"و"status": "outForDelivery". قيم كل Enum في النماذج وفي جداول الحقول بالمرجع. - المعرّفات UUID، عدا رقم التتبع فهو نص يعرّف الشحنة في كل المسارات.
- الأسماء متاحة باللغتين: كائنات الأماكن والحالات تحمل
nameArوnameEn(أوstatusLabelArوstatusLabelEn). اختر ما يناسب واجهتك؛ لا تحتاجAccept-Languageلذلك.
- اللحظات بصيغة ISO 8601 بتوقيت UTC، مثل
2026-01-15T09:30:00Z. حوّلها إلى المنطقة الزمنية المحلية في واجهتك. estimatedDeliveryDateتاريخ بلا وقت بالصيغةyyyy-MM-dd.- فلاتر التاريخ مثل
createdFromوcreatedToتقبل صيغة ISO 8601 نفسها.
نقاط القوائم تقبل page (يبدأ من 1 والافتراضي 1) و pageSize (الافتراضي 25 والحد الأقصى 100؛ القيم الأكبر تُقصّ إلى 100) وترد بالغلاف نفسه:
{
"items": [],
"page": 1,
"pageSize": 25,
"totalCount": 0,
"totalPages": 0
}كرّر الطلب حتى يبلغ page قيمة totalPages. بعض النقاط التي ترجع قائمة قصيرة كاملة (الحالات وأحداث الـ Webhooks وعناوين التاجر) ترجع مصفوفة مباشرة؛ ويبيّن المرجع ذلك.
يحدد Accept-Language لغة message في الأخطاء: العربية افتراضياً، والإنجليزية حين تفضّلها الترويسة (Accept-Language: en). وحين تكون الرسالة إنجليزية يبقى النص العربي في details.messageAr. أما code فلا يتغير، فابنِ منطقك على الرمز لا على النص.
تعمل الحدود على مرحلتين:
- لكل عنوان IP للعميل، قبل المصادقة: افتراضياً 600 طلب في الدقيقة. عناوين IPv6 تُجمَّع حسب البادئة /64، فتدوير العناوين داخل بادئة واحدة لا يمنح حصة جديدة. ويمكن للمنصة تغيير هذا السقف.
- لكل مستدعٍ موثَّق، بعد المصادقة: افتراضياً 120 طلباً في الدقيقة، تُحسب لكل مفتاح API أو لكل مستخدم عند الدخول بكلمة المرور. والهوية الموثَّقة وحدها تحدد هذه الحصة: ترويسة
X-API-Keyفاشلة التحقق لا تحددها أبداً.
تسجيل الدخول له حد مستقل: 30 طلباً في الدقيقة لـ login وعشرة لـ refresh لكل عنوان IP (و IPv6 حسب /64).
المرحلتان ترددان بالطريقة نفسها. عند تجاوز الحد يرد 429 rate_limited مع ترويسة Retry-After (بالثواني) و details.retryAfterSeconds:
{
"code": "rate_limited",
"message": "Too many requests. Retry after the time given in the Retry-After header.",
"status": 429,
"details": {
"retryAfterSeconds": 23,
"messageAr": "طلبات كثيرة جداً. أعد المحاولة بعد المدة الموضحة في ترويسة Retry-After."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}انتظر المدة المذكورة ثم أعد المحاولة. وللبقاء بعيداً عن الحد: خزّن القوائم قليلة التغير (الدول والمدن والأحياء والحالات)، وفضّل الـ Webhooks على الاستعلام المتكرر، ووزّع المهام الكبيرة على الزمن.
للأرقام حدود عليا تطابق ما يستطيع النظام تخزينه؛ والقيمة الأكبر تُرفض بـ 400 validation_failed ورسالة مثل Weight is too large. على ذلك الحقل:
| الحقل | المسموح |
|---|---|
parcel.weightKg |
أكبر من 0 وحتى 9,999,999 |
parcel.lengthCm وwidthCm وheightCm |
أكبر من 0، وكل منها حتى 100,000 |
parcel.pieces |
من 1 إلى 1000 |
parcel.declaredValue وpayment.codAmount |
0 أو أكثر وحتى 999,999,999,999 |
النقاط POST /shipments و POST /merchants و POST /merchants/{id}/addresses تقبل ترويسة اختيارية Idempotency-Key (والبديل X-Idempotency-Key). تجعل إعادة المحاولة آمنة: إن انتهت مهلة طلب ولا تدري هل أُنشئ، أعد إرساله بالمفتاح نفسه.
- المفتاح من 1 إلى 128 محرفاً قابلاً للطباعة بلا مسافات. استخدم قيمة ثابتة من بياناتك مثل
order-1001، لا قيمة عشوائية جديدة في كل محاولة. - المفتاح نفسه مع الطلب نفسه خلال 24 ساعة يرجع الرد الأول مع الترويسة
Idempotent-Replayed: true. ولا تُنشأ شحنة ثانية. - المفتاح نفسه مع جسم مختلف يرد بـ
409 idempotency_key_reused. - المفاتيح مقيّدة بشركتك وبالاعتماد (مفتاح API أو مستخدم). تُحفظ الردود الناجحة (2xx) فقط، فيمكن تصحيح طلب فاشل وإعادة إرساله بالمفتاح نفسه.
- إن تعذّر مخزن منع التكرار لحظياً، ينفَّذ الطلب بلا هذه الحماية بدل أن يفشل.
{
"code": "idempotency_key_reused",
"message": "This Idempotency-Key was already used with a different request body.",
"status": 409,
"details": {
"messageAr": "تم استخدام مفتاح منع التكرار مع طلب مختلف."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}كل رد غير 2xx له الجسم نفسه:
{
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"details": { "errors": { "recipient.phone": ["Recipient phone is required."] } },
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}| الحقل | المعنى |
|---|---|
code |
رمز ثابت للبرامج. رموز عامة مثل unauthorized، أو رموز أعمال بالشكل area.reason مثل shipment.not_found |
message |
نص مقروء باللغة الموضحة أعلاه. اعرضه للمطوّر، لا تعرضه كما هو للعميل النهائي |
status |
حالة HTTP مكررة |
details |
بيانات إضافية تعتمد على الرمز، أو null |
traceId |
اذكره عند التواصل مع الدعم |
| الحالة | متى |
|---|---|
400 |
الجسم أو الاستعلام غير صالح: validation_failed، ويربط details.errors كل مسار حقل (مثل recipient.phone) برسائله. وأيضاً ambiguous_credentials حين يحمل الطلب رمز Bearer ومفتاح API معاً |
401 |
الاعتماد مفقود أو خاطئ: unauthorized |
403 |
الاعتماد بلا نطاق (forbidden مع details.requiredScope)، أو قناة الـ API متوقفة (channel_disabled)، أو الشركة موقوفة (tenant_blocked) |
404 |
المورد غير موجود، مثل shipment.not_found |
409 |
تعارض، مثل idempotency_key_reused أو merchant.possible_duplicate |
422 |
الطلب سليم الصياغة لكن قاعدة عمل أو مكاناً فشل، مثل shipment.cannot_cancel أو geo_city_not_found |
429 |
طلبات كثيرة: rate_limited |
500 |
خطأ غير متوقع: internal_error |
| الرمز | ما يجب فعله |
|---|---|
unauthorized |
افحص الترويستين (أو رمز Bearer). أنشئ مفتاحاً جديداً إن كان القديم ملغى أو منتهياً |
ambiguous_credentials |
أرسل إما Authorization: Bearer أو X-API-Key مع X-API-Secret، لا الاثنين معاً |
forbidden |
أضف النطاق المذكور في details.requiredScope إلى المفتاح |
channel_disabled |
اطلب من المنصة منح القناة ومن مدير الشركة تشغيلها |
validation_failed |
صحّح كل حقل في details.errors وأعد الإرسال |
rate_limited |
انتظر Retry-After ثم أعد المحاولة |
idempotency_key_reused |
استخدم مفتاحاً جديداً لطلب جديد |
geo_*_not_found و geo_*_ambiguous |
دع المستخدم يختار من details.candidates، راجع الأماكن بالاسم |
business_rule_violation |
اقرأ message؛ البيانات تخالف قاعدة بلا رمز مستقل |
الفهرس الكامل في مرجع الأخطاء.
أعد المحاولة عند أخطاء الشبكة و 429 (بعد Retry-After) و 5xx، بتأخير متزايد، ومع Idempotency-Key نفسه في عمليات الإنشاء. لا تعد محاولة بقية أخطاء 4xx كما هي: يجب أن يتغير الطلب نفسه أولاً.