نظرة عامة على واجهات الـ API: واجهة التاجر وواجهة الشركة

الغرض#

للمنصة واجهتان عامتان من نوع REST لربط أنظمتك بها (نظام ERP أو تطبيق أو متجر مخصّص). تتبادلان بيانات JSON، وتتعرّفان إليك بمفتاح API يُرسل بصيغة Bearer، وتردّان بغلاف موحّد. وتجد تفاصيل نقاط النهاية في مرجع واجهة التاجر ومرجع واجهة شركة التوصيل.

الواجهتان العامتان#

العنوان الكامل هو نطاق المنصة مع المسار الأساسي. وفي كل من هاتين الصفحتين زر توثيق الـ API، وتعرض اللوحة عنوان Base URL الدقيق (في أسفل بطاقة مفتاح الـ API للشركات، وفي قسم «البداية السريعة» من صفحة التوثيق للتجّار). وهناك مسارات أخرى تحت /api غير موثّقة هنا: واجهة تطبيقات الجوال وويب هوك المتاجر للاستخدام الداخلي فقط، ويوجد مسار يعتمد على مفتاح (POST /api/parcel/create-with-security مع X-Platform) تستعمله منصات المتاجر والمنصات المخصّصة. وللتكاملات الجديدة استخدم /api/v1 أو /api/company/v1.

من يستطيع استخدامها؟#

• واجهة التاجر: تجّار المنصة. التاجر التابع لشركة توصيل لا يستطيع استخدامها: تعرض اللوحة تنبيهاً وتعيده إلى لوحة التحكم، ويردّ الـ API بالرمز 403 وكود الخطأ api_not_allowed. أما التاجر الذي يملك شركة توصيل داخلية فيبقى تاجر منصة.
• واجهة الشركة: يُنشئ أدمن الشركة المفتاح. تحتاج الشركة إلى اشتراك فعّال وإلى باقة تتضمن ميزة الـ API، وتُستثنى من الشرطين الشركات التابعة للمنصة والمملوكة لتاجر.
• الباقات: عندما تكون باقات التجّار مستخدمة، يحتاج التاجر إلى باقة فعّالة تتضمن ميزة الـ API. تبدأ باقة التاجر الجديدة وميزة الـ API غير مفعّلة إلى أن يفعّلها السوبر أدمن، وتبدأ باقة الشركة الجديدة وهي مفعّلة. والباقة القديمة التي لم تُضبط ميزاتها تسمح بكل شيء.

كيف تعمل الإصدارات؟#

• رقم الإصدار جزء من المسار. الواجهتان على v1، ولا توجد ترويسة للإصدار ولا إصدار آخر.
• يذكر توثيق واجهة التاجر داخل اللوحة أن حقولاً جديدة قد تُضاف دون إنذار (تجاهل ما لا تعرفه) وأن أي تغيير يكسر التوافق سيصدر بإصدار جديد، أما توثيق واجهة الشركة فيذكر فقط أن حقولاً جديدة قد تُضاف وأن ما لا تعرفه يُتجاهل.
• ابنِ منطقك على stage في الطرد (مجموعة مبسّطة ثابتة من الحالات)، واستخدم status_code وstatus_label للحالة الدقيقة وللعرض، وتفرّع حسب error.code لا حسب نص error.message.

غلاف الرد#

كل ردّ من الواجهتين يأتي بأحد شكلين.

{ "success": true, "data": { "id": 1 }, "meta": { "page": 1, "per_page": 20, "total": 132, "last_page": 7 } }

{ "success": false, "error": { "code": "validation_failed", "message": "...", "fields": { "customer_phone": ["..."] } } }

• يظهر meta في القوائم المقسّمة إلى صفحات فقط (page وper_page وtotal وlast_page): في واجهة التاجر GET /parcels وGET /statement، وفي واجهة الشركة GET /merchants وGET /parcels. أما بقية القوائم فمصفوفة عادية في data. ولا توجد روابط links.
• error.code كود قصير بصيغة snake_case: اعتمد عليه في برنامجك لا على نص error.message. الرسالة بالعربية افتراضياً وبالإنجليزية مع Accept-Language: en.
• يظهر fields في معظم أخطاء التحقق (وبعض أخطاء واجهة الشركة تحمل message فقط)، وretry_after مع rate_limited، وreference في أخطاء الخادم.
• الأوقات في الطرود والأحداث وسطور كشف الحساب وروابط الويب هوك بصيغة ISO 8601 مع فرق التوقيت عن UTC. أما انتهاء الباقة في GET /me فنص عادي: YYYY-MM-DD للتاجر وYYYY-MM-DD HH:MM:SS للشركة. والمبالغ داخل كائن الطرد بالدولار الأمريكي.
• أرسل دائماً Accept: application/json. الأخطاء التي تقع قبل وصول الطلب إلى كود الـ API (مسار غير موجود، أو طريقة HTTP خاطئة، أو تجاوز الحد العام للطلبات أو حدود المسارات) تأتي بتنسيق مختلف هو {"message": "..."}، أو بصفحة HTML بدون الترويسة.

ابدأ بسرعة#

1. تأكد أن باقتك تتضمن الـ API

   للتاجر: تعرض «الباقة والاشتراك» ميزات كل باقة، ومنها بند الـ API مع حدوده. وللشركة: تعرض بطاقة «باقة الشركة» في صفحة «الربط والـ API» ميزات باقتك.

2. ولّد مفتاح API

   اتبع صفحة «المصادقة ومفاتيح الـ API».

3. استدعِ نقطة الحساب

   تُرجع GET /me بيانات حسابك وتثبت أن المفتاح يعمل. وفي واجهة الشركة استخدم /api/company/v1/me.

   bashنسخ

   curl https://YOUR_DOMAIN/api/v1/me \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"
   

4. أنشئ الطرود وتابعها

   راجع مرجعَي الواجهتين.

1234

1. مفاتيح الـ API الحالية (تُعرض مخفية)
2. اسم المنصة أو النظام الذي ستربطه
3. أنشئ مفتاحاً جديداً
4. افتح توثيق الـ API

أخطاء شائعة#

• نوع مفتاح خاطئ. مفتاح ck_ على /api/v1، أو مفتاح sk_ أُنشئ لمنصة متاجر، يعطي 401 والكود invalid_key.
• المفتاح خارج الترويسة. المفتاح في الرابط أو في جسم الطلب يُهمَل: 401 والكود unauthenticated.
• الاعتماد على حدّ المسار وحده (120 أو 300 طلب في الدقيقة). يُطبَّق أيضاً الحد العام: 60 طلباً في الدقيقة لكل عنوان IP.
• وضع المفتاح داخل تطبيق جوال أو كود متصفح. أبقِه على خادمك.

الحدود والصلاحيات#

• حدود الطلبات. تُطبَّق ثلاث طبقات: حدّ عام قدره 60 طلباً في الدقيقة لكل عنوان IP على كل طلب تحت /api؛ وحدود المسارات (واجهة التاجر 120 في الدقيقة، و60 لـ POST /parcels، و30 لـ GET /statement؛ وواجهة الشركة 300 في الدقيقة، و120 لـ POST /parcels)، وتُحتسب لكل عنوان IP على عدّاد واحد مشترك، فطلب POST /parcels يُحسب على حدّ المجموعة وعلى حدّه الخاص معاً، وأرقام المسارات ليست حصصاً منفصلة (وعملياً، لأن كل طلب يُحسب مرتين، لا يستطيع عنوان IP واحد إنشاء أكثر من نحو 30 طرداً في الدقيقة في واجهة التاجر ونحو 60 في واجهة الشركة، وأقل من ذلك إن أرسل طلبات أخرى في الدقيقة نفسها)؛ وحدود الباقة لكل حساب (في الدقيقة وفي اليوم). عند بلوغ حدود الباقة يأتي 429 مع rate_limited وقيمة retry_after بالثواني وترويسة Retry-After، وعند بلوغ الحد العام أو حدود المسارات يأتي 429 مع {"message": "Too Many Attempts."}. خطّط على أساس 60 طلباً كحدّ أقصى في الدقيقة لكل عنوان IP.
• الويب هوك. يُضبط إرسال إشعارات الويب هوك إلى نظامك بشكل منفصل: عبر نقاط /webhooks في واجهة التاجر، أو من اللوحة؛ وليس في واجهة الشركة نقاط ويب هوك (استخدم اللوحة).