نظرة عامة على واجهة API للفوترة الإلكترونية

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

نتعامل هنا مع الزاوية العملية: كيف تستدعي الواجهات، وما الترويسات (Headers) التي تحتاجها، وكيف يبدو الطلب والاستجابة. أما المرجع التقني الكامل لمواصفات الواجهات فتجده في صفحة تكامل API مع منصة فاتورة، وهي تركّز على زاوية المواصفات (Spec). هذه الصفحة مكمّلة لها وتركّز على الاستخدام اليومي والوصفات العملية.

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

ما هي واجهة API للفوترة الإلكترونية؟

الفوترة الإلكترونية في السعودية مرّت بمرحلتين. المرحلة الأولى (مرحلة الإصدار) بدأت إلزاميًا في 4 ديسمبر 2021، وتطلّبت إصدار الفواتير عبر نظام إلكتروني بصيغة منظّمة بدل الفواتير الورقية وملفات PDF المنسوخة من برامج التحرير. المرحلة الثانية (مرحلة الربط والتكامل) بدأت في 1 يناير 2023 على دفعات حسب حجم إيرادات المنشأة، وهي التي أدخلت الربط المباشر مع منصة فاتورة عبر واجهات API.

في المرحلة الثانية لم يعد كافيًا أن تصدر فاتورة إلكترونية محليًا. صار لزامًا على نظامك أن يتواصل مع منصة فاتورة لاعتماد فواتير الأعمال (B2B) لحظيًا، ولإبلاغ الهيئة بفواتير المستهلك (B2C) خلال 24 ساعة. كل فاتورة يجب أن تحمل ختمًا تشفيريًا (Cryptographic Stamp)، ومعرّفًا فريدًا (UUID)، وبصمة (Hash) للفاتورة السابقة لضمان سلامة السلسلة، ورمز QR. واجهة الـ API هي الجسر الذي ينفّذ هذا الحوار بين نظامك ومنصة فاتورة.

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

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

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

عنوان القاعدة (Base URL) والبيئات

تعمل منصة فاتورة على بيئتين منفصلتين تمامًا. بيئة المحاكاة (Sandbox / Simulation) للتطوير والاختبار دون أثر ضريبي حقيقي، وبيئة الإنتاج (Production) للفواتير الفعلية ذات القيمة القانونية. لكل بيئة عنوان قاعدة مستقل، وشهادة مستقلة، ومفاتيح مستقلة. القاعدة الذهبية: لا تخلط بين البيئتين أبدًا، وابدأ دائمًا من بيئة المحاكاة.

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

يأخذ عنوان القاعدة الشكل التالي، ويتبعه مسار الإصدار ثم مسار الواجهة المحدّدة:

https://gw-fatoora.zatca.gov.sa/e-invoicing/{environment}/{resource}

# environment = simulation | core (production)
# resource    = compliance
#             | production/csids
#             | invoices/clearance/single
#             | invoices/reporting/single

القيمة الفعلية للعناوين قد تتغيّر بين الإصدارات والبيئات، لذلك اقرأ دائمًا التوثيق الرسمي للهيئة قبل تثبيت أي عنوان في الكود. لا تضع عناوين الإنتاج في كودك مباشرة، بل اجعلها متغيّرات بيئة (Environment Variables) قابلة للتبديل بين المحاكاة والإنتاج بسطر واحد. هذا النمط يحميك من أخطاء النشر، ويسهّل اختبار التكامل في خطوط المعالجة الآلية (CI/CD) دون لمس مفاتيح الإنتاج.

لمحة عن بيئة المحاكاة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نموذج المصادقة (Authentication) بإيجاز

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

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

POST /e-invoicing/simulation/invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic {base64(binarySecurityToken:secret)}
Content-Type: application/json
Accept: application/json
Accept-Language: en
Accept-Version: V2
Clearance-Status: 1

قيمة binarySecurityToken مشتقّة من شهادة CSID، والقيمة secret هي المفتاح السرّي المصاحب لها. ترويسة Clearance-Status بقيمة 1 تعني أنك تطلب المقاصة الفعلية لا مجرّد التحقّق. أما ترويسة Accept-Language فتحدّد لغة رسائل التحقّق في الاستجابة.

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

إصدارات الواجهة (API Versioning) عبر Accept-Version

تدير منصة فاتورة إصدارات واجهاتها عبر ترويسة Accept-Version. تحدّد بها أي إصدار من الواجهة تخاطب، وهذا يحميك من أن يكسر تحديث في الواجهة تكاملك القائم. القيمة الشائعة في المرحلة الثانية هي V2.

Accept-Version: V2

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

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

بنية الطلب والاستجابة (Request / Response)

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

هذا مثال مبسّط لجسم طلب اعتماد فاتورة عبر واجهة المقاصة:

{
  "invoiceHash": "NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZj...",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}

الحقل invoiceHash هو بصمة الفاتورة، وuuid معرّفها الفريد، وinvoice ملف XML كاملًا مرمّزًا بـ Base64. عند نجاح الاعتماد، تأتي الاستجابة بحالة المقاصة والفاتورة المعتمدة موقّعة من الهيئة، مع أي تحذيرات إن وُجدت:

{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...",
  "validationResults": {
    "infoMessages": [
      { "type": "INFO", "code": "XSD_ZATCA_VALID",
        "message": "Complied with UBL 2.1 standards in line with specifications" }
    ],
    "warningMessages": [],
    "errorMessages": [],
    "status": "PASS"
  }
}

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

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

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

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

القاعدة العملية: لا تكتفِ بقراءة رمز الحالة، بل اقرأ كائن validationResults دائمًا. فالرمز 202 يعني أن الفاتورة اعتُمدت لكن ثمة تحذيرات (warningMessages) قد تتحوّل إلى أخطاء حاجبة في تحديث لاحق من الهيئة. عالج التحذيرات في بيئة المحاكاة قبل أن تنتقل إلى الإنتاج، فالتحذير اليوم قد يصبح رفضًا غدًا.

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

المقاصة مقابل الإبلاغ: متى تستخدم أيًّا منهما؟

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

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

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

رحلة المطوّر: من المحاكاة إلى الإنتاج

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

1. هيّئ بيئة المحاكاة واحصل على بيانات الاعتماد التجريبية.
2. أنتج عيّنات الفواتير بصيغة XML المتوافقة مع المرحلة الثانية.
3. استدعِ واجهة الامتثال للتحقّق من فواتيرك واحصل على شهادة الامتثال.
4. اطلب شهادة الإنتاج (Production CSID) من واجهة الإصدار.
5. اعتمد فواتير الأعمال (B2B) عبر واجهة المقاصة لحظيًا.
6. أبلِغ بفواتير المستهلك (B2C) عبر واجهة الإبلاغ خلال 24 ساعة.
7. راقب رموز الحالة ونتائج التحقّق، وعالج أي تحذيرات أولًا بأول.

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

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

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

خريطة رحلة المطوّر خطوة بخطوة

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

أين يقع قيود في طبقة الـ API؟

إذا كنت تبني تكاملك بنفسك، فهذه الواجهات الأربع هي عالمك اليومي. لكن إن كنت صاحب منشأة لا تريد بناء كل هذا، فإن نظامًا محاسبيًا مثل قيود يتولّى الطبقة كاملة نيابة عنك. يوقّع قيود كل فاتورة بالختم التشفيري، ويسندها بمعرّف UUID، ويحفظ سلسلة البصمات (Hash chain)، ويجري المقاصة اللحظية لفواتير الأعمال، ويبلّغ بفواتير المستهلك خلال 24 ساعة، ويدير شهادة CSID تلقائيًا.

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

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

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