برنامج محاسبة مزود بواجهة برمجة تطبيقات (API)

كل جزء في Nordlet متاح من خلال واجهة برمجة تطبيقات JSON واحدة، مع حزم أدوات التطوير (SDKs)، وخطافات الويب (webhooks)، وعمليات إعادة المحاولة ذاتية التماثل (idempotent retries)، وخادم بروتوكول سياق النموذج (MCP server) للمساعدين الذكيين.

واجهة برمجة التطبيقات (API) هي وسيلة لتمكين برنامج واحد من التواصل مع برنامج آخر. تتيح لك واجهة برمجة التطبيقات المحاسبية تطوير برمجياتك الخاصة لإنشاء الفواتير، وتسجيل المدفوعات، وقراءة التقارير، دون الحاجة لتدخل بشري عبر التنقل بين الشاشات.

Nordlet هو برنامج محاسبة تُمثّل واجهة برمجة التطبيقات فيه القناة الرئيسية للوصول. فكل ما يقوم به تطبيق الويب متاح عبر واجهة برمجة تطبيقات JSON نفسها. هذه الصفحة مخصصة للمطورين وللأشخاص المسؤولين عن تحديد تكاملات منتجاتهم.

ما يفعله Nordlet

هيكل طلب موحد. كل استعلام يأخذ الشكل POST /v1/{module}/{resource}/{action} مع هيكل بيانات JSON، مثل sales/invoices/create أو bank/transactions/match.
مفاتيح واجهة برمجة التطبيقات ذات الصلاحيات. ينتمي كل مفتاح إلى شركة واحدة ويحمل صلاحيات مثل sales:read أو bank:write. أي مفتاح يفتقر إلى الصلاحية المطلوبة يتلقى رد خطأ برمز 403.
المبالغ المالية كنصوص. المبالغ هي نصوص رقمية عشرية تصل إلى 4 منازل عشرية، وليست أرقام فاصلة عائمة (floating-point)، وبذلك لا تضيع أي سنتات بسبب التقريب.
نسق أخطاء موحد. كل خطأ له الهيكل نفسه متضمناً رمزاً، ورسالته، ومعرف الطلب.
استعلامات قوائم مشتركة. كل استعلام list يقبل حقول التقسيم لصفحات، والفرز، والتصفية نفسها، ويمكنه إرجاع المجاميع.
قواعد محاسبية حقيقية. يجب أن تكون القيود اليومية متوازنة، وألا تحتوي أرقام المستندات على فجوات، كما أن الفترة المحاسبية المقفلة ترفض أي قيود جديدة برد برمز 409. يتم تسجيل كل تعديل في سجل التدقيق (audit log).

إعادة المحاولة الآمنة مع خاصية ذاتية التماثل (Idempotency)

قد تحدث مشكلة في الشبكة بعد معالجة طلبك وقبل تلقيك الرد. في هذه الحالة، قد تؤدي إعادة المحاولة إلى إنشاء الفاتورة نفسها مرتين. تعني خاصية ذاتية التماثل (Idempotency) أن الطلب المكرر ينتج عنه التأثير نفسه للطلب الأول.

أرسل ترويسة Idempotency-Key مع أي طلب يقوم بتعديل البيانات.
إعادة المحاولة باستخدام المفتاح والهيكل نفسهين ستعيد لك الرد المحفوظ، مع ترويسة x-idempotent-replay: true.
استخدام المفتاح نفسه مع هيكل بيانات مختلف يُعد أمراً مرفوضاً.
تُحفظ المفاتيح لمدة 24 ساعة.

خطافات الويب (Webhooks)

خطاف الويب هو رسالة يرسلها Nordlet إلى خادمك عند وقوع حدث معين، مثل sale_invoice.paid.

تُكتب الأحداث ضمن معاملة قاعدة البيانات (database transaction) نفسها الخاصة بالتغيير، لذلك فإن التغييرات التي يتم التراجع عنها لا ترسل أي حدث.
يتم توقيع كل عملية تسليم باستخدام خوارزمية HMAC-SHA256 باستخدام سر الاشتراكات الخاص بك، مما يتيح لك التحقق من أنها صادر من Nordlet.
تتم إعادة محاولة تسليم الطلبات الفاشلة لمدة 24 ساعة تقريباً. يمكنك أيضاً إعادة إرسالها يدويّاً.
تُدار الاشتراكات من خلال الحساب (Account) ← خطافات الويب (Webhooks) أو عبر واجهة برمجة التطبيقات.

أدوات المطورين

مرجع واجهة برمجة التطبيقات (API reference). مرجع تفاعلي لواجهة برمجة التطبيقات مبني استناداً إلى مواصفات OpenAPI، بالإضافة إلى مجموعة طلبات Postman.
حزم أدوات التطوير (SDKs). عملاء مهيئو الأنواع (typed clients) للغات TypeScript وPython وGo وJava وC# وRuby وPHP وSwift وRust، مُولّدون من المواصفات نفسها. راجع دليل حزم أدوات التطوير.
خادم بروتوكول سياق النموذج (MCP server). يمكن للمساعدين الذكيين مثل Claude البحث عن واجهة برمجة التطبيقات واستدعائها باستخدام مفتاحك الخاص بها. راجع دليل خادم بروتوكول سياق النموذج.
شركات تجريبية (Sandbox companies). تعمل الشركة الاختبارية تماماً مثل الشركة الحقيقية، ويتم تصنيفها كبيانات اختبار، وترسل الإقرارات والفواتير الإلكترونية حصرياً إلى نقاط النهاية الاختبارية للجهات الحكومية.
حدود الاستخدام (Rate limit). 300 طلب في الدقيقة لكل مفتاح واجهة برمجة تطبيقات، مع ترويسات توضح السعة المتبقية.

الأسئلة الشائعة

ماذا يمكنني أن أفعل عبر واجهة برمجة التطبيقات؟

كل ما يوجد في المنتج: الفواتير، المشتريات، دفتر الأستاذ العام، مطابقة البنوك، المخزون، الأصول، الرواتب، التقارير، والإقرارات الضريبية الخاصة بالدولة. يستعرض دليل البدء السريع دورة عمل كاملة تبدأ من الفاتورة وصولاً إلى أرقام ضريبة القيمة المضافة.

هل يمكنني دمج المحاسبة داخل منتجي الخاص؟

نعم. تمتلك كل شركة في Nordlet دفاترها الحسابية الخاصة، وتعمل برمجياتك عليها من خلال مفتاح واجهة برمجة التطبيقات الخاص بها. لا تتضمن واجهة برمجة التطبيقات أي طلب لتعديل أو حذف قيد يومي مُرحّل. أي تصحيح يتم عبر قيد جديد، مما يحافظ على دفتر أستاذ غير قابل للتعديل (immutable ledger).