مرجع API و Webhooks للمطورين

هذا المرجع مخصص للمطور أو مزود ERP/POS الذي يريد ربط نظام خارجي مع متجر على متجرة. إذا كنت تاجرًا وتريد فهم الفكرة العامة وخطة الربط، ابدأ من دليل الربط المبسط: كيف تربط متجرك مع ERP أو POS أو أي نظام خارجي؟

مسؤولية التنفيذ

• متجرة: توفر مفاتيح API، صلاحيات، Webhooks، وتوثيقًا يوضح البيانات المتاحة.

• التاجر: يحدد السيناريو المطلوب: الطلبات، المخزون، الأسعار، المنتجات، نقاط العملاء، أو حالات الطلب.

• المطور أو مزود النظام الخارجي: يبني الربط داخل ERP/POS أو عبر وسيط مثل n8n أو Make أو Power Automate أو خادم مخصص، ويختبر المزامنة ويتابع الأخطاء.

الرابط الأساسي

استخدم دومين المتجر نفسه، ثم أضف مسار API:

https://YOUR_STORE_DOMAIN/api/v1/

مثال:

https://example.com/api/v1/orders

المصادقة

الطريقة المفضلة هي إرسال مفتاح API في ترويسة Authorization:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

ويوجد دعم لاستخدام المفتاح كمعامل query عند الحاجة:

https://YOUR_STORE_DOMAIN/api/v1/orders?api_key=YOUR_API_KEY

مهم: لا ترسل مفاتيح API في محادثات عامة أو في الواجهة الأمامية للمتجر. أنشئ مفتاحًا مستقلًا لكل نظام خارجي حتى يمكن تعطيله وحده عند الحاجة.

إنشاء مفتاح API من لوحة التحكم

1. افتح لوحة التحكم.

2. اذهب إلى إعدادات API أو مفاتيح API.

3. أنشئ مفتاحًا جديدًا باسم واضح مثل: Odoo Integration أو POS Sync.

4. اختر أقل صلاحيات مطلوبة للسيناريو فقط.

5. سلّم المفتاح للطرف المنفذ بطريقة آمنة.

الصلاحيات المتاحة

الصلاحية	متى تستخدم؟
orders.read	قراءة الطلبات وتفاصيلها.
orders.update	تحديث حالة الطلب أو إضافة تعليق.
products.read	قراءة المنتجات والأسعار والمخزون.
products.create	إنشاء منتجات جديدة من النظام الخارجي.
products.update	تحديث بيانات المنتجات.
stock.update	تحديث كمية المخزون بالمعرف أو SKU أو UPC.
customers.read	قراءة بيانات العميل أو رصيد النقاط.
customers.update	إضافة أو تعديل نقاط العميل.
abandonedcarts.read	استخدمها فقط إذا كان سيناريو السلات المتروكة متاحًا ومفعّلًا في متجرك.

أهم نقاط API

هذه أهم المجموعات التي يحتاجها مزود ERP/POS عادة. تأكد من اختبارها على متجر تجريبي أو بيانات محدودة قبل التشغيل الكامل.

الطلبات

Method	Endpoint	الصلاحية	الاستخدام
GET	/orders	orders.read	قراءة قائمة الطلبات مع فلاتر مثل الصفحة والحالة والتاريخ.
GET	/orders/{order_id} أو /orders/get?order_id={order_id}	orders.read	قراءة طلب واحد وتفاصيله.
PUT	/orders/status/update?order_id={order_id}	orders.update	تحديث حالة الطلب أو إضافة تعليق أو إرسال إشعار للعميل.

المنتجات والمخزون

Method	Endpoint	الصلاحية	الاستخدام
GET	/products	products.read	قراءة المنتجات مع الصفحة والبحث والتصنيف.
GET	/products/get?product_id={product_id}	products.read	قراءة منتج محدد.
POST	/products/create	products.create	إنشاء منتج جديد.
PUT	/products/update?product_id={product_id}	products.update	تحديث بيانات منتج.
PUT	/stock/update-by-id?product_id={product_id}	stock.update	تحديث المخزون بمعرف المنتج.
PUT	/stock/update-by-sku?sku={sku}	stock.update	تحديث المخزون عبر SKU، وهو الأفضل عادة للربط مع ERP/POS.
PUT	/stock/update-by-upc?upc={upc}	stock.update	تحديث المخزون عبر UPC أو Barcode.

نقاط العملاء

Method	Endpoint	الصلاحية	الاستخدام
POST	/customers/points/add	customers.update	إضافة نقاط للعميل.
GET	/customers/points/balance	customers.read	قراءة رصيد نقاط العميل.

أمثلة سريعة

قراءة الطلبات

curl -X GET "https://YOUR_STORE_DOMAIN/api/v1/orders?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

تحديث مخزون عبر SKU

curl -X PUT "https://YOUR_STORE_DOMAIN/api/v1/stock/update-by-sku?sku=SKU-001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 25,
    "operation": "set"
  }'

تحديث حالة طلب

curl -X PUT "https://YOUR_STORE_DOMAIN/api/v1/orders/status/update?order_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_status_id": 5,
    "comment": "تم شحن الطلب",
    "notify": true
  }'

Webhooks: متى تستخدمها؟

استخدم Webhook عندما تريد أن ترسل متجرة إشعارًا فوريًا إلى نظام خارجي عند حدوث حدث داخل المتجر. مثال: عند إنشاء طلب جديد، يرسل Webhook البيانات إلى n8n أو خادم ERP، ثم يستخدم النظام الخارجي API إذا احتاج تفاصيل إضافية أو تحديثات لاحقة.

الأحداث المتاحة

Event	متى يحدث؟
order_created	عند إنشاء طلب جديد.
order_status_updated	عند تحديث حالة الطلب.
stock_update	عند تحديث المخزون.
product_added	عند إضافة منتج جديد.
product_updated	عند تحديث منتج.
notify_when_available_available	عند توفر منتج طلب العميل إشعاره عند توفره.
abandoned_cart_reminder_due	عندما تصبح السلة المتروكة مؤهلة للتذكير.

إضافة Webhook

1. افتح صفحة Webhooks من لوحة التحكم.

2. أضف رابط الاستقبال في النظام الخارجي، مثال: https://erp.example.com/matjrah/webhook.

3. اختر الحدث المطلوب مثل order_created.

4. إذا كان النظام الخارجي يحتاج ترويسة مصادقة، أضف اسم الترويسة وقيمتها.

5. استخدم زر الاختبار قبل الاعتماد.

شكل Webhook المتوقع

قد تختلف البيانات حسب الحدث. تعامل مع الحقول باعتبارها قابلة للتوسع، ولا تفترض أن كل حدث يحمل نفس التفاصيل.

{
  "event": "order_created",
  "store_id": "123",
  "created_at": "2026-06-17T10:00:00Z",
  "data": {
    "order_id": 12345
  }
}

في بعض السيناريوهات يكون Webhook تنبيهًا فقط. عندها يستخدم النظام الخارجي API لجلب تفاصيل الطلب أو المنتج ثم يكمل المعالجة.

نمط الربط المقترح

1. Push: متجرة ترسل Webhook عند إنشاء الطلب.

2. Pull: النظام الخارجي يستدعي API لجلب تفاصيل إضافية إذا احتاج.

3. Sync back: النظام الخارجي يحدث المخزون أو حالة الطلب في متجرة عبر API.

قواعد مهمة قبل التشغيل

• استخدم SKU أو Barcode لربط المنتجات، وليس اسم المنتج.

• حدد مصدر الحقيقة لكل بيانات: السعر، المخزون، اسم المنتج، حالة الطلب.

• جهز معالجة تكرار Webhook حتى لا يتكرر إنشاء الطلب في ERP.

• سجل كل طلب API أو Webhook فاشل مع سبب الفشل.

• نفذ retry بحدود واضحة بدل إعادة المحاولة بلا نهاية.

• اختبر الربط على 5 منتجات وطلبين قبل تشغيل كل المنتجات والطلبات.

• راجع الصلاحيات دوريًا وأوقف أي مفتاح غير مستخدم.

نص جاهز يرسله التاجر للمطور

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

متى تستخدم وسيطًا مثل n8n أو Make؟

• Make: مناسب للسيناريوهات البسيطة مثل إرسال الطلب إلى Google Sheets أو إشعار داخلي.

• n8n: مناسب للربط المرن مع Odoo أو API مخصص، خصوصًا إذا كان لديك فريق تقني.

• Power Automate: مناسب إذا كان النظام الخارجي من بيئة Microsoft مثل Dynamics أو Business Central.

• خادم مخصص: الأفضل للربط الحساس: فروع متعددة، مخزون لحظي، طلبات كثيرة، أو حاجة قوية للتتبع وإعادة المحاولة.

الخلاصة

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