تكامل API مع منصة فاتورة

هذا الدليل موجّه للمطوّرين وفِرَق التكامل التقني الذين يربطون أنظمتهم بمنصة فاتورة في الفوترة الإلكترونية في السعودية. لا يشرح القصة المفاهيمية لربط المنشأة بالهيئة، بل يفصّل الواجهات البرمجية (APIs) نفسها: نقاط النهاية (Endpoints)، وترويسات المصادقة (Auth Headers)، وأشكال الطلب والاستجابة (Request/Response)، ورموز الحالة (Status Codes)، ومسار الانتقال من الامتثال إلى الإنتاج على مستوى الـ API.

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

تتعامل منصة فاتورة مع أربع واجهات برمجية أساسية تغطّي دورة حياة الربط بالكامل: واجهة الامتثال (Compliance)، وواجهة الإصدار والإنتاج (Onboarding / Production CSID)، وواجهة المصادقة (Clearance)، وواجهة الإبلاغ (Reporting). نمرّ على كل واحدة منها بنقطة نهايتها وترويساتها وحمولتها (Payload) ورموز حالتها.

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

نظرة على واجهات منصة فاتورة الأربع

قبل أي طلب HTTP، يهمّك أن تفهم أن الواجهات الأربع تنقسم وظيفيًا إلى مجموعتين. مجموعة إعداد الهوية الرقمية للجهاز (Compliance و Onboarding)، ومجموعة تشغيل الفواتير اليومية (Clearance و Reporting). الأولى تُنفَّذ مرة عند ربط كل جهاز، والثانية تُنفَّذ مع كل فاتورة.

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

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

سبب تغليف XML داخل JSON أن المنصة تفصل بين طبقة النقل وطبقة المستند. JSON هو غلاف النقل الذي يحمل البيانات الوصفية مثل التجزئة والمعرّف الفريد، بينما XML هو المستند الضريبي الرسمي الذي تفحصه الهيئة وتوقّعه. هذا الفصل يعني أنك تتعامل مع تنسيقين في كل طلب: تبني XML الفاتورة وفق UBL، ثم ترمّزه بـ Base64 وتضعه في حقل JSON واحد.

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

الجدول التالي يلخّص الأربع قبل أن نغوص في كل واحدة:

لاحظ أن الفرق بين المصادقة والإبلاغ ليس في شكل الـ API بل في توقيته وأثره: المصادقة تسبق التسليم وتعيد فاتورة معتمدة، والإبلاغ يلي التسليم ويكتفي بإثبات الاستلام. نفصّل كلًّا منهما في دليلَيه: المصادقة (Clearance) والإبلاغ (Reporting).

المصادقة على الطلبات: ترويسات الـ Auth والشهادات

توثيق الطلبات في منصة فاتورة لا يعتمد على رمز OAuth وحده، بل على ثنائية الشهادة الرقمية ومفتاحها السري. كل طلب لواجهات الفواتير يحمل في ترويساته شهادة CSID مُرمَّزة بـ Base64 في خانة الاسم، وكلمة السر المصاحبة لها في خانة كلمة السر، وفق نمط Basic Authentication القياسي.

الشهادة هنا هي محور الهوية الرقمية للجهاز. تبدأ بشهادة امتثال مؤقتة (Compliance CSID) للاختبار، ثم تُستبدل بشهادة إنتاج (Production CSID) للتشغيل الحي. تفاصيل هذه الشهادة وكيفية توليدها مشروحة في دليل شهادة CSID.

من المهم أن تميّز بين دورين تلعبهما الشهادة. الدور الأول مصادقة الطلب نفسه على البوابة، وهنا تُرسل الشهادة في ترويسة Authorization لتثبت أن من يطرق الباب جهاز معروف ومسجّل. الدور الثاني توقيع الفاتورة، وهنا يُستخدم المفتاح الخاص المرتبط بالشهادة لإنشاء الختم المشفّر داخل XML. الدوران منفصلان: الأول على مستوى النقل، والثاني على مستوى المستند.

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

هذا مثال لترويسات طلب مصادقة قياسي. انتبه إلى أن قيمة Authorization هي ناتج ترميز «المعرّف:كلمة السر» بصيغة Base64، وأن OTP يُرسل فقط في طلبات الامتثال والإنتاج الأولى لا في كل فاتورة:

POST /invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Content-Type: application/json
Accept: application/json
Accept-Language: ar
Accept-Version: V2
Authorization: Basic VFVsSlEyd...<Base64(CSID:secret)>
Clearance-Status: 1

الترويسة Accept-Version: V2 إلزامية وتحدّد إصدار الواجهة. والترويسة Clearance-Status تخبر المنصة بأنك تطلب مصادقة فعلية لا مجرد فحص. حذف أي منهما يعيد لك رفضًا على مستوى البوابة قبل معالجة الفاتورة.

واجهة الامتثال (Compliance API)

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

يبدأ المسار بطلب توليد طلب توقيع شهادة (CSR) محليًا، ثم إرساله إلى نقطة النهاية التالية مصحوبًا برمز التحقق لمرة واحدة (OTP) الذي تحصل عليه من بوابة فاتورة:

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

{
  "csr": "<Base64-encoded-CSR>"
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "requestID": 1234567890123,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "<Base64-Compliance-CSID>",
  "secret": "<Base64-secret>"
}

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

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

{
  "invoiceHash": "<SHA-256-Base64>",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "<Base64-encoded-UBL-XML>"
}

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

قيمة invoiceHash في الطلب ليست اختيارية ولا شكلية. هي تجزئة SHA-256 لنسخة XML المُقَنَّنة (Canonicalized) قبل الترميز، وتُحسب وفق قواعد تقنين محددة في مواصفة الهيئة. أي اختلاف بين التجزئة المرسلة والتجزئة التي تحسبها المنصة من XML المرفق يعني رفضًا فوريًا، لأن المنصة تعتبر ذلك دليلًا على عبث محتمل بالمحتوى.

المعرّف الفريد uuid يجب أن يكون فريدًا لكل فاتورة على مستوى المنشأة بالكامل، لا على مستوى الجهاز فقط. ابنِ منطق توليده بحيث يستحيل تكراره حتى عند تعدّد نقاط البيع، لأن تكرار المعرّف يربك سلسلة التجزئة (Hash Chain) ويعطّل ربط الفاتورة بسابقتها.

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

واجهة الإصدار والإنتاج (Production CSID API)

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

طلب الإنتاج بسيط من حيث الشكل: يحمل معرّف طلب الامتثال الذي نجحت فيه، ويُوثَّق بشهادة الامتثال نفسها:

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

{
  "compliance_request_id": "1234567890123"
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "requestID": 9876543210987,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "<Base64-Production-CSID>",
  "secret": "<Base64-production-secret>"
}

تجديد شهادة الإنتاج عند قرب انتهائها يتم عبر نقطة النهاية نفسها مع طلب PATCH بدل POST وترويسة OTP جديدة. ابنِ منطقًا يتابع تاريخ انتهاء الشهادة لكل جهاز ويجدّدها مبكرًا، لأن انتهاءها يوقف توقيع الفواتير فورًا.

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

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

واجهة المصادقة (Clearance API)

المصادقة هي المسار الإلزامي للفاتورة الضريبية بين المنشآت (B2B). ترسل الفاتورة إلى المنصة، فتفحصها الهيئة وتوقّعها وتعيدها معتمدة، وعندها فقط يحق تسليمها للمشتري. أي فاتورة B2B لم تمرّ على هذه الواجهة ليست فاتورة نظامية.

نقطة النهاية تحمل ترويسة Clearance-Status: 1 للدلالة على طلب مصادقة فعلية. حمولة الطلب تتكوّن من قيمة التجزئة (Hash)، والمعرّف الفريد (UUID)، والفاتورة بصيغة XML مُرمَّزة بـ Base64:

POST /invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Content-Type: application/json
Accept-Version: V2
Clearance-Status: 1
Authorization: Basic <Base64(Production-CSID:secret)>

{
  "invoiceHash": "9f8c7d6e5b4a...",
  "uuid": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "invoice": "<Base64-encoded-UBL-XML>"
}

عند النجاح تعيد المنصة الفاتورة المعتمدة موقَّعة بختم الهيئة، مع حالة المصادقة. الحقل clearedInvoice هو نسخة XML الموقَّعة التي يجب أن تسلّمها للمشتري بدل النسخة الأصلية:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  },
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "<Base64-signed-UBL-XML>"
}

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

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

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

لا تخلط بين فحص الفاتورة (Clearance-Status: 0) وطلب المصادقة الفعلي (Clearance-Status: 1). الأول يعيد نتيجة التحقق دون اعتماد، وهو مفيد في الاختبار. الثاني هو الطلب الذي يعتمد الفاتورة فعليًا في الإنتاج. إرسال طلب فحص في الإنتاج ظنًّا أنه اعتماد يترك فاتورتك غير معتمدة.

واجهة الإبلاغ (Reporting API)

الإبلاغ هو مسار الفاتورة الضريبية المبسّطة الموجّهة للمستهلك (B2C). هنا تُسلَّم الفاتورة للمشتري فورًا عند البيع، ثم تُبلَّغ الهيئة بها خلال 24 ساعة كحد أقصى. لا تنتظر اعتمادًا مسبقًا، لأن المعاملة أُنجزت أصلًا.

شكل الطلب قريب جدًا من المصادقة، لكن نقطة النهاية مختلفة ولا تحمل ترويسة Clearance-Status، لأن الهدف إثبات الإبلاغ لا طلب الاعتماد:

POST /invoices/reporting/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Content-Type: application/json
Accept-Version: V2
Authorization: Basic <Base64(Production-CSID:secret)>

{
  "invoiceHash": "1a2b3c4d5e6f...",
  "uuid": "9z8y7x6w-5v4u-3t2s-1r0q-9p8o7n6m5l4k",
  "invoice": "<Base64-encoded-UBL-XML>"
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  },
  "reportingStatus": "REPORTED"
}

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

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

لكن لا تجعل الطابور الخلفي ذريعة للإهمال. أي فاتورة B2C لم تُبلَّغ خلال المهلة تتحوّل إلى مخالفة محتملة. راقب طول الطابور وعمر أقدم عنصر فيه، وأطلق تنبيهًا إن اقترب أي عنصر من حدّ الـ 24 ساعة. الإبلاغ المتأخر بصمت أخطر من الفشل الظاهر، لأنه يتراكم دون أن يلاحظه أحد.

رمز الاستجابة السريع (QR) على فاتورة B2C يجب أن يكون مكتملًا قبل التسليم، لا بعد الإبلاغ. الزبون قد يمسح الرمز للتحقق من الفاتورة، فلا يجوز أن ينتظر رد المنصة. يولّد نظامك الرمز محليًا من بيانات الفاتورة وختمك المشفّر بصيغة TLV المرمّزة بـ Base64، دون أي اعتماد على رد الهيئة.

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

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

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

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

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

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "validationResults": {
    "status": "ERROR",
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-44",
        "category": "KSA",
        "message": "Invalid VAT registration number format."
      }
    ]
  },
  "clearanceStatus": "NOT_CLEARED"
}

الجدول التالي يربط الرمز بالإجراء الموصى به في نظامك:

قاعدة عملية: الأخطاء في نطاق 4xx مصدرها بياناتك أنت، فلا فائدة من إعادة الإرسال دون تصحيح. أما 5xx فمصدرها المنصة، وإعادة المحاولة بتراجع أسّي (Exponential Backoff) هي التصرّف الصحيح. لا تعِد إرسال فاتورة B2C فاشلة بلا حد، بل أوقفها بعد عدد محاولات وأبلغ المستخدم لتفادي تجاوز مهلة الـ 24 ساعة بصمت.

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

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

أخيرًا، لا تعرض للمستخدم رمز الخطأ الخام. ترجم رمز BR-KSA إلى رسالة عربية مفهومة تخبر المحاسب بما يجب إصلاحه بالضبط: «الرقم الضريبي للمشتري بصيغة غير صحيحة» أوضح بكثير من سرد رمز تقني. هذه الطبقة من الترجمة هي ما يفصل تكاملًا قابلًا للاستخدام عن تكامل يربك مستخدميه.

الانتقال من الامتثال إلى الإنتاج على مستوى الـ API

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

الخطوات بالترتيب التقني:

• توليد طلب توقيع شهادة (CSR) داخل نظامك لكل جهاز.
• استدعاء POST /compliance مع رمز OTP للحصول على شهادة الامتثال المؤقتة.
• اختبار عينات الفواتير عبر POST /compliance/invoices حتى اجتياز كل الحالات الإلزامية.
• استدعاء POST /production/csids بمعرّف طلب الامتثال الناجح للحصول على شهادة الإنتاج.
• تبديل شهادة الامتثال بشهادة الإنتاج في كل الطلبات الحية.
• تشغيل الفواتير: المصادقة لـ B2B والإبلاغ لـ B2C مع كل معاملة.

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

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

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

أين يقع قيود في هذه الطبقة؟

قيود حل فوترة إلكترونية متوافق مع المرحلة الثانية من الفوترة الإلكترونية. يعني عمليًا أن قيود ينفّذ نيابةً عنك كل ما شرحناه في هذا الدليل دون أن تكتب سطر API واحدًا.

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

الدور هنا واضح: قيود هو منصة الانطلاق إلى منصة فاتورة، لا بديل عنها. منصة فاتورة إلزامية، وقيود يتولّى الطبقة التقنية كاملةً نيابةً عنك، فتركّز على عملك بدل بناء تكامل وصيانته.