واجهة API وWebhooks في تنسيق: اربط متجرك بأنظمتك

مع نمو نشاطك تظهر أنظمة أخرى: برنامج مستودع، أو نظام إدارة عملاء، أو لوحة تقارير، أو جدول يتابعه فريق المبيعات. وبدل نسخ الطلبات والحجوزات يدوياً من موقعك إلى هذه الأنظمة، تربطها واجهة تنسيق البرمجية وWebhooks مباشرة. هذا المقال لصاحب النشاط ولمبرمجه معاً.

قبل أن تبرمج: ما المربوط جاهزاً؟

كثير من الربط موجود في تنسيق دون أي برمجة، فتأكد منه أولاً:

• الدفع: ميسر (البطاقات ومدى وApple Pay)، وتابي وتمارا، من حساباتك أنت.
• الشحن: بوالص أرامكس وسمسا وتتبعها.
• الفوترة والمحاسبة: فواتير الزكاة والضريبة مع رمز QR والربط بمنصة فاتورة، وفواتير في دفترة أو قيود أو وافق لكل طلب مؤكد.
• التسويق: إعلانات جوجل، وبكسلات ميتا وتيك توك وسناب شات، وملفات المنتجات لمتاجرها.
• المواعيد: تقويم Google وZoom.

إن كان ما تحتاجه هنا فلا داعي للواجهة البرمجية. وإن كان نظامك خاصاً بك، فتابع القراءة.

ماذا تفعل الواجهة البرمجية؟

واجهة REST تعيد JSON، وموثقة بصيغة OpenAPI ليقرأها مبرمجك أو أدواته. تتيح:

• المواقع: قائمة المواقع التي يصل إليها المفتاح.
• المنتجات: قراءتها، وإنشاء منتج جديد، وتعديل منتج قائم.
• الطلبات: قراءتها بتفاصيلها، وتحديث حالة الطلب، مثل تحويله إلى «تم الشحن» حين يخرج من مستودعك.
• العملاء: عملاء المتجر.
• الحجوزات وردود النماذج: للقراءة.

النتائج تأتي في صفحات من ٥٠ عنصراً، ولكل مفتاح حد لعدد الطلبات في الدقيقة.

مفاتيح بصلاحيات تختارها

لا يحتاج كل نظام إلى كل شيء. عند إنشاء المفتاح تختار:

1. المواقع التي يعمل عليها، موقعاً واحداً أو أكثر.
2. الإجراءات المسموحة: قراءة المنتجات، أو تعديلها، أو قراءة الطلبات، أو تحديثها، وهكذا.
3. مدة الصلاحية إن أردت: ٣٠ أو ٩٠ أو ٣٦٥ يوماً.

والمفتاح لا يتجاوز صلاحيات من أنشأه أبداً؛ فعضو الفريق الذي لا يرى الطلبات لا يستطيع أن يمنح مفتاحاً يقرؤها. ويمكنك إلغاء أي مفتاح في أي وقت.

Webhooks: نظامك يعرف فور حدوث الشيء

بدل أن يسأل نظامك تنسيق كل دقيقة «هل من جديد؟»، يرسل تنسيق إليه طلباً فور وقوع أحد هذه الأحداث:

• order.created: طلب جديد.
• order.status_changed: تغيّرت حالة طلب.
• booking.created: حجز جديد.
• form.submitted: رد جديد على نموذج.
• product.updated: تعديل منتج.

تضيف رابط نظامك وتختار الأحداث، لموقع واحد أو لكل مواقع حسابك. وكل طلب موقّع بترويسة Tansik-Signature (HMAC-SHA256 بسرّ خاص بالرابط)، ليتحقق نظامك أنه من تنسيق فعلاً. وإن فشل الاستلام تعيد تنسيق المحاولة حتى ست مرات على مدى ساعات. ومن اللوحة ترسل طلب تجربة، وترى سجل الإرسال، وتعيد إرسال أي طلب، وتغيّر السرّ متى شئت.

أمثلة عملية

• متجر ومستودع: يصل order.created إلى نظام المستودع فيبدأ التجهيز، ثم يحدّث المستودع حالة الطلب عبر الواجهة، فيرى العميل التحديث في صفحة طلبه.
• عيادة ونظام إدارة عملاء: كل booking.created يصبح سجلاً لدى فريق الاستقبال.
• شركة خدمات: كل form.submitted من نموذج «اطلب عرض سعر» يصل إلى جدول المبيعات.
• وكالة: تجمع طلبات مواقع عملائها في لوحة تقارير واحدة. اقرأ دليل الوكالات.

ابدأ

الواجهة البرمجية وWebhooks متاحة في الباقات التي تشملها، فاطلع على الباقات. بعد ذلك أنشئ مفتاحاً من لوحة التحكم، وأعطِه لمبرمجك مع توثيق OpenAPI، وأضف أول Webhook. وإن كنت تبدأ متجرك الآن، فابدأ بمقال المتجر الإلكتروني في السعودية.

أسئلة شائعة