كيف تربط جهاز الكاشير بزاتكا في المرحلة الثانية

ما هي المرحلة الثانية في الفوترة الإلكترونية؟

انطلقت المرحلة الثانية – الربط والتكامل (Integration Phase) رسمياً في 1 يناير 2023 على موجات متدرجة. بخلاف المرحلة الأولى التي اقتصرت على إصدار الفاتورة إلكترونياً بصيغة مقروءة وحفظ رمز QR، تفرض المرحلة الثانية ربطاً تقنياً مباشراً بين نظام المنشأة (EGS – Electronic Generation Solution) ومنصة فاتورة (fatoora.zatca.gov.sa). كل فاتورة يجب أن:

1. تُصاغ بصيغة UBL 2.1 XML وفق معيار زاتكا (vTrack).
2. تُحفظ في ملف PDF/A-3 يتضمن XML مضمَّناً.
3. تُوقَّع رقمياً بخوارزمية ECDSA على منحنى secp256k1 مع تجزئة SHA-256.
4. تحمل رمز QR بترميز TLV يتكوّن من 9 حقول مُشفَّرة Base64.
5. تُرسَل إلى منصة فاتورة بحسب نوعها: المشاركة للفاتورة الضريبية (B2B) أو الإبلاغ للفاتورة الضريبية المبسطة (B2C).

حتى نهاية 2025 وصلت زاتكا إلى الموجة 22 (حد إيرادات 1 مليون ريال)، والآن في 2026 تعلن الموجتان 23 (750 ألف ريال – 31 مارس 2026) و24 (375 ألف ريال – 30 يونيو 2026).

نموذج المشاركة ونموذج الإبلاغ: الفرق الجوهري

الخطوات الثماني لتأهيل جهاز الكاشير على منصة فاتورة

الخطوة 1: الدخول إلى منصة فاتورة

افتح fatoora.zatca.gov.sa وسجِّل الدخول ببيانات بوابة ERAD للمنشأة. هذه البوابة هي نفسها بوابة الزكاة والضريبة المعتمدة، وليست بوابة المطوِّرين.

الخطوة 2: طلب رمز OTP

في قائمة «تسجيل وحدة حل جديد» اختر «توليد OTP». يُولَّد رمزاً بعدد الأجهزة المراد ربطها. كل رمز صالح ساعة واحدة فقط من لحظة توليده، ومُخطَّط عمليات CSR وطلب الشهادة تتمّ داخل هذه النافذة.

الخطوة 3: توليد CSR على الجهاز

يجب أن يُنشئ جهاز الكاشير طلب توقيع شهادة (CSR) محلياً بصيغة PKCS#10، ومُوقَّعاً بمفتاح ECDSA جديد على منحنى secp256k1. الحقول الإلزامية:

• C: رمز الدولة، دائماً SA.
• O: الاسم القانوني للمنشأة.
• OU: اسم الفرع، أو الرقم الضريبي لعضو المجموعة الضريبية إذا كان الحساب لمجموعة.
• CN: اسم عام فريد لكل جهاز، مثل ABC-3111111119-311111111100003.
• UID: الرقم الضريبي (15 رقماً يبدأ وينتهي بـ3).
• title: نواع ثنائي يحدد أنواع الفواتير (1000 قياسية، 0100 مبسطة، 1100 كلاهما).
• subjectAltName يحتوي على SN=1-{اسم الحل}|2-{الطراز}|3-{UUID}.
• registeredAddress و businessCategory.
• امتداد certificateTemplateName = ASN1:PRINTABLESTRING:ZATCA-Code-Signing للإنتاج، أو PREZATCA-Code-Signing لبيئة المحاكاة.
• keyUsage = digitalSignature, nonRepudiation, keyEncipherment.

بأوامر OpenSSL يمكن توليد المفتاح و CSR كالتالي:

openssl ecparam -name secp256k1 -genkey -noout -out privatekey.pem
openssl req -new -sha256 -key privatekey.pem \
    -extensions v3_req -config cert.cnf -out generatedCSR.csr
echo -n `cat generatedCSR.csr` | openssl enc -base64 -a -A > csr_b64.txt

الخطوة 4: طلب شهادة الامتثال (Compliance CSID)

يرسل الجهاز CSR المُشفَّر Base64 في جسم الطلب مع رمز OTP في ترويسة OTP إلى نقطة النهاية:

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance
Accept-Version: V2
OTP: 123456
Content-Type: application/json

تعيد زاتكا شهادة الامتثال (CCSID) في نوع X.509 بصيغة Base64، بالإضافة إلى سر (secret) يستخدم لمصادقة HTTP Basic في النداءات التالية.

الخطوة 5: اجتياز اختبارات الامتثال بفواتير عينة

قبل السماح بالإنتاج، تطلب زاتكا تقديم عمليات موقَّعة من كل نوع فاتورة أعلنته في title:

• title=1000 – 3 عمليات: فاتورة قياسية (388)، إشعار دائن (381)، إشعار مدين (383).
• title=0100 – 3 عمليات مبسطة.
• title=1100 – 6 عمليات (النوعان معاً).

ترسل العمليات إلى:

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices
Authorization: Basic base64(CCSID:secret)

الخطوة 6: طلب شهادة الإنتاج (Production CSID)

بعد نجاح كل العمليات، يطلب الجهاز شهادة الإنتاج الحقيقية:

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids
Body: {"compliance_request_id": "…"}
Authorization: Basic base64(CCSID:secret)

تعيد زاتكا Production CSID من هيئة الشهادات التقنية (Technical CA) مع سر إنتاج جديد. صلاحية الشهادة عادة سنة واحدة، وتُجدَّد قبل انتهائها عبر PATCH على نفس النقطة بـ CSR جديد ورمز OTP جديد.

الخطوة 7: إصدار الفواتير في الإنتاج

كل فاتورة جديدة تُمرّ بهذه المراحل داخل الجهاز:

1. بناء XML وفق UBL 2.1 مع ProfileID = reporting:1.0.
2. تنفيذ Canonicalization (C14N) ثم تجزئة SHA-256 → Base64 لإنتاج InvoiceHash.
3. تطبيق توقيع رقمي XAdES-B-B enveloped بخوارزمية ECDSA/SHA-256 باستخدام مفتاح PCSID.
4. حساب PIH = تجزئة الفاتورة السابقة وإدراجها في cac:AdditionalDocumentReference بمعرِّف PIH.
5. بناء QR بـ9 حقول TLV وتشفيرها Base64.
6. إرسال الفاتورة إلى نقطة النهاية المناسبة:
   • فاتورة B2C: POST /e-invoicing/core/invoices/reporting/single
   • فاتورة B2B: POST /e-invoicing/core/invoices/clearance/single مع ترويسة Clearance-Status: 1.

الخطوة 8: الأرشفة وتجديد الشهادة

يلتزم النظام بحفظ كل XML صادر مع استجابة زاتكا لمدة 6 سنوات (15 سنة للفواتير المرتبطة بالعقارات)، وتخزين سلسلة التجزئة محلياً لضمان صحة كل PIH جديد. قبل انتهاء Production CSID بأسبوعين على الأقل، أعد تنفيذ الخطوات 2 و3 و6 لتحديث الشهادة.

نقاط النهاية الرسمية لمنصة فاتورة

🔎 ملاحظة مهمة: بيئة المحاكاة (Simulation) تستعمل نفس الهيكل مع مقطع /simulation/ بدل /core/، وSandbox المطوِّرين يستعمل /developer-portal/. تأكَّد من استخدام قالب الشهادة الصحيح لكل بيئة (ZATCA-، PREZATCA-، أو TSTZATCA-).

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

بنية UBL 2.1 XML المختصرة

كل فاتورة تبدأ بعنصر الجذر <Invoice> مع فضاءات الأسماء cac/cbc/ext، وتحتوي على العناصر الإلزامية التالية:

• cbc:ProfileID دائماً reporting:1.0.
• cbc:ID، cbc:UUID، cbc:IssueDate، cbc:IssueTime.
• cbc:InvoiceTypeCode name="0100000|0200000" مع القيمة 388/381/383.
• cbc:DocumentCurrencyCode = SAR، وcbc:TaxCurrencyCode = SAR.
• cac:AdditionalDocumentReference بمعرِّفات ICV و PIH (و QR للمبسطة).
• cac:AccountingSupplierParty وcac:AccountingCustomerParty.
• cac:InvoiceLine لكل بند مع TaxTotal وPrice.
• cac:TaxTotal الإجمالي + cac:LegalMonetaryTotal.
• ext:UBLExtensions لاحتضان توقيع XAdES مع KeyInfo/X509Data وخصائص QualifyingProperties.

بنية QR code بترميز TLV (9 حقول في المرحلة 2)

كل حقل يُكتَب بالشكل [Tag:1 byte][Length:1 byte][Value]، ثم تُدمج البايتات وتُشفَّر Base64:

الطول الأقصى لنص الناتج 700 حرف كحد أعلى.

سلسلة التجزئة PIH: كيف تضمن عدم التلاعب

القاعدة: PIH_N = Base64( SHA-256( Canonical XML(N-1) ) ) – مع استبعاد UBLExtensions وAdditionalDocumentReference[ID='QR'] وأي Signature سابق من الحساب. أول فاتورة تستعمل البذرة الثابتة:

NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==

أي فاتورة ترفَض أيضاً تحتفظ بموقعها في السلسلة: PIH التالي = تجزئة الفاتورة المرفوضة، لا المقبولة قبلها. ولكن عدّاد ICV لا تُستعمل مرتين حتى لو فشلت الفاتورة.

الأخطاء الشائعة وحلولها السريعة

أخطاء توليد CSR

• «X509Certificate is not valid for this VAT Registration Number» – الرقم الضريبي في UID لا يطابق حساب ERAD.
• «invalid certificateTemplateName» – استخدمت قالب الإنتاج في بيئة المحاكاة أو العكس.
• «invalid SN format» – تحقَّق أن SN في subjectAltName بالصيغة 1-x|2-y|3-z.

أخطاء الطابع الزمني

• «Time on QR Code does not match Invoice Issue Time (KSA-25)» – عدم تزامن ساعة الكاشير مع NTP. زامن الجهاز مع time.google.com واحسب الطابع الزمني مرة واحدة لكل فاتورة.
• OTP expired – تجاوز ساعة كاملة منذ التوليد. أعد التوليد وأكمل خلال النافذة.

أخطاء التجزئة والتوقيع

• «invalid-invoice-hash» – XML عُدِّل بعد حساب التجزئة. احسب التجزئة آخر شيء، ولا تُعِد تنسيق XML بعدها.
• «invoiceSignedDataDigestValue» – لم تُطبَّق الاستبعادات الصحيحة قبل C14N.
• «SignatureValue does not verify» – مفتاح التوقيع لا يطابق الشهادة، أو ترميز غير DER.
• «QRCODE_INVALID» – حقول 6–9 ناقصة (لا زيت على QR المرحلة 1).

أخطاء السلسلة والتسلسل

• «PIH mismatch» – اعتمدت تجزئة فاتورة مقبولة وتجاهلت فاتورة مرفوضة بينهما.
• «ICV must be sequential» – عدّاد ICV قفز أو أعيد استخدامه.
• «Duplicate invoice ID» – إعادة إرسال نفس cbc:ID بعد رفض. أنشئ رقماً جديداً.

أخطاء رمز نوع الفاتورة

• «Invalid InvoiceTypeCode / name attribute» – نواع KSA-2 خاطئ. مثلاً «simplified export» غير مسموح لأن التصدير لا بدّ أن يكون قياسياً.
• «BR-KSA-37» – رقم المبنى يجب أن يكون 4 أرقام بالضبط.
• «Missing BillingReference» – كل إشعار دائن أو مدين يجب أن يشير إلى الفاتورة الأصلية في cac:BillingReference.

لماذا «هلا إنفويس» ينجز هذه الطبقة عنك؟

كل ما سبق يتطلب فريق تطوير متخصص في التشفير، وتجزئة XML، وسلاسل التجزئة، والامتثال الضريبي. هلا إنفويس يختصر هذه الطبقة كلياً: يدير CSR و CSID، وينفِّذ اختبارات الامتثال نيابة عن عميله، ويوقِّع الفواتير بـ ECDSA secp256k1، ويُولِّد QR بـ9 حقول TLV، ويحافظ على سلسلة PIH، ويرسل إلى نموذجَي المشاركة والإبلاغ بحسب نوع الفاتورة، مع أرشفة سحابية 6 سنوات. كل ذلك خلف واجهة عربية أولاً ولوحة تحكم للتقارير الضريبية. نحن نجعل الامتثال زاتكا تلقائياً وغير مرئي بالنسبة لصاحب المنشأة.

جرّب المولّد المجاني الآن

أسئلة شائعة حول ربط الكاشير بزاتكا في المرحلة الثانية