أدوات الفوترة العربية

أدوات تعمل الآن

مكتبات

التثبيت — اليوم، بلا حساب npm

المكتبتان لم تُنشرا على npm بعد. وحتى ذلك، تُثبَّتان من إصدارٍ على هذا المستودع — وfatura-zatca تسحب nasq معها تلقائياً:

npm install https://github.com/opusstudiohq-max/arabic-invoice-mcp/releases/download/libs-v0.2.0/fatura-zatca-0.2.0.tgz

import { encodeZatcaQr, computeTotals, formatMinor } from "fatura-zatca";

const qr = encodeZatcaQr({
  sellerName: "مؤسسة عبد الرحمن بن محمد العتيبي للتجارة والمقاولات العامة والصيانة",
  vatNumber: "310122393500003",
  timestamp: "2026-09-01T14:30:00Z",
  totalWithVat: "1150.00",
  vatAmount: "150.00",
});
// اسمٌ من 140 بايتاً ⇒ الطول يُكتب 0x81 0x8C كما يقبله مُحقِّق الهيئة

وجُرّبت السلسلة من طرفها إلى طرفها: مشروعٌ نظيف ثبّت من هذا العنوان نفسه، فسحب nasq وتبعياتِها، ثم شُغّل فأعطى الطولَ صحيحاً والاسمَ سليماً والمجاميعَ بالهللات.

ثلاثة أشياء وجدناها بالقياس

① فاتورتك تطبع المبلغ مقلوباً. الإجمالي 1,234.50 ج.م تُكتب في ملف PDF المولَّد بـpdf-lib هكذا: م.ج 05.432,1 ﻲﻟﺎﻣﺟﻹا — أي أن المبلغ يصل العميل «05.432,1». والعيب في الترتيب الثنائي الاتجاه لا في تشكيل الحروف. وnasq/ يصلحه — وإضافةُ خوارزمية اتجاهٍ وحدها تزيده سوءاً، لأن العكس يقع مرّتين.

② نصف الخطوط العربية المرخَّصة بحرية تُنتج فاتورة مكسورة. قِسنا ثمانية عبر pdf-lib: Almarai وTajawal وIBM Plex وCairo سليمة؛ وNoto Sans وNoto Naskh وReadex Pro وAmiri مكسورة. والنصّ يُستخرج سليماً من المكسورة كلها — فلا اختبارٌ نصّي يمسّها، ولا يكشفها إلا النظر.

③ ومقياسنا عضّ صاحبه أولاً. قبل نشر مقياس التفقيط سألنا سؤالاً بديهياً: هل يجتازه بناؤنا نحن؟ فكان 19 من 50. أصلحناه، ونشرنا القصّة مع المقياس.

④ وذهبنا نفحص غيرنا فوجدنا عيبنا. قِسنا حزم ZATCA على npm فوجدنا إحداها تكتب طول الحقل بقواعد BER بينما نصّ المواصفة يقول «بايت واحد». ذهبنا نتحقق أيّهما الصواب — فإذا الخطأ عندنا، وفي ثلاث نسخ منها أداةُ الفحص المنشورة. أصلحناها قبل أن نقيس أحداً، ثم رفعنا ستّ مسائل عند أصحاب الحزم المعطوبة، كلٌّ ببرهانٍ يُشغَّل.

ما لا تفعله هذه الأدوات

• لا تؤكّد قبول الهيئة لفاتورتك. حالة القبول حدثٌ في استجابة منصة «فاتورة»، ولا تملكها أداةٌ محلية.
• لا تُدرج الوسوم 6-9 (هاش المستند، توقيع ECDSA، المفتاح العام، توقيع الهيئة). تلزم من ربطته الهيئة بالمنصة، ولا تُبنى بلا شهادة ختمٍ حقيقية — ولن نشحن كوداً لم يُشغَّل عليها.
• ولا نبيع خوفاً. مبادرة إلغاء الغرامات سارية حتى 31 ديسمبر 2026.

وهذه الحدود مكتوبة في الكود لا في وثيقة: tools/claims_lint.py بوابةٌ تُفشل أي أصلٍ عام يتجاوزها، وFACTS.json يُبطل كل حقيقة تنظيمية تجاوزت موعد إعادة فحصها فيُوقف حتى يُعاد التحقق.

ماذا نعمل — وما لا نعمله

الأدوات أعلاه مجانيةٌ ومفتوحة، ولا تحتاج إلينا لتستعملها. وهذه فقرةٌ لمن يحتاج عملاً هندسياً فوقها.

نعمل:

• تكاملُ الفوترة الإلكترونية: بناءُ الفاتورة والتوقيع والإرسال، أو إصلاحُ تكاملٍ قائمٍ يُرفض ولا يُعرف سببه.
• قراءةُ عيبٍ من البايتات: حين يقول المُحقِّق «مرفوض» ولا يقول لماذا، نفكّ المستند والرمز ونُريك موضع الكسر بالضبط — كما في مقياس رمز QR حيث وجدنا العيب في 91.7% من التنزيلات المقيسة، وفي كودنا نحن أولاً.
• النصّ العربي في المستندات: مبالغُ تنقلب، وأسماءٌ تُبتر، وتواريخُ تُعرض مقلوبة. هذا صنفٌ نعرفه من داخله.

ولا نعمل:

• لا نبيع «شهادة امتثال» — لا نملكها ولا يملكها أحدٌ غير الهيئة.
• لا نأخذ عملاً لم نُشغِّله. ما لم نجرّبه نقول إنّا لم نجرّبه، ونُقدّر ثمنَ التجربة صراحةً بدل أن نُخفيه في السعر.
• لا نبدأ بلا نطاقٍ مكتوب وسعرٍ متّفقٍ عليه. ولا نُسعّر بالساعة عملاً لا نعرف حدّه.

كيف تحكم علينا قبل أن تدفع: كلُّ ما تقرؤه هنا مفتوحٌ ويُعاد تشغيله — المقاييس، والاختبارات، والبوابات التي تُفشل ادعاءاتنا نحن. وابدأ بأصعب سؤالٍ عندك؛ إن كان جوابُنا «لا نعرف» قلناها.

📧 yahya@opus-studio.pro

الترخيص

الكود بترخيص MIT. والخطّ في أداة الفاتورة — Almarai — برخصة SIL Open Font License 1.1.

للتواصل: opus.studio.hq@gmail.com