Nordlet لمطوري التطبيقات

أضف الفوترة، وإمساك الدفتر (bookkeeping)، والإقرارات الضريبية في الاتحاد الأوروبي إلى برمجياتك من خلال واجهة برمجة تطبيقات JSON واحدة، وحزم تطوير برمجيات محددة الأنواع (typed SDKs)، وخطافات الويب (webhooks)، وخادم بروتوكول السياق النموذجي (MCP server)، وشركات تجريبية (sandbox companies).

تنشئ العديد من التطبيقات أحداثاً مالية: سداد طلب، تجديد اشتراك، أو إصدار استرداد أموال. يجب أن ينتهي المطاف بكل حدث من هذه الأحداث في دفاتر الشركة.

Nordlet هو برنامج محاسبة مصمم ليكون مبنياً أساساً لواجهات برمجة التطبيقات (API-first). كل ما يقوم به تطبيق الويب متاح أيضاً من خلال واجهة برمجة تطبيقات JSON واحدة. يرسل تطبيقك الأحداث، ويحتفظ Nordlet بالدفاتر ويجهز الإقرارات الضريبية.

ما يفعله Nordlet

يتيح كل إجراء على هيئة POST /v1/{module}/{resource}/{action} مع محتوى JSON، مثل /v1/sales/invoices/create.
يوثق كل طلب باستخدام مفتاح واجهة برمجة تطبيقات (API key) ينتمي إلى شركة واحدة. يحمل كل مفتاح نطاقات (scopes)، مثل sales:read أو sales:write، والتي تحد من الصلاحيات المتاحة له.
يتعامل مع المبالغ كقيم عشرية نصية (decimal strings)، وليس أبداً كأرقام ذات فاصلة عائمة (floating-point numbers)، لئلا تضيع أي سنتات بسبب التقريب.
يقبل ترويسة Idempotency-Key مع كل عملية تعديل. تؤدي إعادة المحاولة باستخدام نفس المفتاح إلى إرجاع الإجابة الأولى بدلاً من تنفيذ العمل مرتين. تعني حتمية المعالجة (idempotency) أن الطلب المكرر له نفس تأثير الطلب الواحد.
يرجع كل خطأ بتنسيق مشترك واحد.
يسمح بـ 300 طلب في الدقيقة لكل مفتاح واجهة برمجة تطبيقات.
يسجل كل تغيير في سجل التدقيق (audit log).

يغطي دليل اتفاقيات واجهة برمجة التطبيقات (API conventions) كل قاعدة من هذه القواعد بالتفصيل.

دفاتر تظل صحيحة

يؤدي إصدار الفاتورة إلى تعيين رقم متسلسل بلا فجوات، والتحقق من أن الفترة المحاسبية (accounting period) مفتوحة، وترحيل قيد اليومية (journal entry) في نفس معاملة قاعدة البيانات (database transaction).
يجب أن يكون كل قيد مرحل متوازناً. تتحقق قاعدة البيانات نفسها من ذلك عند حفظ المعاملة.
لا يمكن حذف المستندات الصادرة والمثبتة. يتم التراجع عن مطابقة بنكية خاطئة باستخدام قيد عكسي، وليس عن طريق تعديل القديم. هذا هو المقصود بـ دفتر الأستاذ غير القابل للتعديل (immutable ledger).

حزم تطوير البرمجيات، وبروتوكول MCP، وخطافات الويب

يتم إنشاء حزم تطوير برمجيات محددة الأنواع (typed SDKs) من نفس وصف OpenAPI لكل من TypeScript وPython وGo وJava وC# وRuby وPHP وSwift وRust. إلى أن يتم نشر حزمة SDK، يمكنك تثبيتها من مستودع المصدر الخاص بها. راجع دليل حزم تطوير البرمجيات (SDKs).
تتوفر مجموعة Postman تحتوي على كل نقطة نهاية (endpoint).
يتيح خادم بروتوكول السياق النموذجي (MCP server) لمساعد ذكاء اصطناعي مثل Claude Code البحث في واجهة برمجة التطبيقات واستدعائها باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك. كل استدعاء هو طلب واجهة برمجة تطبيقات عادي بنفس النطاقات والحدود.
تخبر خطافات الويب (webhooks) تطبيقك عند وقوع حدث ما، مثل sale_invoice.issued أو sale_invoice.paid. يتم توقيع كل عملية تسليم باستخدام توقيع HMAC حتى تتمكن من التحقق من أنها صادر من Nordlet. تتم إعادة محاولة عمليات التسليم الفاشلة لمدة 24 ساعة تقريباً.

الاختبار باستخدام الشركات التجريبية

أنشئ شركة باستخدام isSandbox: true، أو ضع علامة في مربع الحماية (sandbox) عند إعداد شركة في التطبيق.
تعمل الشركة التجريبية (sandbox company) تماماً مثل الشركة الحقيقية: نفس الوحدات النمطية، ونفس واجهة برمجة التطبيقات.
يتم تمييزها بوضوح كبيانات اختبار، ولا يمكنك تحويل شركة حقيقية إلى شركة تجريبية أو العكس.
تذهب الإقرارات والفواتير الإلكترونية (e-invoices) الخاصة بالشركة التجريبية إلى خدمات الاختبار التابعة للإدارات.
يتم قياس الاستخدام في الشركة التجريبية وإفوترته مثل الاستخدام في الشركة الحقيقية.

يستعرض دليل البدء السريع (getting started) مفتاح واجهة برمجة التطبيقات الأول، والفاتورة الأولى، والدورة الكاملة.

FAQ

هل يمكن لتطبيق واحد خدمة عدة شركات؟

نعم. ينتمي كل مفتاح واجهة برمجة تطبيقات إلى شركة واحدة، لذا فإنك تنشئ مفتاحاً لكل شركة. يحمل كل تسليم لخطاف الويب المعرف companyId الخاص بالشركة التي ينتمي إليها، بحيث يمكن لمتلقٍ واحد خدمة عدة شركات.

هل يجب عليّ إعداد الإقرارات الضريبية بنفسي؟

لا. يقوم Nordlet بإنشاء الإقرارات من الدفاتر. بالنسبة لكل إقراره، إما أن يقوم بإرساله، أو يبني ملفاً تقوم برفعه، أو يعرض الأرقام لتُدخلها يدويًا، وذلك حسب الدولة. يسرد جدول دعم الإقرارات (filing support table) كل حالة.