الـ Webhooks
أعلم نظاماً آخر تلقائياً عند الإبلاغ عن فاتورة أو دفعها أو استلامها. الإعداد في التطبيق؛ والتفاصيل التقنية على docs.alyabooks.ai.
الـ webhook هو عنوان ويب لنظام تخطيط موارد المؤسسة (ERP) أو أداة المحاسبة أو منصة الأتمتة الخاصة بك تستدعيه عليا بوكس كلما حدث شيء. يعطيك مطورك العنوان؛ وتسجله أنت هنا.
الخطوات
- افتح API access (الوصول إلى API) في الشريط الجانبي (مجموعة System) واختر علامة تبويب Webhooks. تحتاج إلى دور المالك أو المسؤول، أو صلاحية "Manage webhooks".
- انقر New webhook (webhook جديد) واملأ:
- Target URL (عنوان URL الهدف): يجب أن يكون عنوان
https://عاماً. تُرفض العناوين الخاصة أو عناوينhttp://العادية. - Name (الاسم) وDescription (الوصف) الاختياري.
- Events (الأحداث): حدد ما تحتاجه، أو All events (كل الأحداث).
- Custom headers (ترويسات مخصصة) إذا طلبها مطورك، ومفتاح Active (نشط).
- Target URL (عنوان URL الهدف): يجب أن يكون عنوان
- انقر Create webhook (إنشاء webhook). يُعرض سر التوقيع مرة واحدة؛ انسخه ومرره إلى مطورك، الذي يستخدمه للتحقق من كل استدعاء.
- من قائمة الصف، استخدم Send test (إرسال اختبار) لفحص نقطة النهاية، وDeliveries (عمليات التسليم) لرؤية كل محاولة مع الحالة والاستجابة، وPause (إيقاف مؤقت) أو Resume (استئناف)، وRotate secret (تدوير السر)، وEdit (تعديل) أو Delete (حذف).
الأحداث الشائعة
| الحدث | يُرسل عندما |
|---|---|
invoice.created, invoice.submitted, invoice.reported, invoice.rejected | تنتقل فاتورة عبر دورة حياة الهيئة الاتحادية للضرائب |
invoice.paid, invoice.overdue | تُسجل دفعة أو يمر تاريخ الاستحقاق |
incoming.created, incoming.validated, incoming.accepted | تصل فاتورة مورد وتُراجع |
quote.sent, reminder.sent, document.sent | يُرسل مستند بالبريد الإلكتروني |
customer.created, product.created | تُضاف بيانات رئيسية |
معلومات مفيدة
- يُعاد المحاولة للاستدعاءات الفاشلة بعد دقيقة واحدة و5 دقائق و30 دقيقة وساعتين و12 ساعة على الأقل (ترسل إعادات المحاولة مهمةٌ تعمل كل 5 دقائق)؛ وبعد ست محاولات يُعلَّم التسليم بأنه فاشل ويمكن إعادة محاولته يدوياً.
- يوقف الـ webhook نفسه مؤقتاً بعد 25 عملية تسليم متتالية مستنفدة؛ أصلح ن قطة النهاية وانقر Resume.
- تعمل الـ webhooks في كل الأوضاع، بما في ذلك Test (simulated)، فيمكنك التكامل قبل الانتقال إلى الوضع الحي.
- يحمل كل استدعاء الترويسات
X-Webhook-EventوX-Webhook-Event-IdوX-Webhook-DeliveryوX-Webhook-Attempt، والتوقيع فيX-Webhook-Signature، ووكيل المستخدمWebhook-Delivery/1.0؛ ولا يمكن أن تبدأ أسماء الترويسات المخصصة بـX-Webhook-. يتحقق المطوّر لديك من التوقيع باستخدام سر التوقيع. - صيغ الحمولة والترويسات والتحقق من التوقيع: راجع وثائق المطورين على docs.alyabooks.ai.