المطوّرون

واجهات API والويب هوك.

نظرة عامة على واجهات الـ API: واجهة التاجر وواجهة الشركة واجهتان عامتان للمنصة: واجهة التاجر (مفتاح يبدأ بـ sk) وواجهة شركة التوصيل (مفتاح يبدأ بـ ck)، ومن يحق له استخدامهما، وكيف تعمل الإصدارات، وشكل ردّ JSON الموحّد. مفهوم المطوّرون
المصادقة ومفاتيح الـ API كيف تولّد مفتاح API للتاجر (بادئة sk) أو لشركة التوصيل (بادئة ck) من اللوحة، وترسله في ترويسة Authorization بصيغة Bearer، ومعنى بادئات المفاتيح، وأي خطأ تحصل عليه عند مفتاح ناقص أو خاطئ أو محجوب بالباقة. دليل المطوّرون
مرجع واجهة التاجر API v1 كل نقاط واجهة التاجر (الإصدار v1): الطريقة والمسار والمعاملات مع قواعد التحقق وشكل الرد، مع أمثلة curl وJavaScript وPHP وPython لإنشاء طرد وعرضه وتتبّعه. مرجع المطوّرون
مرجع واجهة شركة التوصيل API v1 كل نقاط واجهة الشركة (الإصدار v1): التجّار والمناديب والطرود وإنشاء الطرد وتعيين المندوب وتحديث الحالة، مع المعاملات والردود وأمثلة curl وJavaScript وPHP وPython. مرجع المطوّرون
الأخطاء ورموز الحالة في واجهات الـ API رموز حالة HTTP وأكواد الأخطاء الحقيقية في واجهتي التاجر والشركة: شكل الخطأ، وترتيب الفحوصات، وجدول بمعنى كل كود وإصلاحه، وأخطاء التحقق 422، وكيف تتعامل معها في برنامجك. مرجع المطوّرون
حدود الطلبات في الـ API كما تُطبَّق فعلياً الحدود التي يطبّقها الكود فعلياً على واجهة الـ API: 60 طلباً في الدقيقة لكل عنوان IP، وحدود المسارات، وحدود الباقة بالدقيقة وباليوم، وشكل ردّ 429. أما الأرقام القديمة في اللوحة (120 و300 لكل مفتاح) فغير مطبّقة، والحدود الفعلية هي لكل عنوان IP إضافة إلى حدود الباقة. مرجع المطوّرون
الصفحات والفلاتر في الـ API كيف تُقسَّم قوائم الـ API إلى صفحات (page و per_page و meta) وأي الفلاتر تعمل فعلاً، ومنها قيم stage في واجهة التاجر: القيمتان processing و awaiting_funds تُتجاهلان بينما ترفض واجهة الشركة القيم المجهولة. مرجع المطوّرون
الويب هوك الصادر: إشعارات فورية لنظامك ما هو الويب هوك الصادر: الأحداث العشرة ورسالة ping، شكل الرسالة والترويسات، تسجيل الرابط من اللوحة أو الـ API، وشروط الرابط (https، المنفذان 443 و8443، عنوان عام)، وميزة الباقة والحد الأقصى. مفهوم المطوّرون
التحقق من توقيع الويب هوك (X-DS-Signature) كيف تتحقق من ترويسة X-DS-Signature بحساب HMAC-SHA256 للنص timestamp.body ثم مقارنة النتيجة بزمن ثابت، مع مثال اختبار وكود يعمل بلغات PHP و Node.js و Python وفحص للطابع الزمني. دليل المطوّرون
إعادة محاولة الويب هوك والإيقاف التلقائي ثماني محاولات بجدول انتظار من دقيقة إلى 24 ساعة، والإيقاف التلقائي بعد 40 فشلاً متتالياً، وسجل الرسائل وإعادة الإرسال، وخطوات التعافي بعد انقطاع نظامك. مرجع المطوّرون
إصدارات الواجهة وإعادة المحاولة الآمنة (Idempotency) رقم الإصدار جزء من المسار فقط (v1 لواجهة التاجر وcompany/v1 لواجهة الشركة)، ولا يوجد دعم لترويسة Idempotency-Key؛ وتعتمد إعادة المحاولة الآمنة على الحقل reference. مرجع المطوّرون
الويب هوك الواردة والاستدعاءات: المتاجر وستور سيريا والشركاء مرجع للطلبات التي تستقبلها المنصة: أحداث متاجر سلة وزد وشوبيفاي وووكومرس، وواجهة ستور سيريا القديمة، واستدعاءات شركات الشحن والدفع، مع التحقق وما يتغيّر. مرجع المطوّرون
توثيق الـ API داخل اللوحة ونقاط النهاية العامة المساعدة ما تحتويه صفحتا توثيق الـ API في لوحتي التاجر والشركة، والحدود ورموز الأخطاء التي يطبّقها الـ API، ونقاط النهاية العامة الصغيرة للمحافظات ورسوم التوصيل والنشرة البريدية والتواصل. مرجع المطوّرون