نقاط نهاية API (Endpoints) لمنصة فاتورة

هذا الدليل موجّه للمطوّرين وفِرَق التكامل التقني الذين يبنون ربطًا فعليًا مع منصة فاتورة ضمن الفوترة الإلكترونية في السعودية. هدفه واحد ومحدّد: أن يضع بين يديك كتالوج نقاط النهاية (Endpoints) لمنصة فاتورة في مكان واحد. المسار النسبي لكل نقطة، وطريقة الطلب (HTTP Method)، والترويسات المطلوبة لكل واحدة منها، وشكل الاستجابة المتوقّعة.

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

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

المبادئ العامة قبل أي طلب

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

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

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

ثالثًا، البيئتان منفصلتان تمامًا. هناك بيئة اختبار (Sandbox) للامتثال والتطوير، وبيئة إنتاج (Production) للفواتير الحقيقية. لكل بيئة عنوان أساسي (Base URL) مختلف ومعرّف ختم مشفّر (CSID) مختلف. لا تخلط بينهما، فالامتثال يجري على معرّف الامتثال (Compliance CSID) بينما الإصدار الحقيقي يجري على معرّف الإنتاج (Production CSID).

رابعًا، الترويسات الأربع المشتركة. كل طلب يحمل في الأغلب Accept-Version لتثبيت إصدار الواجهة، وContent-Type: application/json، وAccept-Language لتحديد لغة رسائل الأخطاء، إضافة إلى ترويسة المصادقة الخاصة بكل نقطة. نفصّل المصادقة في القسم المخصّص لها أدناه.

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

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

العناوين الأساسية (Base URLs)

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

# بيئة الاختبار (Sandbox / Compliance)
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal

# بيئة الإنتاج (Production)
https://gw-fatoora.zatca.gov.sa/e-invoicing/core

لاحظ أن المسار النسبي نفسه (مثل /invoices/clearance/single) يُستدعى تحت العنوانين، فالفرق بين الاختبار والإنتاج هو العنوان الأساسي والمعرّف المستخدم، وليس المسار. وثّق العنوان الأساسي كمتغيّر بيئة واحد، وغيّره عند الانتقال للإنتاج.

ترميز الطلب والاستجابة

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

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

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

المعرّف الفريد (UUID) وعدّاد الفاتورة (ICV)

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

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

المصادقة (Authentication) على كل نقطة نهاية

كل نقاط النهاية التشغيلية في منصة فاتورة محمية بمصادقة من نوع Basic Authentication فوق HTTPS. لا توجد واجهة رمز وصول منفصلة (لا OAuth token endpoint بالمعنى التقليدي). بدلًا من ذلك، تبني ترويسة Authorization من معرّف الختم المشفّر (CSID) وسرّه (Secret) اللذين حصلت عليهما من واجهة الإصدار.

الصيغة العملية: تدمج المعرّف والسرّ بنقطتين بينهما، ثم تُرمّز الناتج بـ Base64، وتضعه بعد كلمة Basic. في بيئة الاختبار تستخدم معرّف الامتثال، وفي الإنتاج تستخدم معرّف الإنتاج. هذه الترويسة تتكرّر في طلبات Compliance و Clearance و Reporting، لذا نعرضها مرة واحدة هنا ونحيل إليها في كل قسم.

# بناء ترويسة المصادقة من CSID + Secret
# value = base64( binarySecurityToken : secret )
Authorization: Basic VFVsSlEyOXpaMEYzU.....=

# الترويسات المشتركة على معظم النقاط
Accept-Version: V2
Content-Type: application/json
Accept-Language: ar

تفصيل تدفّق المصادقة الكامل ومعالجة انتهاء صلاحية المعرّفات تجده في دليل تكامل API مع منصة فاتورة. هنا يكفيك أن تعرف أن غياب ترويسة Authorization الصحيحة يعيد لك الحالة 401 Unauthorized دائمًا قبل أي تحقّق آخر.

أولًا: واجهة الامتثال (Compliance)

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

طلب معرّف الامتثال

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

POST /compliance
Content-Type: application/json
Accept-Version: V2
OTP: 123456

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

# الاستجابة
HTTP/1.1 200 OK
{
  "requestID": 1234567890123,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "TUlJQ29...",   // هذا هو Compliance CSID
  "secret": "Xy9k...=="
}

فحص فواتير الامتثال

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

POST /compliance/invoices
Authorization: Basic <base64(complianceCSID:secret)>
Content-Type: application/json
Accept-Version: V2
Accept-Language: ar

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

# الاستجابة
HTTP/1.1 200 OK
{
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  },
  "reportingStatus": null,
  "clearanceStatus": "CLEARED"
}

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

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

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

ثانيًا: واجهة الإصدار والإنتاج (Onboarding / Production CSID)

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

POST /production/csids
Authorization: Basic <base64(complianceCSID:secret)>
Content-Type: application/json
Accept-Version: V2

{
  "compliance_request_id": "1234567890123"
}

# الاستجابة
HTTP/1.1 200 OK
{
  "requestID": 9876543210987,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "TUlJRDl6Q...",   // هذا هو Production CSID
  "secret": "Pq7m...=="
}

تستخدم نفس النقطة لاحقًا بطريقة PATCH لتجديد معرّف منتهي الصلاحية، وبطريقة GET للاستعلام عن حالة المعرّف. خزّن المعرّف وسرّه بشكل مشفّر، فهما مفتاح توقيع فواتيرك الحقيقية ولا يمكن استرجاعهما إن فُقدا، بل يلزم إصدار معرّف جديد.

ثالثًا: واجهة المصادقة (Clearance)

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

تُستدعى هذه النقطة على معرّف الإنتاج، ومع كل فاتورة ضريبية على حدة. لاحظ ترويسة Clearance-Status التي تطلب من المنصة تنفيذ المصادقة الكاملة.

POST /invoices/clearance/single
Authorization: Basic <base64(productionCSID:secret)>
Content-Type: application/json
Accept-Version: V2
Accept-Language: ar
Clearance-Status: 1

{
  "invoiceHash": "OWQ4ZjI3M...",
  "uuid": "f1e2d3c4-b5a6-47e8-9f01-22aabbccddee",
  "invoice": "<Base64-encoded-UBL-2.1-XML>"
}

# الاستجابة عند النجاح
HTTP/1.1 200 OK
{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "<Base64-encoded-cleared-XML>",   // النسخة المُصادَقة لتسليمها للمشتري
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  }
}

الحقل الجوهري في الاستجابة هو clearedInvoice: هذه هي النسخة المُصادَق عليها التي تحمل ختم الهيئة، وهي ما يجب أن تسلّمه للمشتري، وليست النسخة التي أرسلتها أنت. أما الحالة NOT_CLEARED مع errorMessages ممتلئة فتعني رفض الفاتورة، ويجب ألّا تسلّمها للمشتري حتى تصحّح الخطأ وتعيد المصادقة.

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

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

للتفصيل الكامل لمسار المصادقة وحالاته وأخطائه الشائعة، راجع دليل المقاصة (Clearance) في الفاتورة الإلكترونية.

رابعًا: واجهة الإبلاغ (Reporting)

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

تُستدعى هذه النقطة على معرّف الإنتاج، ومع كل فاتورة مبسّطة. تستخدم ترويسة Clearance-Status بقيمة صفر للدلالة على أن العملية إبلاغ وليست مصادقة.

POST /invoices/reporting/single
Authorization: Basic <base64(productionCSID:secret)>
Content-Type: application/json
Accept-Version: V2
Accept-Language: ar
Clearance-Status: 0

{
  "invoiceHash": "MmEzYjRjNW...",
  "uuid": "9a8b7c6d-5e4f-43a2-b1c0-99887766ffee",
  "invoice": "<Base64-encoded-UBL-2.1-XML>"
}

# الاستجابة عند النجاح
HTTP/1.1 200 OK
{
  "reportingStatus": "REPORTED",
  "validationResults": {
    "status": "PASS",
    "warningMessages": [],
    "errorMessages": []
  }
}

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

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

لكن لا تفرّط في المهلة. لو فشل الإبلاغ ضمن الـ 24 ساعة لخطأ عابر، فأنت بحاجة لآلية إعادة محاولة موثوقة تضمن وصول الفاتورة قبل انتهاء النافذة. أبسط تصميم آمن: طابور (Queue) للفواتير غير المبلَّغة بعد، مع إعادة محاولة دورية وتنبيه عند اقتراب أي فاتورة من حدّ المهلة دون إبلاغ ناجح.

للتفصيل الكامل لمسار الإبلاغ ونافذة الـ 24 ساعة ومعالجة التحذيرات، راجع دليل الإبلاغ (Reporting) في الفاتورة الإلكترونية.

الفرق الجوهري بين المصادقة والإبلاغ على مستوى الـ API

كثير من أخطاء التكامل تنبع من الخلط بين النقطتين. الفروق الثلاثة العملية التي يجب أن تبنيها في الكود واضحة.

الفرق الأول في النقطة نفسها: المصادقة على /invoices/clearance/single للفاتورة الضريبية B2B، والإبلاغ على /invoices/reporting/single للفاتورة المبسّطة B2C. لا تستدعِ نقطة الإبلاغ لفاتورة ضريبية، فالنوع يحدّد النقطة.

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

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

رموز الحالة (Status Codes) التي تتعامل معها

تعيد كل النقاط رموز حالة HTTP قياسية، ويهمّك أن تعالجها برمجيًا لا أن تتجاهلها. أبرز ما تقابله:

• 200 OK: نجح الطلب وتمّت المعالجة. افحص داخل الجسم حقل validationResults.status فقد يكون PASS أو يحمل تحذيرات.
• 202 Accepted: قُبل الطلب مع تحذيرات (Warnings) لا توقف العملية لكنها تستحق المراجعة والمعالجة.
• 303 See Other: رُفضت الفاتورة في مسار المصادقة. لا تسلّمها للمشتري، اقرأ errorMessages وصحّح ثم أعد الإرسال.
• 400 Bad Request: الطلب نفسه غير صالح بنيويًا، مثل JSON مكسور أو حقل ناقص أو XML غير متوافق مع UBL 2.1.
• 401 Unauthorized: ترويسة المصادقة غائبة أو خاطئة أو المعرّف منتهي الصلاحية.
• 500 Internal Server Error: خطأ من جهة المنصة. أعد المحاولة لاحقًا مع آلية إعادة محاولة متدرّجة (Exponential backoff).

القاعدة العملية: لا تكتفِ برمز HTTP وحده. الفاتورة قد تعيد 200 على مستوى النقل بينما تحمل errorMessages داخل الجسم. اقرأ دائمًا validationResults قبل أن تعتبر الفاتورة ناجحة.

إعادة المحاولة ومعالجة الأخطاء العابرة

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

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

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

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

قائمة الانتقال من الاختبار إلى الإنتاج

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

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

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

جدول مرجعي سريع لكل نقاط النهاية

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

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

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

• إدارة معرّف الختم المشفّر (CSID) تلقائيًا: يتولّى قيود تدفّق طلب معرّف الامتثال ثم معرّف الإنتاج لكل جهاز، ويخزّنهما بشكل آمن، ويجدّدهما عند الحاجة.
• توليد XML المتوافق مع UBL 2.1: يبني قيود مستند الفاتورة بالصيغة المطلوبة مع رمز الاستجابة السريعة (QR) والختم المشفّر وسلسلة التجزئة، فلا تصوغ XML يدويًا.
• مساري المصادقة والإبلاغ معًا: يوجّه قيود الفاتورة الضريبية إلى مسار المصادقة (Clearance) والفاتورة المبسّطة إلى مسار الإبلاغ (Reporting) آليًا حسب نوعها.
• التحقّق من صيغة المعرّفات قبل الإرسال: يتحقّق قيود من صيغة أرقام التعريف (مثل السجل التجاري والرقم الضريبي) عند الإدخال، فيلتقط أحد أكثر أسباب تحذيرات الهيئة شيوعًا قبل أن يصل الطلب إليها.
• فاتورة PDF/A-3 مع XML مضمّن: يصدر قيود ملف PDF واحدًا يضمّن داخله مستند الـ XML الضريبي وفق متطلب العرض في المرحلة الثانية، فتسلّم المشتري ملفًا واحدًا بدل اثنين.

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

أسئلة شائعة عن نقاط نهاية منصة فاتورة

هل كل نقاط النهاية تستخدم طريقة POST؟
نقاط الإصدار والتشغيل الأساسية (الامتثال والمصادقة والإبلاغ وطلب معرّف الإنتاج) تستخدم POST. نقطة معرّف الإنتاج تقبل أيضًا PATCH للتجديد وGET للاستعلام عن الحالة.

ما الفرق بين معرّف الامتثال ومعرّف الإنتاج؟
معرّف الامتثال (Compliance CSID) يعمل في بيئة الاختبار لفحص توافق نظامك فقط. معرّف الإنتاج (Production CSID) هو الذي يوقّع كل فاتورة حقيقية. لكل جهاز معرّف إنتاج خاص به.

أي ترويسة تفرّق بين المصادقة والإبلاغ؟
ترويسة Clearance-Status: قيمتها 1 في مسار المصادقة (Clearance)، و0 في مسار الإبلاغ (Reporting). إضافةً إلى اختلاف المسار نفسه بين النقطتين.

لماذا تُرسَل الفاتورة بصيغة Base64؟
لأن مستند الفاتورة بصيغة XML متوافقة مع UBL 2.1، ويُحمَل مُرمَّزًا بـ Base64 داخل حقل invoice في جسم JSON. هذا يفصل بين غلاف النقل (JSON) والمستند الضريبي الرسمي (XML).

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

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