GROperator

جارٍ التحميل…

English

الاصطلاحات

القواعد التالية تسري على كل نقاط النهاية، فتتعلمها مرة واحدة.

كل نقاط النهاية تحت /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) وترد بالغلاف نفسه:

JSON
{
  "items": [],
  "page": 1,
  "pageSize": 25,
  "totalCount": 0,
  "totalPages": 0
}

كرّر الطلب حتى يبلغ page قيمة totalPages. بعض النقاط التي ترجع قائمة قصيرة كاملة (الحالات وأحداث الـ Webhooks وعناوين التاجر) ترجع مصفوفة مباشرة؛ ويبيّن المرجع ذلك.

يحدد Accept-Language لغة message في الأخطاء: العربية افتراضياً، والإنجليزية حين تفضّلها الترويسة (Accept-Language: en). وحين تكون الرسالة إنجليزية يبقى النص العربي في details.messageAr. أما code فلا يتغير، فابنِ منطقك على الرمز لا على النص.

تعمل الحدود على مرحلتين:

  1. لكل عنوان IP للعميل، قبل المصادقة: افتراضياً 600 طلب في الدقيقة. عناوين IPv6 تُجمَّع حسب البادئة /64، فتدوير العناوين داخل بادئة واحدة لا يمنح حصة جديدة. ويمكن للمنصة تغيير هذا السقف.
  2. لكل مستدعٍ موثَّق، بعد المصادقة: افتراضياً 120 طلباً في الدقيقة، تُحسب لكل مفتاح API أو لكل مستخدم عند الدخول بكلمة المرور. والهوية الموثَّقة وحدها تحدد هذه الحصة: ترويسة X-API-Key فاشلة التحقق لا تحددها أبداً.

تسجيل الدخول له حد مستقل: 30 طلباً في الدقيقة لـ login وعشرة لـ refresh لكل عنوان IP (و IPv6 حسب /64).

المرحلتان ترددان بالطريقة نفسها. عند تجاوز الحد يرد 429 rate_limited مع ترويسة Retry-After (بالثواني) و details.retryAfterSeconds:

JSON
{
  "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) فقط، فيمكن تصحيح طلب فاشل وإعادة إرساله بالمفتاح نفسه.
  • إن تعذّر مخزن منع التكرار لحظياً، ينفَّذ الطلب بلا هذه الحماية بدل أن يفشل.
JSON
{
  "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 له الجسم نفسه:

JSON
{
  "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 كما هي: يجب أن يتغير الطلب نفسه أولاً.