هذا الدليل يعطيك نماذج طلبات جاهزة للنسخ واللصق لتكامل الفاتورة الإلكترونية مع منصة فاتورة التابعة لهيئة الزكاة والضريبة والجمارك (ZATCA). الفكرة بسيطة: بدلًا من قراءة المواصفة حقلًا حقلًا، تأخذ هنا طلبًا كاملًا بكل ترويساته وجسمه، تستبدل القيم التجريبية بقيمك، وترسله. تجد نموذج طلب مقاصة (Clearance) كامل لفاتورة B2B، ونموذج طلب إبلاغ (Reporting) كامل لفاتورة B2C، ونسخة cURL لكل منهما تنسخها مباشرة إلى الطرفية.
النماذج هنا مكمّلة للمواصفة، لا بديلة عنها. إذا أردت شرح كل نقطة نهاية وحدودها، ارجع إلى نقاط نهاية API (Endpoints) لمنصة فاتورة. وإذا أردت التفصيل الكامل لكل واجهة، ارجع إلى واجهة المقاصة Clearance API وواجهة الإبلاغ Reporting API. دور هذا الدليل أن يضع بين يديك الطلب جاهزًا.
قبل أن تبدأ، تذكّر ثلاث حقائق تحكم كل النماذج التالية. الاختصار الصحيح لمعرّف الختم المشفّر هو CSID، وأي ترتيب آخر للأحرف خطأ شائع يربك فرق التكامل. القيمة في ترويسة Clearance-Status هي ما يفرّق طلب المقاصة عن طلب الإبلاغ. وجسم الطلب JSON دائمًا، حتى وإن حمل في داخله مستند XML مرمّزًا بـ Base64.
هذا الدليل موجّه للمطوّرين الذين يربطون أنظمتهم مباشرة بمنصة فاتورة. إن كنت صاحب منشأة تبحث عن التوافق دون كتابة كود، فالقسم الأخير يخصّك ويشرح كيف يتكفّل قيود بكل ما يلي نيابة عنك. أما إن كنت تبني التكامل بنفسك، فاقرأ النماذج بالترتيب، لأن كل قسم يبني على الذي قبله: نبدأ بالحقول الثابتة، ثم نموذج المقاصة كاملًا، ثم نموذج الإبلاغ، ثم تفاصيل بناء كل جزء على حدة.
الحقول الثابتة في كل طلب
كل نموذج في هذا الدليل يتكوّن من ثلاثة أجزاء: سطر الطلب (الطريقة والمسار)، الترويسات، ثم جسم JSON. الحقول الثلاثة داخل الجسم واحدة في الواجهتين، وهي العمود الفقري لأي طلب فاتورة:
- invoiceHash: بصمة الفاتورة، وهي قيمة SHA-256 محسوبة على نسخة XML بعد تقييسها (canonicalization)، ثم مرمّزة بـ Base64. أي تغيير بسيط في المحتوى يغيّر البصمة، لذا احسبها على النسخة النهائية الموقّعة بالضبط.
- uuid: المعرّف الفريد للفاتورة بصيغة UUID النسخة الرابعة. يجب أن يطابق المعرّف الموجود داخل الفاتورة نفسها حرفيًا. تكراره عبر فواتير مختلفة يسبّب الرفض.
- invoice: مستند الفاتورة الكامل بصيغة UBL 2.1 بعد ترميزه بـ Base64. هذا هو المحتوى الفعلي الذي تفحصه الهيئة وتضيف ختمها عليه في حالة المقاصة.
القيم في النماذج التالية مختصرة بثلاث نقاط (…) لأن قيم Base64 الحقيقية طويلة جدًا. استبدلها بقيمك الفعلية كاملة دون أي اقتطاع، لأن أي حرف ناقص يكسر البصمة ويردّ الطلب.
سطر الطلب: POST + مسار النقطة
الترويسات: Authorization وAccept-Version وContent-Type وClearance-Status
جسم JSON: invoiceHash وuuid وinvoice (Base64)
نموذج طلب المقاصة الكامل (Clearance B2B)
هذا الطلب يُستخدم للفاتورة الضريبية القياسية (B2B). تُرسل الفاتورة إلى الهيئة قبل تسليمها للمشتري، وتنتظر ختمها. لاحظ قيمة Clearance-Status هنا تساوي 1، وهذا ما يجعله طلب مقاصة لا إبلاغ. المسار النسبي هو POST /invoices/clearance/single، يُضاف بعد العنوان الأساسي للبيئة التي تعمل عليها.
انسخ الطلب التالي كاملًا، ثم استبدل قيمة الترويسة Authorization والقيم الثلاث في الجسم بقيمك:
هذه قراءة سطر بسطر لما يحمله الطلب:
- سطر الطلب: طريقة POST فوق HTTPS إلى المسار النسبي للمقاصة الفردية. لا تضمّن العنوان الأساسي داخل الكود، بل اجعله متغيّرًا في الإعدادات يتبدّل بين بيئة الاختبار والإنتاج.
- Authorization: مصادقة من نوع Basic. القيمة ليست اسم مستخدم وكلمة سر بشريين، بل معرّف الختم المشفّر (CSID) كاسم والسرّ المرتبط به ككلمة سر، مدموجين بنقطتين، مرمّزين بـ Base64، مسبوقين بكلمة Basic.
- Clearance-Status: قيمتها 1 في المقاصة. هذه القيمة تطلب من الهيئة المصادقة الكاملة على الفاتورة لا فحصها فقط.
- Content-Type: قيمتها application/json. الجسم JSON دائمًا حتى وإن حمل مستند XML مرمّزًا في داخله.
- Accept-Language: اللغة التي تريد بها رسائل الرد، مثل ar أو en.
القيمة في حقل invoice أعلاه هي مستند الفاتورة كاملًا بعد ترميزه بـ Base64. لبنائها بالترتيب الصحيح: ابنِ مستند UBL 2.1، أضف عدّاد الفاتورة وبصمة الفاتورة السابقة، وقّع المستند بالختم المشفّر، احسب بصمة SHA-256 على النسخة المقيّسة، ثم رمّز المستند النهائي بـ Base64. الناتج هو قيمة invoice، والبصمة هي قيمة invoiceHash.
نسخة cURL لطلب المقاصة
إذا أردت تجربة الطلب من الطرفية مباشرة قبل كتابته في الكود، انسخ أمر cURL التالي. استبدل قيمة الترويسة Authorization والقيم الثلاث في الجسم بقيمك، واضبط العنوان الأساسي على بيئتك:
ملاحظتان عمليتان على أمر cURL: علامة –data-raw تمنع cURL من تفسير أي رمز خاص داخل JSON، وهذا مهم لأن قيم Base64 قد تحوي علامات تساوي. واستخدام علامات التنصيص المفردة حول الجسم يحفظ بنيته كما هي دون أن تتدخّل الطرفية.
لا تبنِ التكامل من الصفر
يدير قيود المقاصة والإبلاغ والربط مع منصة فاتورة نيابة عنك. تُصدر فواتيرك الإلكترونية المتوافقة مع الهيئة دون أن تكتب طلب API واحدًا بنفسك.
| المعيار | Clearance (B2B) | Reporting (B2C) |
|---|---|---|
| النقطة | clearance/single | reporting/single |
| Clearance-Status | 1 | 0 |
| التوقيت | قبل التسليم | خلال 24 ساعة |
نموذج طلب الإبلاغ الكامل (Reporting B2C)
هذا الطلب يُستخدم للفاتورة الضريبية المبسّطة (B2C). الفاتورة المبسّطة تُوقَّع محليًا بمعرّف الختم المشفّر المرتبط بالجهاز وتُسلَّم للعميل فورًا، ثم تُبلَّغ الهيئة بها خلال نافذة أربع وعشرين ساعة. الفرق الجوهري عن المقاصة أن قيمة Clearance-Status هنا تساوي 0، والمسار النسبي هو POST /invoices/reporting/single.
انسخ الطلب التالي كاملًا، ثم استبدل القيم بقيمك:
القيم الثلاث في الجسم متطابقة في تركيبها مع طلب المقاصة. الاختلاف كله في الترويسة Clearance-Status وفي المسار. هذه قراءة الترويسات:
- Authorization: القيمة هي معرّف الختم المشفّر للإنتاج (Production CSID) وسرّه المرتبط، مدموجين ومرمّزين بـ Base64. هذا ما يثبت للهيئة هوية الجهاز الذي يبلّغ.
- Clearance-Status: قيمتها 0 في مسار الإبلاغ. هذه القيمة هي ما يفرّق طلب الإبلاغ عن طلب المقاصة الذي قيمته 1.
- Content-Type: قيمتها application/json كما في المقاصة.
تذكّر أن الحقول الثلاثة يجب أن تكون متّسقة فيما بينها. البصمة في invoiceHash يجب أن تطابق فعلًا تجزئة المستند المرمّز في invoice، والمعرّف في uuid يجب أن يطابق المعرّف المضمّن داخل المستند نفسه. أي عدم تطابق بين الغلاف والمستند يردّه الفحص.
نسخة cURL لطلب الإبلاغ
وهذه نسخة الطرفية لطلب الإبلاغ. لاحظ أن الفرق الوحيد عن أمر المقاصة هو المسار وقيمة Clearance-Status:
من أين تأتي قيم المعرّفات قبل أول طلب
النماذج أعلاه تفترض أنك تملك بالفعل معرّف ختم مشفّر صالحًا وسرّه. لكن هذه القيم لا تُولَّد من فراغ، بل تأتي بعد مسار تسجيل في منصة فاتورة يمرّ بمرحلتين متتاليتين. فهم هذا المسار يجنّبك حيرة «من أين آخذ قيمة Authorization» في أول محاولة.
تبدأ بطلب رمز تفعيل (OTP) من بوابة الهيئة، ثم تولّد طلب توقيع شهادة (CSR) يحوي بيانات منشأتك ورقمها الضريبي. ترسل طلب التوقيع مع رمز التفعيل إلى واجهة الامتثال، فتستلم في المقابل معرّف الختم للامتثال (Compliance CSID). هذا المعرّف يفتح لك واجهات بيئة الاختبار فقط، وتستخدمه لإرسال فواتير تجريبية تغطّي الحالات المطلوبة: فاتورة معيارية، فاتورة مبسّطة، إشعار دائن، وإشعار مدين.
عند اجتياز هذه الفحوص تطلب ترقية الشهادة، فتستلم معرّف الإنتاج (Production CSID). هذا المعرّف هو الذي يوقّع كل فاتورة حيّة لاحقًا، وهو القيمة التي تضعها في ترويسة Authorization في طلبات الإنتاج. القاعدة هنا صارمة: معرّف الامتثال للاختبار فقط، ومعرّف الإنتاج للفواتير الحقيقية، ولا يصحّ استخدام أحدهما في بيئة الآخر.
عمليًا، أنت لن تتعامل يدويًا مع طلبات توقيع الشهادات في كل فرع أو جهاز. الأنظمة المعتمدة تدير هذا المسار نيابة عنك لكل نقطة بيع أو فرع، فلا تخزّن أنت السرّ يدويًا ولا تعيد بناء الشهادات في كل مرة. اعرف المسار لتفهم من أين تأتي القيم، لكن اترك إدارته للنظام كي لا تتسرّب الأسرار أو تنتهي الشهادات دون انتباه.
تشريح حقل invoice المرمّز قبل أن ترسله
أكثر الحقول التباسًا في النماذج أعلاه هو حقل invoice، لأن قيمته الظاهرة مجرد سلسلة Base64 طويلة لا تكشف عن بنيتها. لكن خلف هذه السلسلة مستند XML مبنيّ وفق معيار UBL 2.1، وأي خلل في بنائه ينعكس فورًا على البصمة فيُرفض الطلب. لذا يستحق هذا الحقل وقفة قبل الإرسال.
المستند الذي ترمّزه يجب أن يحوي، إضافة إلى بيانات الفاتورة المعتادة، أربعة عناصر إلزامية ترتبط بالفوترة الإلكترونية: عدّاد الفاتورة المتسلسل، بصمة الفاتورة السابقة التي تربط الفواتير في سلسلة واحدة، التوقيع الرقمي بالختم المشفّر، ورمز الاستجابة السريع (QR). غياب أي من هذه العناصر أو ترتيبها الخاطئ يجعل الفحص يردّ الفاتورة حتى لو بدت البيانات التجارية سليمة.
الترتيب الذي تبني به هذه العناصر مهم ولا يقبل التبديل. تبني مستند UBL 2.1 أولًا متضمّنًا بصمة الفاتورة السابقة وعدّاد الفاتورة، ثم تضيف التوقيع الرقمي ورمز الاستجابة السريع، ثم تحسب تجزئة المستند بخوارزمية SHA-256 على نسخته المقيّسة، وأخيرًا ترمّز المستند كاملًا بـ Base64 وتضعه في حقل invoice. أي تقديم أو تأخير في هذه الخطوات يغيّر الناتج النهائي.
كلمة التقييس (canonicalization) هنا ليست تفصيلًا ثانويًا. الفاتورة الواحدة قد تُكتب بأكثر من شكل XML صحيح شكليًا لكنه مختلف في المسافات أو ترتيب السمات، وكل شكل ينتج بصمة SHA-256 مختلفة. لذا تُقيَّس الفاتورة وفق قواعد معتمدة تجعل لها شكلًا واحدًا قياسيًا قبل حساب البصمة. احسب البصمة دائمًا على النسخة المقيّسة الموقّعة، لا على أي مسودة وسيطة.
اتّساق الحقول الثلاثة داخل الجسم
الحقول الثلاثة في الجسم ليست مستقلة، بل مترابطة ترابطًا صارمًا، والفحص يتحقّق من هذا الترابط قبل أي شيء آخر. فهم العلاقة بينها يفسّر معظم رسائل الرفض في بداية التكامل.
أولًا، قيمة invoiceHash يجب أن تكون فعلًا تجزئة SHA-256 للمستند نفسه المرمّز في حقل invoice. لو حسبت البصمة على نسخة ثم رمّزت نسخة أخرى في حقل invoice، يكشف الفحص عدم التطابق ويردّ الطلب برسالة أن بصمة الفاتورة لا تطابق الفاتورة المرسلة. هذا أشهر خطأ على الإطلاق.
ثانيًا، قيمة uuid في الجسم يجب أن تطابق المعرّف الفريد المضمّن داخل مستند XML نفسه حرفيًا. المعرّف يظهر مرتين: مرة في غلاف الطلب JSON، ومرة داخل الفاتورة. أي اختلاف بين الموضعين، ولو في حرف واحد، يردّه الفحص. ولّد المعرّف مرة واحدة واكتبه في الموضعين من المصدر نفسه.
ثالثًا، المعرّف الفريد قيمة لا تتكرّر مطلقًا عبر الفواتير. تكراره عبر فاتورتين مختلفتين يجعل النظام يعتبر الثانية محاولة لإعادة إرسال الأولى، فيرفضها. ولّد UUID نسخة رابعة جديدًا لكل فاتورة، واحتفظ به مرتبطًا بالفاتورة في قاعدة بياناتك كي تستطيع إعادة الإرسال نفسه عند الحاجة.
كيف تبني العنوان الأساسي لكل بيئة
المسار النسبي ثابت لا يتغيّر بين البيئتين. ما يتغيّر هو العنوان الأساسي ومعرّف الختم المشفّر. لكل بيئة عنوان مختلف ومعرّف مختلف، لذا اجعل العنوان متغيّرًا في إعداداتك ولا تثبّته في الكود.
على سبيل المثال، تُبنى عناوين المقاصة والإبلاغ بدمج العنوان الأساسي مع المسار النسبي على هذا النحو:
القاعدة الحاسمة: الإبلاغ الحقيقي والمقاصة الحقيقية يجريان على معرّف الإنتاج في عنوان الإنتاج، بينما فحص توافق نظامك يجري على معرّف الامتثال في بيئة الاختبار. لا تخلط بين معرّف الامتثال (Compliance CSID) ومعرّف الإنتاج (Production CSID)، فكل منهما يعمل في بيئته فقط.
ملف UBL 2.1
العدّاد والتجزئة السابقة
التوقيع
SHA-256 على النسخة المقيّسة
ترميز Base64
كيف تبني ترويسة Authorization خطوة بخطوة
الخطأ الأكثر شيوعًا في أول طلب هو بناء ترويسة Authorization بشكل غير صحيح. الترويسة تتبع مخطط Basic القياسي، لكن المدخلات مختلفة عن المألوف. تأخذ معرّف الختم المشفّر وسرّه، تدمجهما بنقطتين، ترمّز الناتج بـ Base64، ثم تسبقه بكلمة Basic.
بالترتيب: لديك قيمتان، المعرّف والسرّ. تكتبهما على هذا الشكل قبل الترميز:
النقطتان بين المعرّف والسرّ جزء من القيمة قبل الترميز، لا تنسهما. ولا تستخدم معرّف الامتثال في بيئة الإنتاج، ولا معرّف الإنتاج في بيئة الاختبار، لأن كل معرّف يعمل في بيئته فقط.
الفروق الدقيقة بين الطلبين في سطر واحد
إذا نظرت إلى النموذجين جنبًا إلى جنب، تلاحظ أنهما متطابقان تقريبًا في كل شيء، ويختلفان في موضعين فقط. هذا التطابق مقصود في تصميم الواجهة، ويعني أن بناء طلب واحد سليم يعطيك تسعين بالمئة من الطلب الآخر مجانًا.
الفرق الأول في المسار: المقاصة تستدعي /invoices/clearance/single، والإبلاغ يستدعي /invoices/reporting/single. الفرق الثاني في الترويسة: المقاصة ترسل Clearance-Status بقيمة 1، والإبلاغ يرسلها بقيمة 0. ما عدا ذلك، الترويسات نفسها، وحقول الجسم الثلاثة نفسها، وطريقة بناء المصادقة نفسها.
هناك فرق ثالث غير ظاهر في الطلب لكنه يحكم متى ترسله. المقاصة تجري قبل تسليم الفاتورة للمشتري وبشكل لحظي متزامن، فلا تُسلَّم الفاتورة إلا بعد ختم الهيئة. أما الإبلاغ فيجري بعد تسليم الفاتورة للعميل، خلال نافذة أربع وعشرين ساعة، لأن الفاتورة المبسّطة سارية بمجرد توقيعها محليًا. هذا الفرق في التوقيت يحدّد بنية نظامك: هل تنتظر الرد قبل الطباعة، أم تطبع فورًا وتبلّغ لاحقًا.
عمليًا، اجعل دالة واحدة في الكود تبني الطلب، وتمرّر لها متغيّرين فقط: المسار وقيمة Clearance-Status. هذا يقلّل التكرار ويمنع الخطأ الذي ينشأ حين تنسخ دالة المقاصة لبناء الإبلاغ وتنسى تغيير القيمة. الفاتورة الضريبية القياسية تذهب للمقاصة، والفاتورة المبسّطة تذهب للإبلاغ، والدالة الواحدة تخدم المسارين.
الأخطاء الشائعة في أول طلب وكيف تتجنّبها
قبل أن ترسل أول طلب حقيقي، راجع هذه القائمة. معظم حالات الرفض في بداية أي تكامل تعود إلى أحد هذه الأسباب:
- عدم تطابق البصمة: إذا حسبت invoiceHash على نسخة غير النسخة المرمّزة في حقل invoice، يرفض الفحص الطلب برسالة أن البصمة لا تطابق الفاتورة. احسب البصمة على النسخة النهائية الموقّعة بالضبط.
- معرّف فريد مكرّر أو غير مطابق: إذا تكرّر uuid عبر فواتير مختلفة، أو اختلف عن المعرّف داخل XML، يُرفض الطلب. ولّد معرّفًا فريدًا لكل فاتورة واجعله يطابق المعرّف داخل المستند حرفيًا.
- قيمة Clearance-Status خاطئة: إرسال 0 لفاتورة B2B أو 1 لفاتورة B2C يوجّه الطلب للواجهة الخطأ. القيمة 1 للمقاصة و0 للإبلاغ، لا تخلط بينهما.
- خلط البيئات: استخدام معرّف الاختبار في عنوان الإنتاج أو العكس يفشل المصادقة. اضبط العنوان الأساسي والمعرّف معًا حسب البيئة.
- خطأ في كتابة CSID: الاختصار الصحيح هو CSID (معرّف الختم المشفّر). أي ترتيب آخر للأحرف في الكود أو التوثيق يربك فرق التكامل، فاضبطه من البداية.
عند إعادة إرسال الفاتورة نفسها بعد خطأ شبكي، أعد إرسال جسم الطلب نفسه حرفيًا. لا تولّد uuid جديدًا ولا تحسب بصمة جديدة، لأن ذلك يجعل الفاتورة تبدو مختلفة ويكسر تسلسل العدّاد والسلسلة.
ماذا تتوقّع في الرد بعد الإرسال
بعد أن ترسل أحد النماذج أعلاه، يعود الرد بصيغة JSON أيضًا. الرد يختلف بين المقاصة والإبلاغ، لكن منطقه العام واحد: حالة عامة للطلب، ثم تفاصيل تحذيرات أو أخطاء إن وُجدت. فهم شكل الرد المتوقّع يساعدك على بناء معالجة سليمة من أول طلب.
في المقاصة، يحمل الرد عند النجاح حقلًا باسم clearedInvoice، وهو الفاتورة المصادَق عليها بصيغة Base64. تفكّ ترميزها لتحصل على XML النهائي الموقّع من الهيئة. هذه هي النسخة الرسمية الوحيدة التي تُسلَّم للمشتري وتُحفظ، وأي نسخة محلية قبل المصادقة لا تُعتبر فاتورة معتمدة.
في الإبلاغ، يحمل الرد حقل حالة باسم reportingStatus، وقيمته REPORTED عند قبول الإبلاغ. لا يعيد الإبلاغ فاتورة موقّعة من الهيئة، لأن الفاتورة المبسّطة وُقّعت محليًا وسُلّمت للعميل قبل الإرسال أصلًا. هنا يكفيك تحديث حالة الفاتورة عندك إلى «مُبلَّغ عنها» وتخزين بصمتها لتكون مدخلًا للفاتورة التالية في السلسلة.
الردود قد تأتي أيضًا بحالة «مصادَق مع تحذيرات» في المقاصة، أو بأخطاء صريحة في الحالتين. التحذير لا يمنع اعتماد الفاتورة لكنه يستحق المراجعة، أما الخطأ فيوجب معالجة السبب وإعادة الإرسال. سنفرد لقراءة الرد وتفسير رموز حالاته دليلًا مستقلًا بنماذج جاهزة.
انضباط إعادة الإرسال وحفظ السجلات
التكامل المتزامن مع الهيئة يحتاج انضباطًا في ترتيب العمليات وفي حفظ النسخ، لا في بناء الطلب فحسب. عند أي خطأ شبكي أو انقطاع قبل وصول الرد، القاعدة هي إعادة إرسال جسم الطلب نفسه حرفيًا. لا تولّد uuid جديدًا ولا تحسب بصمة جديدة، لأن ذلك يجعل الفاتورة تبدو فاتورة مختلفة فيكسر تسلسل العدّاد والسلسلة المرتبطة بالبصمة السابقة.
هذا يعني عمليًا أنك تخزّن جسم الطلب المبنيّ، بمعرّفه وبصمته، قبل الإرسال لا بعده. فإذا فشل الاتصال، تعيد الإرسال من النسخة المخزّنة لا من نسخة جديدة. هذا السلوك، المعروف بمبدأ الثبات عند إعادة المحاولة (idempotency)، يحمي تسلسل فواتيرك من الانكسار الذي يصعب إصلاحه لاحقًا.
إلى جانب ذلك، سجّل لكل استدعاء معرّف الفاتورة، رمز الاستجابة، وحالة المقاصة أو الإبلاغ، مع رموز أي تحذيرات أو أخطاء. هذا السجل ضروري للتدقيق ولتتبّع أي رفض، ويختصر زمن حلّ المشكلات عند مراجعة فاتورة قديمة. احتفظ كذلك بالنسخة المصادَقة (clearedInvoice) في المقاصة للمدة النظامية لحفظ السجلات الضريبية.
كيف يساعدك قيود
كل ما سبق يفترض أنك ستبني هذا التكامل بنفسك: توليد UUID، حساب البصمة، بناء ترويسة المصادقة، إدارة معرّفين منفصلين لبيئتين، وتوجيه كل فاتورة لمسارها الصحيح. هذا حمل تقني كبير على فريق التطوير، وكل خطوة فيه عرضة للخطأ.
قيود يتولّى هذا كله نيابة عنك. النظام معتمد رسميًا من هيئة الزكاة والضريبة والجمارك ومتكامل مع منصة فاتورة في مرحلتها الثانية. يدير قيود معرّف الختم المشفّر لكل فرع أو جهاز، ويبني ترويسة المصادقة تلقائيًا، ويحسب البصمة ويولّد المعرّف الفريد لكل فاتورة، ويوجّه الفاتورة الضريبية القياسية لمسار المقاصة والفاتورة المبسّطة لمسار الإبلاغ دون تدخّل منك.
عمليًا، يعني هذا أنك تُصدر فاتورتك من واجهة قيود البسيطة، ويتكفّل النظام بكل ما في هذا الدليل خلف الكواليس: بناء مستند UBL 2.1، التوقيع، الترميز، الاستدعاء، وقراءة الرد. تحصل على فاتورة متوافقة مع الهيئة دون أن تكتب طلب API واحدًا.
يحفظ قيود كذلك سجلًا كاملًا لكل فاتورة: معرّفها، بصمتها، حالتها، والنسخة المصادَقة العائدة من الهيئة. هذا يعفيك من بناء طبقة السجلّات والتدقيق التي شرحناها أعلاه، ويضمن سلامة تسلسل الفواتير وبصماتها المتسلسلة دون تدخّل منك. ويتولّى النظام إدارة معرّف الختم المشفّر لكل فرع أو جهاز، فلا تخزّن الأسرار يدويًا ولا تقلق من انتهاء صلاحية الشهادات. النتيجة أن فريقك ينصرف لبناء منتجه بدلًا من ملاحقة تفاصيل التكامل مع منصة فاتورة.
روابط ذات صلة في مركز المطوّرين
هذا الدليل جزء من مركز مطوّري الفاتورة الإلكترونية. لتكمّل الصورة، ارجع إلى الأدلة التالية:
- نقاط نهاية API (Endpoints) لمنصة فاتورة: جرد كامل لكل نقاط النهاية وعناوينها وبيئاتها.
- واجهة المقاصة Clearance API: التفصيل الكامل لواجهة الفاتورة الضريبية القياسية B2B.
- واجهة الإبلاغ Reporting API: التفصيل الكامل لواجهة الفاتورة المبسّطة B2C.
- دليل الفاتورة الإلكترونية الشامل: لمحة عن الفوترة الإلكترونية ومتطلبات الهيئة من البداية.
بعد أن أرسلت الطلب وفهمت بنيته، الخطوة المنطقية التالية هي قراءة الرد العائد من الهيئة وتفسير حقوله ورموز حالاته. سنفرد لذلك دليلًا مستقلًا بنماذج استجابة جاهزة للنسخ.
