البدء السريع

منصة Nordlet هي منصة محاسبية مبنية خصيصاً لواجهات البرمجة (API-first) لأسواق الاتحاد الأوروبي والمنطقة الاقتصادية الأوروبية (EEA)، وتُطلق مع توافق تام مع الأنظمة اللتوانية. تتوفر كافة وظائف المنتج، مثل الفوترة، دفتر الأستاذ العام (general ledger)، التسوية البنكية، وملفات i.SAF، عبر واجهة برمجة تطبيقات JSON واحدة.

1. الحصول على مفتاح واجهة برمجة التطبيقات (API)

يتم مصادقة كل طلب باستخدام مفتاح مصادقة (Bearer API key) مرتبط بشركة واحدة:

Authorization: Bearer nl_...

لأغراض التطوير المحلي، يمكنك تهيئة شركة ومفتاح جديدين:

pnpm --filter @nordlet/db bootstrap:dev     # شركة فارغة
pnpm --filter @nordlet/api seed:demo        # شركة تحتوي على بيانات تجريبية

مرجع واجهة البرمجة التفاعلي (مواصفات OpenAPI متوفرة على الرابط /openapi.json؛ بينما يوفر الخادم المحلي نفس المرجع على العنوان http://localhost:3001/docs).

Postman

هل تفضل استخدام Postman؟ يمكنك استيراد المجموعة الجاهزة التي تضم كافة نقاط النهاية (endpoints)، منظمة حسب الوحدة النمطية (module)، ومدمجة مسبقاً بمصادقة الحامل (bearer auth): مجموعة Postman لـ Nordlet. بعد الاستيراد، قم بتعيين متغير المجموعة bearerToken ليكون مفتاح واجهة البرمجة الخاص بك، وبذلك يصبح كل طلب مصادقاً عليه تلقائياً.

شركات الوضع التجريبي (Sandbox)

لأغراض اختبار التكامل، يمكنك إنشاء شركة بخيار isSandbox: true (عبر POST /v1/account/companies/create، أو عن طريق تحديد خانة الاختيار الخاصة بالوضع التجريبي أثناء إعداد الحساب في التطبيق). تتصرف شركة الوضع التجريبي تماماً مثل الشركة الحقيقية من حيث الوحدات النمطية وواجهة البرمجة، مما يتيح لك إرسال حجوم معاملات واقعية عبرها، إلا أنه يتم تمييزها بوضوح كبيانات اختبار، ويؤدي حذفها إلى مسح كافة بياناتها فوراً بدلاً من الاحتفاظ بها لفترة فترة الاستبقاء البالغة 10 أيام. يمكنك تشغيل أي عدد من شركات الوضع التجريبي جنباً إلى جنب مع شركتك الحقيقية تحت نفس الحساب؛ علماً أن هذا الخيار غير قابلة للتعديل بعد الإنشاء لضمان عدم إعادة تصنيف السجلات الحقيقية صدفةً على أنها بيانات اختبار. يتم احتساب الاستخدام في شركة الوضع التجريبي وفواتيره تماماً مثل الشركات الحقيقية، ويشمل ذلك الطلبات، صفحات مسح المستندات، التخزين، ورسوم إعادة التفعيل. كما تُرسل الإقرارات والفواتير الإلكترونية الخاصة بشركة الوضع التجريبي دائماً إلى نقاط النهاية الخاصة بالاختبار التابعة للجهات الضريبية.

2. الاستدعاءات الأولى

تُنفذ كل عملية باستخدام الطلب POST /v1/{module}/{resource}/{action} مع إرفاق نص JSON. إليك كيفية إنشاء عميل:

curl -X POST https://api.nordlet.com/v1/partners/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-create-001" \
  -d '{"name": "UAB Klientas", "code": "301111222", "vatCode": "LT100001112223"}'

إصدار فاتورة (يتم تمثيل المبالغ كسلاسل عشرية، ولا تُستخدم الأرقام العائمة أبداً):

curl -X POST https://api.nordlet.com/v1/sales/invoices/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "partnerId": "<partner id>",
    "lines": [{"description": "Konsultacijos", "quantity": 4, "unitPriceExclVat": "75.0000", "vatClassifierCode": "PVM1"}]
  }'

curl -X POST https://api.nordlet.com/v1/sales/invoices/issue \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": "<invoice id>", "issueDate": "2026-07-09"}'

يؤدي الإصدار إلى تخصيص رقم متسلسل دون فجوات (SF-1)، والتحقق من أن الفترة المحاسبية مفتوحة، وتسجيل قيد اليومية المتوازن (مدين 2410 ذمم مدينة / دائن 5001 إيرادات / دائن 4492 ضريبة القيمة المضافة) في نفس المعاملة.

3. الدورة الكاملة

الخطوة	الاستدعاء
نقل الدفاتر المحاسبية من نظام سابق	migration/books/validate ← migration/books/import - راجع قسم الترحيل من نظام آخر
تسجيل فاتورة مورد	purchases/invoices/create ← purchases/invoices/register
استيراد كشف حساب بنكي	bank/statements/import (ملف camt.053 بصيغة XML) أو bank/transactions/import (بصيغة JSON)
الحصول على مقترحات المطابقة	bank/transactions/suggest-matches
تسوية دفعة مالية	bank/transactions/match - يقوم بتسجيل الدفعة وتحديث حالة الدفع paymentStatus
دفع مستحقات الموردين	bank/payments/export - إنشاء ملف pain.001 SEPA المخصص لبنكك
سجلات ضريبة القيمة المضافة الشهرية	declarations/lt/isaf/generate - إنشاء ملف i.SAF 1.2 بصيغة XML لهيئة الضرائب VMI
أرقام إقرار ضريبة القيمة المضافة	declarations/lt/fr0600/compute - احتساب بنود النموذج FR0600 ومطابقتها مع السجلات
شحن بضائع باستخدام سند تحويل	transport/waybills/create ← issue، ثم declarations/lt/ivaz/generate - إنشاء ملف i.VAZ بصيغة XML لهيئة الضرائب VMI

4. الحزمة البرمجية للغة TypeScript (SDK)

import { createNordletClient, idempotent } from '@nordlet/sdk'

const client = createNordletClient({
  baseUrl: 'https://api.nordlet.com',
  apiKey: process.env.NORDLET_API_KEY!,
})

const { data, error } = await client.POST('/v1/sales/invoices/create', {
  body: {
    partnerId,
    lines: [{ description: 'Konsultacijos', quantity: 4, unitPriceExclVat: '75.0000' }],
  },
  ...idempotent(`order-${orderId}`),
})

يتم توليد الحزمة البرمجية (SDK) تلقائياً من مواصفات OpenAPI الحالية (pnpm --filter @nordlet/sdk generate)، مما يضمن كتابة كافة الطلبات والاستجابات بأنواع بيانات محددة بدقة (fully typed).

5. إشعارات الويب (Webhooks)

يمكنك الاشتراك في الأحداث بدلاً من الاستعلام المتكرر (polling):

curl -X POST https://api.nordlet.com/v1/webhooks/subscriptions/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/hyperion", "events": ["sale_invoice.issued", "sale_invoice.paid"]}'

تحمل رسائل التسليم توقيعاً زمنياً بصيغة HMAC (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> محسوباً على النمط <timestamp>.<raw body> باستخدام سر الاشتراك الخاص بك) إلى جانب توقيع x-nordlet-signature: sha256=<hex> الأصلي للنص الخام، وتتم إعادة محاولة إرسالها لمدة تصل إلى 24 ساعة تقريباً. راجع قسم اصطلاحات واجهة البرمجة لمعرفة نافذة إعادة الإرسال.

يأتي كل نص تسليم بالهيكل { id, version, companyId, eventType, createdAt, data }: حيث يمثل حقل version إصدار الغلاف (حالياً 1) ويمثل حقل companyId الشركة التي ينتمي إليها الحدث، مما يسمح لمستقبل واحد بخدمة عدة شركات. يتم رفض الاشتراك في أي اسم حدث غير موجود في القائمة أدناه برمز الخطأ 400؛ ويمكنك استخدام "*" للاشتراك في جميع الأحداث. في حال فشل تسليم 5 أحداث متتالية، سيتم إيقاف الاشتراك مؤقتاً وإرسال بريد إلكتروني لمالكي الشركة؛ ويمكنك إعادة تفعيله من خلال الحساب (Account) ← إشعارات الويب (Webhooks) أو عبر استدعاء webhooks/subscriptions/update مع تعيين القيمة isActive: true.

الأحداث المتاحة: agreement.invoice_generated, bank_feed.synced, document_capture.peppol_received, filing.failed, filing.rejected, goods_receipt.posted, intercompany.invoice_mirrored, item.created, item.deleted, item.updated, lead.converted, lead.created, partner_inquiry.created, payroll_run.approved, payroll_run.reversed, pos_report.created, price_list.updated, purchase_invoice.paid, purchase_invoice.registered, purchase_order.approved, purchase_order.received, refund_liability.actual, refund_liability.trued_up, report.completed, report.failed, revenue_recognition.modified, revenue_recognition.posted, sale_invoice.einvoice_sent, sale_invoice.issued, sale_invoice.paid, sale_invoice.peppol_delivered, sale_invoice.peppol_failed, sale_invoice.peppol_rejected, sale_invoice.peppol_sent, sale_invoice.quote_sent, sale_invoice.sent, sales_order.created, sales_order.fulfilled, settlement.imported, settlement.posted, settlement.updated, stock.changed, stock.reorder_needed, vat_review.opened, vat_review.resolved. تُدرج وثيقة OpenAPI كل حدث تحت القسم x-webhooks.

راجع قسم اصطلاحات واجهة البرمجة للاطلاع على استعلامات القوائم، هياكل الأخطاء، دلالات المعاملات المتطابقة (idempotency)، وحدود معدل الاستخدام (rate limits).