تستطيع أنظمتك قراءة نارفن عبر واجهته البرمجية، بمفاتيح تعمل كحسابات خدمة: دور واحد، والشركات التي تختارها، ولا شيء أكثر. وتخبر Webhooks تلك الأنظمة حين يقع شيء، كمزامنة أو اعتماد أو ترحيل، بأحداث موقّعة تحمل أسماء ومعرّفات وحالات، ولا تحمل مبالغ أبدًا. ولا يستطيع المفتاح أبدًا الاعتماد أو اعتماد الإقفال أو إتمام مراجعة الشخصين.
كيف تعمل مفاتيح الواجهة البرمجية؟
كل مفتاح حساب خدمة. يأخذ دورًا واحدًا والشركات التي تختارها، ضمن ما يملكه الشخص الذي ينشئه، ويعامل نارفن طلباته كطلبات شخص بذلك الدور: فحوص الصلاحيات نفسها، وحدود الشركات نفسها، والفصل نفسه في قاعدة البيانات. وتعرض قائمة المفاتيح متى استُخدم كل مفتاح آخر مرة، ومن أي عنوان.
- لا يستطيع المفتاح أبدًا الاعتماد أو اعتماد الإقفال أو إتمام مراجعة الشخصين، ولا يجتاز أي تحقق جديد من الهوية، ولا يدير المفاتيح أو الـ Webhooks. فهذه تبقى للأشخاص.
- يُعرض مرة واحدة عند إنشائه، ولا يحتفظ نارفن إلا بما يلزم للتعرف عليه.
- يمكن حصره في 20 عنوان IP أو نطاق IPv4 كحد أقصى، ومنحه صلاحية تنتهي بعد 30 أو 90 أو 180 أو 365 يومًا.
- يمكن أن يكون له حد خاص للطلبات في الدقيقة وحصة يومية، وبعدهما يجيب نارفن بالرمز 429 مع عدد الثواني التي يجب انتظارها.
- إنشاء المفتاح أو إلغاؤه يحتاج صلاحية إدارة التكاملات وتحققًا جديدًا من الهوية.
ماذا يستطيع المفتاح أن يقرأ؟
كل ما يسمح به دوره، لشركاته. وتشمل القراءات الموثقة قائمة الدخل والميزانية وقائمة التدفقات النقدية، والمؤشرات الرئيسية، وميزان المراجعة وأسطر دفتر الأستاذ العام، وأعمار الذمم المدينة والدائنة، والمركز النقدي، وجودة البيانات. وتقبل الفترات شهرًا (2026-06) أو ربعًا (2026-Q2) أو ytd أو مدى تواريخ، ويحصر معامل scope القراءة في بعض شركات المفتاح أو في مجموعة. وتصل المبالغ كنصوص عشرية، لا كأرقام عائمة مقرّبة.
ويُولَّد مرجع OpenAPI 3.1 الكامل من الواجهة نفسها، فيذكر كل مسار والصلاحية التي يحتاجها. ويستطيع الأعضاء تصفحه في نارفن، من الإعدادات ثم التكاملات والواجهة البرمجية. والمفاتيح نفسها تشغّل المعادلات المباشرة في Google Sheets وExcel.
ماذا ترسل الـ Webhooks؟
طلب POST بصيغة JSON إلى عنوان HTTPS لديك لكل حدث تشترك فيه: معرّفه ونوعه ووقته ومنشأتك وكائن بيانات من الأسماء والمعرّفات والحالات. ولا تحمل الأحداث مبالغ أبدًا، ويستطيع نظامك استدعاء الواجهة البرمجية بمفتاح حين يحتاج إلى الأرقام.
| نوع الحدث | متى يُرسل |
|---|---|
| sync.completed وsync.failed | حين ينهي اتصال مزامنة، أو تفشل |
| approval.requested وapproval.decided | حين يُطلب اعتماد، أو يُعتمد أو يُرفض |
| erp_posting.drafted وerp_posting.posted وerp_posting.failed | حين يُعدّ قيد أو مستند للمراجعة، أو يُرحَّل إلى ERP، أو يُرفض |
| close.signed_off وclose.reopened | حين يُعتمد إقفال شهر لشركة أو يُعاد فتحه |
| evidence.added | حين يُرفق ملف داعم بمهمة إقفال أو تسوية أو طلب من المدقق |
| report.sent | حين يُرسل تقرير مجدول |
| finding.raised | حين يرفع أحد الوكلاء ملاحظة حرجة |
| audit.anchored وaudit.chain_broken | حين يُتحقق من سلسلة سجل التدقيق، أو لا تصمد |
كيف تتحقق من أن الـ Webhook جاء من نارفن؟
يحمل كل طلب ترويسة Naarvin-Signature بالشكل t=<ثواني يونكس>,v1=<hex>. احسب HMAC-SHA256 على الطابع الزمني ثم نقطة ثم نص الطلب الخام، بسر التوقيع الذي عُرض مرة واحدة عند إنشاء العنوان، وقارنه بقيمة v1. وارفض الطلبات ذات الطابع الزمني القديم، حتى لا يُعاد إرسال طلب ملتقط. وتذكر ترويستا Naarvin-Event وNaarvin-Delivery نوع الحدث والتسليم.
وتُختم عناوين الاستقبال وأسرارها عند حفظها. ويُعاد إرسال ما فشل تسليمه حتى ثماني محاولات، والعنوان الذي يفشل 20 مرة متتالية يُوقف مؤقتًا. ويمكن إعادة إرسال التسليمات الأخيرة، ويختبر حدث تجريبي عنوانك. اطلع على الأمان.
كيف تبدأ؟
- أنشئ مفتاحًا لغرض واحدمن الإعدادات ثم التكاملات والواجهة البرمجية، أنشئ مفتاحًا بأضيق دور والشركات التي يحتاجها النظام، مع تاريخ انتهاء، وحدود IP إن كانت عناوين المتصل ثابتة.
- اقرأ المرجعحدد المسارات التي تحتاجها والصلاحية التي يتطلبها كل منها، ثم أرسل طلبًا أول لشركة واحدة.
- أضف عنوان Webhookأضف عنوان HTTPS لديك، واختر الأحداث، وانسخ سر التوقيع، وتحقق من الحدث التجريبي.
- راجع المفاتيح بانتظامألغِ المفاتيح التي لا يستخدمها أحد. والمفتاح الملغى يتوقف فورًا.
أسئلة شائعة
هل يستطيع مفتاح الواجهة البرمجية اعتماد دفعة؟
لا. لا تستطيع المفاتيح أبدًا الاعتماد أو اعتماد الإقفال أو إتمام مراجعة الشخصين، فهذه تحتاج دائمًا إلى شخص.
لماذا لا تحمل الـ Webhooks مبالغ؟
قد يصل الحدث إلى أنظمة وسجلات خارج قواعد الصلاحيات في نارفن. ويقرأ نظامك الأرقام عبر الواجهة البرمجية، بمفتاح محصور في الشركات التي يحق له رؤيتها.
هل تستطيع أنظمتنا دفع الدفاتر إلى نارفن عبر الواجهة البرمجية؟
تصل الدفاتر عبر الموصلات أو الملفات أو دخول قاعدة البيانات أو [تغذية بيانات REST](/integrations/rest-data-feed) يقرؤها نارفن.