مفاتيح الربط (API) و Webhooks

تتيح لك مفاتيح الربط توصيل متجرك ببرنامج حسابات أو نظام شحن أو مساعد ذكاء اصطناعي، بصلاحيات تحددها أنت لكل مفتاح، ويمكنك إلغاؤه في أي وقت. وبدل أن يسأل التطبيق متجرك باستمرار عن الجديد، يمكنك أيضًا جعل المتجر يرسل إليه الأحداث لحظة وقوعها عبر Webhooks.

المتطلبات

• إنشاء المفاتيح متاح لصاحب المتجر وحده، ولا يتاح لأي عضو في الفريق ولو كانت صلاحياته كاملة، ولا أثناء دخول الدعم الفني على حسابك.
• مفاتيح الربط متاحة في جميع الباقات، أما Webhooks فهي في باقة برو فقط.

الخطوات: إنشاء مفتاح

1. من لوحة التحكم افتح صفحة الإعدادات، ثم اضغط بطاقة مفاتيح الربط (API). تجد في الصفحة رابط الـ API.
2. اكتب اسم المفتاح ليذكّرك بمن يستخدمه، مثل «نظام الشحن».
3. اختر مدة المفتاح: بلا انتهاء، أو 30 يومًا، أو 90 يومًا، أو سنة.
4. اختر كل الصلاحيات، أو حدّد لكل قسم ما يلزم: قراءة، إضافة وتعديل، حذف (وفي الطلبات «تغيير حالة الطلب» أيضًا). الأقسام: المنتجات، الطلبات، العملاء، المدونة، الشحن، الإعدادات، الملفات والصور، المحفظة، واتساب، محادثات الدعم، وWebhooks.
5. اضغط إنشاء المفتاح، وانسخه فورًا وضعه في التطبيق. يرسل التطبيق المفتاح مع كل طلب في الترويسة Authorization: Bearer <المفتاح>.

الخطوات: إضافة Webhook

1. من صفحة الإعدادات اضغط بطاقة Webhooks.
2. اكتب العنوان الذي يستقبل الأحداث، ويجب أن يكون https وعلى الإنترنت العام، ثم اختر الأحداث المطلوبة: طلب جديد، تغيّر حالة الطلب، تغيّر حالة الدفع، إنشاء شحنة، إلغاء طلب، منتج جديد أو معدّل أو محذوف، عميل جديد أو معدّل.
3. اترك المفتاح السري فارغًا ليولّده النظام، أو اكتب مفتاحك. اضغط إضافة، وانسخ المفتاح السري فورًا فهو يظهر مرة واحدة.
4. اضغط إرسال تجربة للتأكد من أن تطبيقك يستقبل الحدث ويرد عليه.

ملاحظات

• يظهر المفتاح مرة واحدة: إذا فُقد فألغِه وأنشئ مفتاحًا جديدًا.
• «كل الصلاحيات» لا تعني كل شيء: هذا المفتاح لا يدير المفاتيح ولا فريق العمل ولا تسجيل الدخول أبدًا.
• الحد الأقصى: 20 مفتاحًا، و20 webhook لكل متجر.
• الإلغاء فوري: يوقف زر إلغاء المفتاح في الحال، وينقطع أي تطبيق يستخدمه. وتعرض القائمة تاريخ إنشاء كل مفتاح وآخر استخدام له وموعد انتهائه.
• توقيع Webhooks: يصل كل حدث بالترويستين X-Webhook-Timestamp وX-Signature للتأكد من أنه صادر من متجرك. وخطوات التحقق (بلغتي PHP وNode.js) مكتوبة أسفل صفحة Webhooks وتخص المبرمج. والترويسة X-Webhook-Id هي رقم الحدث وتثبت عند إعادة الإرسال، فتجاهل ما عالجته من قبل.
• عند تعذّر وصول الحدث: تُعاد المحاولة بفواصل (دقيقة، ثم 5 دقائق، ثم 15 دقيقة، ثم ساعة، ثم 3 ساعات، ثم 6 ساعات). فإذا استمر الفشل 24 ساعة يتوقف الـ webhook تلقائيًا ويظهر «متوقف»، فأصلح العنوان وشغّله بزر تشغيل. وتحت كل webhook سجل بآخر 50 محاولة.
• إذا خرج المتجر من باقة برو توقف إرسال Webhooks.
• تنبيه: يمنح المفتاح صاحبه صلاحيات حقيقية على متجرك. أعطه أقل ما يكفي من الصلاحيات، وحدّد له مدة إذا كان التطبيق مؤقتًا، ولا ترسله في رسالة مفتوحة، وألغِه فورًا إذا اشتبهت في تسريبه.