دليل بيئة المحاكاة (Sandbox) للمطوّرين

بعد أن تفهم مفهوم بيئة المحاكاة (Sandbox) ودورها في المرحلة الثانية من الفوترة الإلكترونية، تأتي الخطوة العملية: أن تجلس أمام محرّر الأوامر وتُجري تكاملك الحقيقي مع منصة فاتورة (Fatoora). هذا الدليل هو الجزء العملي. لا نشرح هنا ما هي بيئة المحاكاة ولماذا تشترطها هيئة الزكاة والضريبة والجمارك (ZATCA)، بل نمسك بيدك خطوة بخطوة: كيف تحصل على وصول للبيئة، وكيف تستخرج شهادة الامتثال (Compliance CSID)، وكيف تُرسل أول فاتورة اختبارية، وما المستندات الأربعة التي يجب أن تختبرها، وكيف تقرأ ردود الهيئة، وما الأخطاء الشائعة التي تعطّل المطوّرين في أول يوم.

الجمهور المستهدف هنا واضح: مطوّر أو فريق تكامل تقني يربط نظامه بمنصة فاتورة لأول مرة. نفترض أنك تتعامل مع طلبات HTTP، وتعرف ما الـ JSON، وتستطيع تشغيل أمر curl أو ما يماثله. كل ما تبقّى نشرحه بالتفصيل.

قبل أن تبدأ: ما الذي تحتاجه فعلياً

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

• الرقم الضريبي للمنشأة (VAT Registration Number) المكوّن من 15 رقماً، أو رقم تجريبي صالح للاختبار.
• رمز التحقّق لمرة واحدة (OTP) الذي تولّده من بوابة فاتورة لربط جهازك.
• أداة لتوليد طلب توقيع الشهادة (CSR) وزوج المفاتيح، مثل OpenSSL أو مكتبة تشفير في لغتك.
• عميل HTTP يدعم Basic Authentication والترويسات المخصّصة (curl، Postman، أو كود في تطبيقك).
• نموذج فاتورة بصيغة UBL 2.1 (سنشرح من أين تأتي).

لاحظ أن بيئة المحاكاة معزولة تماماً عن الإنتاج. أي رقم ضريبي أو بيانات تستخدمها هنا لا تترتّب عليها التزامات قانونية. هذا يمنحك حرية كاملة في التجربة والخطأ.

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

ثلاث بيئات لا تخلط بينها

تتيح الهيئة ثلاث بيئات منفصلة، ولكل واحدة عنوان نهاية (base URL) مختلف. الخلط بينها هو أول مصدر للأخطاء. إليك الفرق الجوهري:

• بيئة المحاكاة (Sandbox / Developer Portal): للتجربة الحرّة والتعلّم. لا تحتاج إلى ربط فعلي للجهاز، وتعيد لك ردوداً واقعية لتفهم سلوك الواجهات.
• بيئة الامتثال (Simulation): هنا تستخرج شهادة الامتثال (Compliance CSID) وتُجري فحوص الامتثال الإلزامية على المستندات قبل الإنتاج.
• بيئة الإنتاج (Production): الفواتير القانونية الفعلية. لا تصلها إلا بعد اجتياز فحوص الامتثال واستخراج شهادة الإنتاج.

هذا الدليل يركّز على البيئتين الأوليين، لأنهما حيث يقضي المطوّر معظم وقته قبل الانتقال للإنتاج.

الخطوة 1: الحصول على وصول لبيئة المحاكاة

تبدأ الرحلة من بوابة المطوّرين التي توفّرها الهيئة ضمن منصة فاتورة. الوصول الأول لا يتطلّب أكثر من توليد رمز تحقّق لمرة واحدة (OTP) من البوابة، ثم استخدامه لربط جهازك واستخراج أول شهادة.

الفكرة الأساسية: نظامك لا يُصادق باسم مستخدم وكلمة مرور. بدلاً من ذلك، يولّد زوج مفاتيح تشفيري (خاص وعام)، ثم يرسل طلب توقيع شهادة (CSR) إلى الهيئة مرفقاً برمز الـ OTP. ترد الهيئة بشهادة امتثال تستخدمها لاحقاً في توقيع كل طلب. هذه الآلية مشروحة بالتفصيل في دليل المصادقة في واجهة الفوترة، وهي الأساس الذي يقوم عليه كل ما يلي.

توليد زوج المفاتيح وطلب التوقيع (CSR)

الخطوة التقنية الأولى هي توليد المفتاح الخاص وطلب توقيع الشهادة. تستخدم الهيئة منحنى التشفير secp256k1. إليك الأمر باستخدام OpenSSL:

openssl ecparam -name secp256k1 -genkey -noout -out ec-private-key.pem

openssl req -new -sha256 -key ec-private-key.pem -out taxpayer.csr \
  -config csr-config.cnf

يحتوي ملف الإعداد csr-config.cnf على حقول إلزامية تطلبها الهيئة، أبرزها اسم الوحدة التنظيمية، والرقم الضريبي، ونوع الفاتورة المدعوم. مثال مبسّط لمحتواه:

[req]
distinguished_name = req_dn
prompt = no
req_extensions = v3_req

[req_dn]
CN = TST-MyCompany
O = My Company LLC
OU = 1234567890
C = SA

[v3_req]
subjectAltName = dirName:alt_names

[alt_names]
SN = 1-MyApp|2-1.0|3-test-device-001
UID = 312345678900003
title = 1100
registeredAddress = Riyadh
businessCategory = Technology

لاحظ حقل UID: هو الرقم الضريبي المكوّن من 15 رقماً. وحقل title بقيمة 1100 يعني أن جهازك سيُصدر فواتير ضريبية قياسية ومبسّطة معاً. هذه الأرقام لها دلالة محدّدة لدى الهيئة، فلا تخترعها عشوائياً.

تبادل الـ CSR مقابل شهادة الامتثال

بعد توليد الـ CSR، ترسله إلى نقطة نهاية الامتثال مرفقاً برمز الـ OTP. الطلب يبدو هكذا:

POST /compliance HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
OTP: 123456
Accept-Version: V2
Content-Type: application/json

{
  "csr": "<BASE64_ENCODED_CSR>"
}

إذا نجح الطلب، تعيد لك الهيئة استجابة تحتوي على ثلاثة عناصر حاسمة: شهادة الامتثال نفسها (binarySecurityToken)، والسرّ المرافق (secret)، ومعرّف الطلب (requestID). هذه الثلاثة هي مفتاحك لكل ما يأتي بعدها.

{
  "requestID": 1234567890123,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "TUlJRC...<مقتطع>",
  "secret": "Xy9...<مقتطع>",
  "errors": null
}

احفظ قيمة binarySecurityToken وsecret في مكان آمن. هاتان القيمتان معاً تشكّلان بيانات اعتماد الـ Basic Authentication: تضع الرمز في موضع اسم المستخدم، والسرّ في موضع كلمة المرور، وتشفّرهما بصيغة Base64.

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

قبل أن نُرسل أول فاتورة، يجب أن تكون العلاقة بين الشهادات واضحة في ذهنك. كثير من المطوّرين يخلطون بين شهادة الامتثال وشهادة الإنتاج، فيقعون في رفض غير مفهوم عند الانتقال.

شهادة الامتثال (Compliance CSID) هي شهادة مؤقتة الغرض. مهمتها الوحيدة أن تسمح لك بإجراء فحوص الامتثال على عيّنة من المستندات. لا تصلح لإصدار فواتير في الإنتاج. بعد أن تجتاز هذه الفحوص بنجاح، تطلب من الهيئة ترقية شهادتك إلى شهادة إنتاج (Production CSID) عبر نقطة نهاية منفصلة، وعندها فقط تبدأ بإصدار فواتير قانونية.

التسلسل المنطقي إذن:

• تولّد المفاتيح والـ CSR.
• تستخرج شهادة الامتثال مقابل الـ OTP.
• تُجري فحوص الامتثال على المستندات الأربعة.
• تطلب شهادة الإنتاج بعد النجاح.
• تبدأ الإصدار الفعلي في الإنتاج.

هذه التسمية مهمة: الاختصار الصحيح هو CSID (Cryptographic Stamp Identifier)، وهو ما تديره الأنظمة المتوافقة تلقائياً نيابة عن المنشأة كما تشرحه صفحة لمحة عن واجهة API للفوترة الإلكترونية.

الخطوة 3: إرسال أول فاتورة اختبارية

الآن وصلنا إلى اللحظة التي ينتظرها كل مطوّر: إرسال أول مستند فعلي. هناك واجهتان رئيسيتان تتعامل معهما:

• واجهة الامتثال (/compliance/invoices): تستخدمها أثناء مرحلة الفحوص بشهادة الامتثال.
• واجهتا المقاصة والإبلاغ (/invoices/clearance/single و/invoices/reporting/single): تستخدمهما في الإنتاج، الأولى للفواتير القياسية (B2B) والثانية للمبسّطة (B2C).

أثناء العمل في بيئة المحاكاة، تركّز على واجهة الامتثال. شكل الطلب:

POST /compliance/invoices HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic <BASE64(binarySecurityToken:secret)>
Accept-Version: V2
Content-Type: application/json

{
  "invoiceHash": "<SHA256_HASH_BASE64>",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "<BASE64_ENCODED_UBL_XML>"
}

الحقول الثلاثة الإلزامية: تجزئة الفاتورة (invoiceHash) المحسوبة بخوارزمية SHA-256، والمعرّف الفريد (uuid)، ومحتوى الفاتورة بصيغة UBL 2.1 مرمّزاً بـ Base64. توليد الـ XML الصحيح هو الجزء الأصعب، لذا ننصح بشدّة باستخدام مولّد متوافق مع المواصفة بدلاً من كتابته يدوياً.

بناء ترويسة المصادقة

قيمة ترويسة Authorization تُبنى بدمج رمز الشهادة والسرّ بنقطتين بينهما، ثم ترميزهما بـ Base64:

# بصيغة سطر أوامر مبسّطة
CREDENTIALS=$(printf '%s:%s' "$BINARY_SECURITY_TOKEN" "$SECRET" | base64 -w0)

curl -X POST "https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices" \
  -H "Authorization: Basic ${CREDENTIALS}" \
  -H "Accept-Version: V2" \
  -H "Content-Type: application/json" \
  -d @invoice-request.json

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

الخطوة 4: المستندات الأربعة التي يجب أن تختبرها

فحص الامتثال ليس فحص فاتورة واحدة، بل سلسلة فحوص على أنواع المستندات التي تدعمها منشأتك. الهيئة تشترط أن تجتاز عيّنة تمثّل كل نوع مستند صرّحت بدعمه في الـ CSR. إن أعلنت في الحقل title=1100 أنك تدعم القياسية والمبسّطة معاً، فعليك اختبار كليهما بكل مشتقاتهما.

المستندات الأربعة الأساسية:

• الفاتورة الضريبية القياسية (Standard / B2B): الفاتورة الموجَّهة لمنشأة أخرى، وتمرّ بالمقاصة (Clearance) في الإنتاج. يجب أن تحمل توقيعاً تشفيرياً كاملاً وختماً من الهيئة.
• الفاتورة الضريبية المبسّطة (Simplified / B2C): الموجَّهة للمستهلك النهائي، وتمرّ بالإبلاغ (Reporting) خلال 24 ساعة في الإنتاج. تحمل رمز QR.
• الإشعار الدائن (Credit Note): يُصدَر لتصحيح فاتورة سابقة بالنقصان، مثل مرتجع أو خصم لاحق.
• الإشعار المدين (Debit Note): يُصدَر لزيادة مبلغ فاتورة سابقة، مثل رسوم إضافية لم تُحتسب أصلاً.

لكل نوع يجب أن تُرسل النسخة القياسية والنسخة المبسّطة إن كنت تدعمهما. عملياً قد يصل عدد عيّنات الفحص إلى ستة أو ثمانية مستندات. الهيئة تتحقّق أن كلاً منها يحمل الحقول الصحيحة، والتسلسل الصحيح للتجزئة (hash chain)، والتوقيع السليم.

سلسلة التجزئة (Hash Chain) في عيّنة الفحص

نقطة دقيقة يغفل عنها كثيرون: كل فاتورة تحمل تجزئة الفاتورة السابقة لها في حقل PIH (Previous Invoice Hash). أول مستند في السلسلة يحمل قيمة أوّلية ثابتة:

PIH (للفاتورة الأولى):
NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZj... (القيمة المعيارية الأولى)

كل مستند تالٍ يجب أن يحمل تجزئة المستند الذي سبقه. إن كسرت هذا التسلسل، يرفض الفحص الفاتورة برسالة تخصّ سلامة السلسلة. احرص أن يولّد نظامك هذه القيم آلياً ولا تتلاعب بها يدوياً.

الخطوة 5: قراءة ردود الهيئة

كل طلب فحص يعيد لك استجابة JSON تحمل قرار الهيئة. القراءة الصحيحة لهذه الردود هي ما يفصل بين تكامل يعمل وآخر يدور في حلقة محاولات عمياء. الحقل المحوري هو clearanceStatus أو reportingStatus، إضافة إلى مصفوفتي warnings وerrors.

هناك ثلاث نتائج ممكنة لكل مستند:

• قبول كامل (CLEARED / REPORTED): الفاتورة سليمة تماماً ومرّت بكل الفحوص. لا إجراء مطلوب.
• قبول مع تحذيرات (CLEARED_WITH_WARNINGS): الفاتورة قُبلت لكن فيها ملاحظات غير حرجة. اقرأ مصفوفة warnings وعالجها قبل الإنتاج.
• رفض (NOT_CLEARED / NOT_REPORTED): الفاتورة فشلت في فحص حرج. مصفوفة errors تحمل سبب الرفض ورمزه.

مثال على استجابة رفض:

{
  "validationResults": {
    "infoMessages": [],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-15",
        "category": "KSA",
        "message": "Invoice type code must be a valid value"
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED"
}

الرمز BR-KSA-15 هنا يخبرك بالضبط أين الخلل: رمز نوع الفاتورة غير صالح. كل رمز يبدأ بـ BR-KSA هو قاعدة عمل خاصة بالسعودية، أما الذي يبدأ بـ BR- فهو قاعدة عامة من مواصفة UBL. تعلّم قراءة هذه الرموز يوفّر عليك ساعات من التخمين.

جدول رموز الحالة التي ستقابلها

إلى جانب قرار الفحص داخل الـ JSON، يحمل كل رد رمز حالة HTTP يخبرك بطبيعة النتيجة على مستوى البوابة قبل منطق الفحص. فهم هذه الرموز يختصر زمن التشخيص:

• 200: الطلب وصل وعُولج، والفاتورة قُبلت بالكامل. اقرأ مع ذلك مصفوفة التحذيرات.
• 202: الطلب عولج لكن الفاتورة قُبلت مع تحذيرات. النتيجة سليمة، لكن راجع الملاحظات.
• 303: دلالة في بعض الواجهات على أن المستند سبق رفعه، أو على إعادة توجيه. اقرأ جسم الرد لا الرمز وحده.
• 400: الفاتورة فشلت في فحص حرج. السبب في مصفوفة errorMessages.
• 401: فشل المصادقة. راجع ترويسة Authorization والشهادة المستخدمة.
• 500: خطأ من جانب الخادم. أعد المحاولة بعد مهلة قصيرة، ولا تعتبره رفضاً للفاتورة.

قاعدة مهمة: لا تبنِ منطقك على رمز الحالة وحده. الفاتورة قد تُرفض داخل رد يحمل الرمز 200 إذا كان حقل القرار NOT_CLEARED. اقرأ دائماً الحقلين معاً: رمز HTTP وحقل القرار داخل الجسم.

الخطوة 6: بناء الطلب داخل الكود خطوة بخطوة

حتى الآن استخدمنا curl للتوضيح. عملياً ستبني الطلب داخل تطبيقك بلغة برمجة. التسلسل ثابت بغض النظر عن اللغة، ونعرضه هنا كخطوات منطقية يمكنك تنفيذها بأي مكتبة HTTP وتشفير:

• جهّز مستند الفاتورة (XML): ولّد مستند UBL 2.1 من بيانات الفاتورة، وأدرج امتدادات الهيئة الإلزامية.
• احسب التجزئة (Hash): طبّق SHA-256 على المستند المُقنّن (canonicalized) واحفظ الناتج بصيغة Base64. هذه قيمة invoiceHash.
• وقّع الفاتورة القياسية: أنشئ توقيع XML باستخدام مفتاحك الخاص، وأدرجه ضمن UBLExtensions. الفاتورة المبسّطة لا تمرّ بالمقاصة لكنها تحتاج توقيعاً للإبلاغ.
• رمّز الفاتورة: حوّل المستند الكامل إلى Base64 ليصبح قيمة حقل invoice.
• ابنِ الجسم وأرسل: جمّع invoiceHash وuuid وinvoice في كائن JSON، وأرسله بترويسة المصادقة الصحيحة.

مثال على جسم الطلب مكتملاً قبل الإرسال:

{
  "invoiceHash": "QtTr6QyW...<hash مقتطع>=",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi...<مقتطع>"
}

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

طلب ترقية الشهادة إلى الإنتاج

بعد أن تجتاز عيّنة الفحص بنجاح، تطلب شهادة الإنتاج عبر نقطة نهاية مخصّصة. تستخدم في هذا الطلب شهادة الامتثال نفسها للمصادقة، ومعرّف الطلب (requestID) الذي حصلت عليه عند استخراج شهادة الامتثال:

POST /production/csids HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic <BASE64(complianceToken:secret)>
Accept-Version: V2
Content-Type: application/json

{
  "compliance_request_id": "1234567890123"
}

إن نجح الطلب، تعيد لك الهيئة شهادة إنتاج جديدة (binarySecurityToken وsecret جديدين). من هذه اللحظة، تتوقّف عن استخدام بيانات الامتثال نهائياً وتستخدم بيانات الإنتاج فقط. الخلط بينهما بعد الترقية سبب شائع لرسائل الرفض الأولى في الإنتاج.

الخطوة 7: الأخطاء الشائعة في الإعداد

جمعنا هنا أكثر العقبات تكراراً في أول يوم تكامل، مع سبب كل منها وحلّه المباشر. مراجعة هذه القائمة قبل أن تبدأ توفّر عليك معظم رسائل الرفض الغامضة.

الخلط بين عناوين البيئات

أكثر خطأ شيوعاً: استخدام عنوان بيئة الامتثال (Simulation) لإرسال طلب يفترض أنه في المحاكاة، أو العكس. كل بيئة لها مسار مختلف ضمن النطاق نفسه. تحقّق أن المسار يحتوي على simulation أو developer-portal حسب البيئة المقصودة قبل كل طلب.

ترميز الشهادة بصيغة خاطئة

قيمة binarySecurityToken التي تعيدها الهيئة مرمّزة بـ Base64 أصلاً. بعض المطوّرين يفكّون ترميزها ثم يعيدون ترميزها قبل وضعها في ترويسة المصادقة، فينتج رمز مكسور. القاعدة: استخدم القيمة كما هي عند بناء بيانات Basic Authentication.

عدم توافق الـ XML مع مواصفة UBL 2.1

الفاتورة ليست JSON بسيطاً، بل مستند XML منظّم بدقّة وفق UBL 2.1 مع امتدادات الهيئة. غياب عنصر إلزامي أو ترتيب خاطئ للعناصر يسبب رفضاً فورياً. لا تكتب الـ XML يدوياً، واعتمد على مولّد متوافق يُجري التحقّق محلياً قبل الإرسال.

التوقيع التشفيري غير الصحيح

الفاتورة القياسية تحتاج توقيعاً تشفيرياً (XML Signature) مبنياً على مفتاحك الخاص وشهادتك. خطأ في حساب التوقيع أو في إدراجه ضمن امتداد UBLExtensions يُفشل الفحص. تأكّد أن مكتبة التوقيع لديك تتبع خوارزمية الهيئة بدقّة.

تجاهل التحذيرات قبل الإنتاج

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

رمز QR في الفاتورة المبسّطة

الفاتورة المبسّطة الموجَّهة للمستهلك النهائي تحمل رمز QR إلزامياً. هذا الرمز ليس صورة زخرفية، بل حقل بيانات منظّم بصيغة TLV (Tag-Length-Value) يحتوي على معلومات الفاتورة الأساسية مرمّزة بـ Base64. الهيئة تتحقّق من بنيته في فحص الامتثال، فلا تتعامل معه باستخفاف.

الحقول الإلزامية داخل رمز QR للمرحلة الثانية:

• اسم البائع: الاسم القانوني للمنشأة المُصدِرة.
• الرقم الضريبي للبائع: رقم تسجيل ضريبة القيمة المضافة (15 رقماً).
• الطابع الزمني: تاريخ ووقت إصدار الفاتورة بصيغة ISO 8601.
• الإجمالي شاملاً الضريبة: المبلغ الكلّي للفاتورة.
• قيمة ضريبة القيمة المضافة: مبلغ الضريبة المحتسب.
• تجزئة الفاتورة: قيمة الـ hash بصيغة Base64.
• التوقيع التشفيري والمفتاح العام: لإثبات أصالة الفاتورة.

إن أصدر نظامك فواتير مبسّطة، اختبر رمز QR في بيئة المحاكاة بقراءته بأي تطبيق ماسح، ثم تحقّق أن الحقول كلها تظهر صحيحة. خطأ شائع: ترتيب وسوم TLV بشكل خاطئ، فيقرأ الماسح بيانات مشوّهة رغم أن الفحص قد يمرّ. التحقّق البصري خطوة ضرورية لا تتجاوزها.

أتمتة دورة الاختبار

إعادة تنفيذ الخطوات يدوياً لكل مستند مرهق وعرضة للخطأ. ننصح المطوّرين ببناء سكربت بسيط يكرّر دورة الاختبار آلياً. الفكرة أن تُجهّز ملفات فواتير عيّنة، ثم تمرّر كل واحد عبر الدورة نفسها وتسجّل النتيجة.

هيكل منطقي لسكربت الاختبار:

# لكل ملف فاتورة في مجلد العيّنات:
#   1) احسب التجزئة (hash)
#   2) وقّع المستند إن كان قياسياً
#   3) رمّزه Base64
#   4) ابنِ جسم JSON
#   5) أرسله إلى /compliance/invoices
#   6) سجّل clearanceStatus + أي errorMessages في تقرير

for invoice in samples/*.xml; do
  ./run-compliance-check.sh "$invoice" >> compliance-report.log
done

تقرير مجمّع كهذا يكشف بسرعة أي نوع مستند ما زال يفشل، فتركّز جهدك حيث المشكلة فعلاً. كما يصلح أساساً لاختبارات الانحدار (regression) عند تحديث مولّد الـ XML لديك مستقبلاً. الاستثمار في الأتمتة من اليوم الأول يوفّر ساعات لاحقة، خاصة مع تعدّد المستندات وتكرار التجارب.

نصيحة أخيرة قبل الانتقال للقسم التالي: احتفظ بنسخة من كل طلب ورد كامل أثناء التطوير. سجلّ الطلبات والاستجابات هو أداتك الأولى عند تشخيص أي رفض غامض، ويغنيك عن إعادة بناء السياق من الصفر في كل مرة.

كيف يساعدك قيود في الربط مع منصة فاتورة

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

• إدارة دورة حياة الشهادات تلقائياً: يتولّى قيود توليد المفاتيح، وطلب شهادة الامتثال، وترقيتها إلى شهادة إنتاج، وتجديدها عند انتهائها، دون تدخّل منك.
• توقيع وختم كل فاتورة: كل فاتورة قياسية تُوقَّع تشفيرياً وتمرّ بالمقاصة، وكل فاتورة مبسّطة تُبلَّغ خلال المدة النظامية، مع رمز QR والمعرّف الفريد UUID وسلسلة التجزئة تلقائياً.
• توليد XML المتوافق مع UBL 2.1: يبني قيود مستند الفاتورة بالصيغة الصحيحة، فلا تتعامل مع تعقيد المواصفة ولا مع رسائل الرفض الغامضة.
• أنواع المستندات الأربعة جاهزة: الفاتورة القياسية والمبسّطة والإشعار الدائن والمدين، كلها مدعومة من واجهة الاستخدام مباشرة دون كتابة كود.

بهذا تحصل على ثمرة كل ما شرحناه في هذا الدليل، دون أن تبني التكامل أو تصونه بنفسك. تركّز أنت على عملك، ويتكفّل قيود بالامتثال.

متى تبني التكامل بنفسك ومتى تعتمد على حلّ جاهز

القرار بين بناء تكامل مباشر مع منصة فاتورة وبين الاعتماد على نظام متوافق ليس قراراً تقنياً بحتاً، بل قرار موارد وأولويات. لكل مسار سياقه المناسب:

• ابنِ بنفسك إن كان التكامل جزءاً من منتجك: لو كنت تطوّر نظاماً برمجياً تبيعه لمنشآت أخرى وتريد التحكّم الكامل في كل تفصيل، فالبناء المباشر منطقي. لكن خصّص فريقاً يتابع تحديثات المواصفة باستمرار.
• اعتمد على حلّ جاهز إن كانت الفوترة وسيلة لا غاية: لو كانت منشأتك تحتاج إصدار فواتير متوافقة فقط دون أن تكون الفوترة منتجها، فبناء التكامل من الصفر إهدار للموارد. النظام المتوافق يحقّق الهدف نفسه أسرع وأرخص.
• وازن تكلفة الصيانة: الربط المباشر ليس مشروعاً ينتهي عند أول فاتورة ناجحة. المواصفة تتغيّر، والشهادات تنتهي، والقواعد تُشدَّد. تكلفة الصيانة المستمرة غالباً أعلى من تكلفة البناء الأولي.

أياً كان قرارك، فهم المسار العملي الذي شرحناه هنا يجعلك مفاوضاً أفضل ومقيّماً أدقّ، سواء قدت الفريق التقني بنفسك أو اخترت شريكاً يتولّى الأمر عنك.

خلاصة عملية قبل أن تنتقل إلى الإنتاج

وصلت الآن إلى نهاية المسار العملي. قبل أن تطلب شهادة الإنتاج، راجع هذه القائمة القصيرة بصفتها بوابة أخيرة:

• ولّدت زوج مفاتيح صحيحاً واستخرجت شهادة الامتثال مقابل رمز OTP صالح.
• أرسلت عيّنة تغطّي كل نوع مستند صرّحت بدعمه في الـ CSR.
• حصلت على نتيجة قبول لكل مستند، وعالجت كل تحذير ظهر في مصفوفة warnings.
• تأكّدت من سلامة سلسلة التجزئة عبر العيّنة كلها.
• تحقّقت أنك تستخدم العنوان الصحيح لكل بيئة، وأن ترويسة المصادقة مبنية بالقيم كما تعيدها الهيئة.

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