الـ Webhooks هي نصف «الدفع» من التكاملات: بدلاً من أن يستعلم نظامك من FreeMaint، يرسل FreeMaint طلب POST إلى عنوانك بمجرد وقوع الحدث. الإعداد من إعدادات الشركة > Webhooks (/company-settings/webhooks). متاحة ابتداءً من باقة Starter (100 تسليم/يوم؛ غير محدودة ابتداءً من Business).
الأحداث المتاحة
- work_order.created — تم إنشاء أمر عمل
- work_order.completed — انتقل أمر عمل إلى «مكتمل»
- work_order.status_changed — انتقل أمر عمل إلى أي حالة؛ وتحمل الحمولة new_status. يُطلَق إلى جانب work_order.completed الذي لم يتغيّر
- request.created — تم إرسال طلب صيانة
- request.status_changed — تمت الموافقة على طلب أو رفضه أو إلغاؤه
- part.low_stock — انخفضت قطعة إلى نقطة إعادة الطلب أو دونها
- part.out_of_stock — نفدت قطعة تمامًا
- part.low_stock_summary — ملخّص يومي واحد لكل شركة يسرد القطع عند نقطة إعادة الطلب أو دونها، بما فيها القطع التي لم تتحرك قط
- part.out_of_stock_summary — الملخّص اليومي نفسه، للقطع التي بلغت الصفر
- part.consumed — تم استهلاك قطعة في أمر عمل، أو إرجاعها
- compliance.chain_divergence — انكسرت سلسلة تجزئة التدقيق (Enterprise)
- asset.downtime_started — فُتِح توقّف آلة
- asset.downtime_ended — أُغلِق توقّف آلة؛ ويمكن الآن احتساب مدّته
- report.daily_summary — أعمال اليوم المنجزة، مرة يوميًا في الساعة التي تختارها
- purchase_order.created — أُنشئ أمر شراء؛ وتحمل الحمولة الأمر (reference وstatus وtotal_cost وcurrency وexpected_date وerp_reference) ومورّده
- purchase_order.status_changed — انتقل أمر شراء إلى حالة أخرى (معتمد، مطلوب، ملغى…)؛ وتحمل الحمولة previous_status وnew_status
- purchase_order.received — استُلم تسليم لأمر شراء (يُرسَل مع كل تسليم، بما في ذلك الجزئية)؛ وتسرد الحمولة كل بند مع quantity_ordered وquantity_received (هذا التسليم) وquantity_received_total وquantity_remaining، إضافة إلى receipt_id وfully_received وclosed_short؛ وتكون new_status هي PARTIALLY_RECEIVED ما دامت البضائع متوقعة، وRECEIVED عند اكتمال الأمر أو إغلاقه
part.consumed — عكس المخزون في نظام ERP
هذا هو الحدث الذي تشترك فيه عندما يحتاج نظام آخر (ERP، فوترة، مخزون، محاسبة) إلى عكس ما استهلكته الصيانة فعلياً. الحقل quantity يحمل إشارة: سالب عند صرف القطعة للعمل، وموجب عند إرجاعها بإزالتها من أمر العمل — وبذلك يُنتج عكسُ العملية في FreeMaint مستندَ إرجاع مطابقاً في النظام الآخر. الحقل stock_movement_id ثابت عبر إعادة المحاولة وإعادة الإرسال: استخدمه كمفتاح للتكرار الآمن ولن تُرحّل الصرف نفسه مرتين أبداً. نقطة مهمة عندما تسير الحركة في الاتجاهين: طفرة GraphQL المسماة adjustStock لا تُطلق هذا الحدث. وهذا مقصود — فتصحيح المخزون الذي يكتبه نظامك في FreeMaint يجب ألّا يعود إليك كصدى فتُسجّله مرتين. وحده الاستهلاك المسجَّل على أمر عمل داخل FreeMaint يُطلق part.consumed. وتحمل القطعة أيضًا custom_reference: رمزك الخاص لها، أي customReference الذي حددته عبر createPart أو updatePart، ليتمكن النظام المسؤول عن الكتالوج من مطابقة كل سطر دون الاحتفاظ بجدول لمعرّفات FreeMaint.
{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "محمل 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "وحدة" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "تغيير محمل" }, "asset": { "id": 91, "name": "فارزة 2" }, "location": { "id": 7, "name": "مستودع المصنع" }, "user": { "id": 5627, "name": "أ. فني" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }
التسليم والتوقيع
كل تسليم هو طلب POST بجسم JSON وترويسة X-FreeMaint-Signature بالشكل t=<ثوانٍ unix>,v1=<hex>، حيث v1 هو HMAC-SHA256 للسلسلة «<t>.<الجسم الخام>» بمفتاح هو سر الـ webhook الخاص بك. تحقّق من الجسم الخام، قبل أي تحليل JSON أو إعادة تسلسل. نرسل أيضاً X-FreeMaint-Event و X-FreeMaint-Delivery-Id. يُعدّ الرد 2xx تسليماً ناجحاً؛ وتُعاد أخطاء الشبكة وأخطاء 5xx حتى 3 مرات بتراجع أُسّي (نحو 2 و4 و8 ثوانٍ)؛ أما 4xx فيُعامَل كرفض نهائي ولا تُعاد المحاولة.
إعادة إرسال تسليم
يُحفظ كل محاولة في سجل التسليمات الخاص بالـ webhook مع حالتها ورمز الاستجابة. ويمكن إعادة إرسال أي تسليم منتهٍ من هناك: تُرسل الحمولة المخزَّنة نفسها دون تغيير، فتبقى مفاتيح الأعمال داخلها (ومنها stock_movement_id) كما هي، ولن يُرحّل المستقبِلُ الذي يزيل التكرار بشكل صحيح العملية مرتين. هكذا تُعوَّض التسليمات بعد تعطّل نقطة النهاية لديك أو رفضها طلباً بالخطأ.
الصور (اختياري)
عند تفعيل «تضمين الصور» على ويب هوك (معطّل افتراضيًا)، يحمل الكائنان "work_order" و"request" مصفوفة "photos": ما يصل إلى 4 روابط HTTPS لصور JPG أو PNG أو GIF أو WebP، الأحدث أولًا. يفتح كل رابط الصورة دون تسجيل دخول لمدة 7 أيام، لذا احفظ الملف لديك إن احتجت إليه مدة أطول. إعادة الإرسال ترسل الروابط نفسها. لا يتغير شيء في الأحداث الأخرى ولا في الويب هوك الأخرى. بالنسبة إلى "work_order.created" و"request.created"، يُرسل الويب هوك الذي فُعّل فيه «تضمين الصور» بعد 90 ثانية من الحدث (يحتفظ الحقل "timestamp" بوقت الحدث)، لتشمل الصور المرفوعة مباشرة بعد السجل.
متطلبات العنوان
- https:// فقط — يُرفض http العادي
- المنفذ 443 أو 8443 فقط
- يجب أن يكون المضيف متاحاً للعموم — تُرفض نطاقات loopback والنطاقات الخاصة وCGNAT
- لا بيانات اعتماد داخل العنوان (يُرفض https://user:pass@host)
- النظام الموجود داخل شبكتك فقط يحتاج إلى نقطة نهاية عامة أو وسيط (n8n أو Make أو Zapier) أمامه
الحدود
- Starter — 100 تسليم/يوم لكل شركة
- Business — غير محدود
- Enterprise — غير محدود
- يحسب العدّاد محاولات التسليم: ثلاثة webhooks مشتركة في الحدث نفسه تستهلك ثلاث وحدات
- يُصفَّر العدّاد اليومي عند 00:00 UTC
نصيحة
مقالات ذات صلة
هل كانت هذه الصفحة مفيدة؟