التكامل مع منصة فاتورة ليس نقطة نهاية واحدة. تولّد مفتاحًا وطلب شهادة، تبادله برمز تحقق برمز اعتماد امتثال، ترسل فواتير اختبارية حتى تُجاز، ثم تحصل على شهادة إنتاج تُوقّع بها. هذا الدليل يمشي في الخطوات بالترتيب، ويقول عند كل خطوة ما الذي يفشل عادةً.
خمسة مفاهيم قبل أول سطر
CSR و CSID
تولّد زوج مفاتيح وطلب توقيع شهادة (CSR) يحمل بيانات منشأتك. تبادله مع الهيئة فتحصل على Compliance CSID — شهادة مؤقتة للاختبار. وبعد اجتياز فواتير الامتثال تطلب Production CSID وهي شهادة العمل الحقيقي.
Clearance و Reporting
واجهتان مختلفتان لنوعين مختلفين: الفاتورة الضريبية (B2B) تمر بـالإجازة قبل تسليمها للعميل، والمبسطة (B2C) تُبلَّغ خلال 24 ساعة بعد تسليمها. إرسال فاتورة إلى الواجهة الخطأ يفشل حتى لو كانت الفاتورة سليمة. راجع الفرق بين النوعين.
ICV و PIH
عدّاد متزايد لا يُصفَّر (ICV) وبصمة الفاتورة السابقة (PIH). الأول يقول «هذه الفاتورة رقم كذا»، والثاني يربط محتواها بمحتوى ما قبلها. الاثنان يخصان الشهادة لا السنة ولا الفرع. راجع BR-KSA-33 وBR-KSA-26.
Hash و Signature
التجزئة تُحسب على XML بعد حذف ثلاث كتل وتقنينه، والتوقيع XAdES يُضمَّن داخل الفاتورة نفسها. الترتيب مهم: ما يُحسب قبل التوقيع لا يشمل التوقيع.
البيئات
بيئة اختبار للتجربة الحرة، وبيئة محاكاة أقرب للإنتاج، ثم الإنتاج. ولكل بيئة عناوينها وشهاداتها؛ ونقل شهادة بين بيئتين لا يعمل ويستهلك وقتًا في تشخيص خطأ لا وجود له.
الخطوات
1. توليد المفتاح وطلب الشهادة
تولّد زوج مفاتيح على منحنى إهليلجي وطلب CSR يحمل بيانات منشأتك: الرقم الضريبي، والاسم، ورمز الدولة، ونوع الفاتورة الذي ستصدره، والعنوان، ومعرّف المنشأة.
ما يفشل هنا: بيانات CSR لا تطابق ما هو مسجّل لدى الهيئة، أو حقل نوع الفاتورة لا يشمل النوع الذي ستصدره فعلًا — فتكتشف بعد أسبوع أنك لا تستطيع إصدار فواتير مبسطة.
2. رمز التحقق من بوابة فاتورة
تدخل بوابة فاتورة وتولّد رمز تحقق (OTP) لمنشأتك. الرمز قصير الصلاحية، ويُستخدم مرة واحدة لتبادل CSR. راجع كيف تحصل على رمز التحقق OTP من بوابة فاتورة.
ما يفشل هنا: انتهاء صلاحية الرمز قبل إتمام الطلب — جهّز CSR أولًا ثم ولّد الرمز، لا العكس.
3. الحصول على Compliance CSID
ترسل CSR مع رمز التحقق فتعود إليك شهادة الامتثال وسِرّها. احفظ الاثنين فورًا: الشهادة تُستخدم للتوقيع، والسر للمصادقة على الاستدعاءات اللاحقة.
ما يفشل هنا: عدم حفظ السر لأن الرد بدا نجاحًا. لا توجد طريقة لاستعادته لاحقًا؛ ستعيد العملية من أولها.
4. فواتير الامتثال
ترسل فواتير اختبارية إلى واجهة الامتثال، وعليها أن تجتاز قواعد التحقق. وهنا تُكتشف كل أخطاء البناء: التقنين، والبصمة، والعدّاد، والحقول الإلزامية.
ما يفشل هنا: كل شيء تقريبًا، وهذا هو الغرض. اقرأ كود الرفض من errorMessages ولا تخمّن — مرجع أكواد أخطاء ZATCA يشرح 135 كودًا بنص الرسالة الرسمي.
5. Production CSID والتدوير
بعد اجتياز الامتثال تطلب شهادة الإنتاج. وهي التي تُوقّع بها الفواتير الحقيقية، ولها مدة صلاحية تحتاج تجديدًا.
ما يفشل هنا: انتهاء الصلاحية بصمت. اجعل التنبيه قبل الانتهاء بأسابيع لا بأيام، لأن انتهاءها يوقف قبول فواتيرك كلها.
6. أول فاتورة: بناء XML وتوقيعها وإرسالها
تبني XML بصيغة UBL 2.1، وتحسب التجزئة، وتوقّع، وتولّد رمز QR، وترسل إلى الواجهة الصحيحة بحسب نوع الفاتورة.
ما يفشل هنا: إن نجحت الخطوة الرابعة فالسادسة تنجح عادةً. الفشل هنا غالبًا في اختيار الواجهة أو في ترميز نوع المعاملة — راجع BR-KSA-06.
ما يفشل عادةً — قائمة مركّزة
- التقنين المختلف بمسافة واحدة. البصمة تُحسب على XML بعد حذف ثلاث كتل وتقنينه بمعيار C14N11. أي فرق — مسافة، ترتيب سمة، سطر جديد — يغيّر البصمة بالكامل. وهذا أشيع سبب لرفض لا يُفهم.
- البصمة بصيغة hex لا Base64. الناتج 64 حرفًا بدل 44 — BR-KSA-26.
- العدّاد يُصفَّر أو يتكرر. عدّاد لكل فرع أو لكل سنة أو لكل نوع مستند يكسر التسلسل — BR-KSA-33.
- التوقيع قبل حذف الكتل. ترتيب العمليات جزء من المواصفة لا تفصيل تنفيذي.
- الرقم الضريبي للمشتري يطابق البائع في بيانات الاختبار — يُرفض فورًا، BR-CUSTOM-VALIDATION-01.
- عنوان ناقص في بيانات المنشأة. الحقول الستة إلزامية، وأكثر ما يُنسى الحي — BR-KSA-09.
تحقّق من ناتجك أثناء التطوير
أسرع طريقة للتأكد أن فاتورتك صارت مرحلة ثانية فعلًا: ارفع ملف PDF الناتج أو صورة الرمز إلى قارئ رمز QR. يفكّ ترميز TLV ويعرض الحقول التسعة، فترى بعينك إن كانت البصمة والتوقيع والمفتاح العام موجودة — قبل أن ترسل شيئًا للهيئة.
وللتحقق من صيغة رقم ضريبي في بيانات الاختبار استخدم أداة التحقق من الرقم الضريبي.
ما ستبنيه بنفسك إن بدأت من الصفر
بلا مبالغة ولا تهويل، هذه القائمة الفعلية:
- توليد المفاتيح و CSR بالحقول التي تشترطها الهيئة.
- تدفّق الحصول على الشهادتين وتخزين أسرارهما بأمان.
- بناء XML بصيغة UBL 2.1 لأربعة أنواع مستندات على الأقل.
- التقنين C14N11 وحساب التجزئة بالخطوات الست بالترتيب الصحيح.
- توقيع XAdES وتضمينه في الفاتورة.
- توليد رمز QR بترميز TLV بحقوله التسعة.
- عدّاد ذرّي وسلسلة بصمات تتحمّل التزامن والفشل.
- توجيه كل مستند إلى واجهته الصحيحة، وإدارة إعادة المحاولة داخل المهلة.
- تفسير ردود التحقق وعرضها بشكل مفهوم.
- مراقبة صلاحية الشهادة وتدويرها.
هذه أسابيع عمل لمطوّر واحد، وأغلبها لا علاقة له بمنتجك.
البديل: واجهة واحدة
واجهة ZATCA Tools API تستقبل JSON فيه بيانات الفاتورة، وتعيد فاتورة موقّعة ومبلَّغة مع رد الهيئة ورمز QR وملف XML. التوقيع والتقنين والعدّاد والبصمة وإدارة الشهادات كلها من طرفنا.
ولمن لا يريد كتابة كود أصلًا: node مفتوح المصدر على n8n يصدر فواتير من أي سير عمل. وللمتاجر الجاهزة: Shopify، وWooCommerce، وسلة، وزد.
الخلاصة
التكامل المباشر ممكن ومفهوم، وهذه خطواته. لكن معظم أسباب الفشل ليست في الاستدعاءات بل في التقنين والبصمة والتوقيع — وهي أجزاء لا تربح شيئًا ببنائها بنفسك، وتخسر أسابيع بتشخيصها.
فإن كان هدفك إصدار فواتير لا بناء موقّع UBL، فابدأ من مرجع الواجهة. مجانية بالكامل حاليًا.