ربط متجر مخصص أو أي منصة أخرى عبر Webhook
استقبل طلبات أي متجر (موقعك الخاص أو منصة أخرى) كفواتير بيع بإرسال الطلب إلى رابط خاص بصيغة JSON
إن كان متجرك على منصة غير سلة وزد وأمازون، أو موقعًا خاصًا مبرمجًا لك، يمكنك ربطه بدفّة عبر Webhook: يرسل متجرك كل طلب إلى رابط خاص، فيحوله دفّة إلى فاتورة بيع ويخصم المخزون. هذا المقال موجّه لك ولمبرمج متجرك.
قبل أن تبدأ
- صلاحية بوابات الدفع وربط المتاجر.
- مبرمج أو إضافة في متجرك تستطيع إرسال طلب HTTP من نوع POST عند إنشاء الطلب.
- أكواد المنتجات (SKU) في متجرك مطابقة لـ كود أو باركود الأصناف في دفّة.
الخطوة 1: إنشاء الربط
- افتح الإعدادات ← التكاملات والفوترة الإلكترونية ثم تبويب المتاجر.
- في ربط متجر جديد اضغط متجر آخر (Webhook).
- املأ اسم المتجر واختر المستودع والفرع والعميل الافتراضي وحساب تحصيل الطلبات المدفوعة وصنف الشحن.
- اضغط حفظ.
- في بطاقة الربط والمزامنة انسخ رابط استقبال الطلبات لحظيًا (Webhook) وسلّمه لمبرمج المتجر.
الخطوة 2: صيغة الطلب (للمبرمج)
يرسل المتجر طلب POST إلى الرابط، بمحتوى JSON بترميز UTF-8. مثال لطلب فيه صنف واحد:
{"id": "10452", "number": "WEB-10452", "paid": true, "customer": {"name": "محمد أحمد", "mobile": "0551234567", "email": "m@example.com", "city": "جدة"}, "items": [{"sku": "LD-A2502", "name": "شاحن سريع", "qty": 2, "price": 57.50}], "shipping": 23, "discount": 0, "total": 138}
| الحقل | الشرح |
|---|---|
| id | معرّف الطلب في المتجر (إلزامي ولا يتكرر) |
| number | رقم الطلب الظاهر للعميل |
| paid | true إن كان مدفوعًا إلكترونيًا، false للدفع عند الاستلام |
| customer | الاسم والجوال (يُستخدم الجوال لإيجاد العميل أو إنشائه) والبريد والمدينة |
| items | الأصناف: sku والكمية qty (أو quantity) وسعر الوحدة price |
| shipping / discount | رسوم الشحن والخصم |
| status | اختياري. القيمة cancelled تلغي الطلب |
يمكن أيضًا إرسال الطلب داخل مفتاح order، مثل {"order": {...}}.
الرد من دفّة
يرد دفّة بـ JSON يحتوي ok و status (imported عند نجاح إنشاء الفاتورة، أو error) ومعرّف الفاتورة و error بسبب الخطأ إن وُجد. ردود الخطأ في الاتصال:
- 401: الرابط أو الرمز السري غير صحيح، أو الربط موقوف.
- 400: المحتوى ليس JSON صالحًا.
إلغاء طلب
أعد إرسال الطلب نفسه (نفس id) مع "status": "cancelled". إن كانت فاتورته مرحّلة يلغيها دفّة ويعكس أثرها المحاسبي والمخزني، وتصبح حالة الطلب ملغى.
متابعة الطلبات
في صفحة المتجر جدول طلبات المتجر يعرض كل طلب وصل وحالته في دفّة. الطلبات بحالة تحتاج معالجة تظهر أولًا مع السبب، ويمكن معالجتها بزر إعادة المعالجة بعد تصحيح الأكواد، أو تجاهل.
أسئلة شائعة
هل يُحدّث دفّة الكميات في متجري المخصص؟
لا. مزامنة المخزون لا تتوفر للمتجر المخصص. يمكن لمتجرك قراءة الأرصدة بنفسه عبر الربط البرمجي API.
أرسلنا الطلب مرتين، هل تتكرر الفاتورة؟
لا. الطلب نفسه (نفس id) لا تُنشأ له إلا فاتورة واحدة.
ما الفرق بين Webhook والربط البرمجي API؟
Webhook لاستقبال الطلبات بصيغة متجرك وتحويلها لفواتير. أما API فواجهة أشمل لقراءة الأصناف والأرصدة والعملاء وإنشاء الفواتير.