واجهة فاتورة البرمجية لدى هيئة الزكاة والضريبة والجمارك لا تستخدم مفتاح API ثابتًا. المصادقة فيها على مرحلتين: رمز OTP يفتح الباب مرة واحدة، ثم شهادة وسرّ يحملهما كل طلب بعده في ترويسة Authorization. هذه الصفحة تشرح المسار كله بالمسارات والترويسات كما يرسلها نظام يعمل في الإنتاج، لمن يبني الربط بنفسه.
البيئات الثلاث
- بيئة المطورين (الاختبار):
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal - بيئة المحاكاة:
https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation - بيئة الإنتاج:
https://gw-fatoora.zatca.gov.sa/e-invoicing/core
ولكل بيئة شهاداتها: الشهادة الصادرة في بيئة لا تعمل في غيرها.
الترويسات في كل طلب
Accept-Version: V2
Accept: application/json
Content-Type: application/json
Accept-Language: enالخطوة 1: شهادة الامتثال برمز OTP
أول طلب هو الوحيد الذي لا يحمل ترويسة Basic. تولّد مفتاحًا خاصًا وطلب توقيع شهادة (CSR) على جهازك، ثم ترسل الطلب مرمَّزًا بـ Base64، ومعه رمز OTP من بوابة فاتورة في ترويسة مستقلة:
POST /compliance
OTP: 123456
{ "csr": "<CSR بترميز Base64>" }ويرجع الرد بثلاثة حقول: binarySecurityToken وهو الشهادة، وsecret وهو سرّها، وrequestID. احفظ الثلاثة: هذه شهادة الامتثال.
ترويسة Authorization: كيف تُبنى
من هنا فصاعدًا كل طلب يحمل ترويسة Basic، وقيمتها ترميز Base64 للنص المكوّن من binarySecurityToken كما جاء في الرد، ثم نقطتين، ثم secret:
Authorization: Basic base64( binarySecurityToken + ":" + secret )وbinarySecurityToken نفسه نص Base64. فإن فككت ترميزه لتحفظ الشهادة، فأعد ترميزه قبل بناء الترويسة. وأشيع أخطاء المصادقة ترميزه مرتين أو نسيان إعادة ترميزه.
الخطوة 2: فحوص الامتثال بشهادة الامتثال
توقّع الفواتير التجريبية التي تشترطها الهيئة وترسلها، كل واحدة في طلب، بشهادة الامتثال وسرّها:
POST /compliance/invoices
Authorization: Basic <شهادة الامتثال وسرّها>
{ "invoiceHash": "...", "uuid": "...", "invoice": "<الفاتورة الموقّعة بترميز Base64>" }الخطوة 3: شهادة الإنتاج
بعد اجتياز الفحوص تطلب شهادة الإنتاج، مصادقًا بشهادة الامتثال، ومرسلًا requestID الذي جاءك في الخطوة 1:
POST /production/csids
Authorization: Basic <شهادة الامتثال وسرّها>
{ "compliance_request_id": "<requestID>" }والرد بالحقول نفسها: binarySecurityToken وsecret جديدان. هذه شهادة الإنتاج، وهي وحدها التي تُرسل بها الفواتير الحقيقية. احفظها سرًّا، فمن يملكها يرسل فواتير باسم منشأتك.
الخطوة 4: إرسال الفواتير بشهادة الإنتاج
POST /invoices/reporting/single (الفاتورة المبسطة)
Clearance-Status: 0
POST /invoices/clearance/single (الفاتورة الضريبية)
Clearance-Status: 1
Authorization: Basic <شهادة الإنتاج وسرّها>
{ "invoiceHash": "...", "uuid": "...", "invoice": "<Base64>" }الفاتورة المبسطة تُبلَّغ، والضريبية تُجاز قبل أن تصل إلى المشتري. والفرق بينهما مشروح هنا.
التجديد قبل انتهاء الشهادة
لشهادة الإنتاج تاريخ انتهاء. تجديدها طلب إلى المسار نفسه بالفعل PATCH، برمز OTP جديد وطلب توقيع شهادة جديد، مصادقًا بشهادة الإنتاج الحالية:
PATCH /production/csids
OTP: 654321
Authorization: Basic <شهادة الإنتاج الحالية وسرّها>
{ "csr": "<CSR جديد بترميز Base64>" }وما يحدث إن انتهت قبل التجديد مشروح هنا.
إذا رجع الطلب 401
المعنى العام لـ 401 أن بيانات المصادقة غير مقبولة. راجع بالترتيب:
- هل الشهادة من البيئة نفسها التي ترسل إليها؟
- هل تستخدم شهادة الإنتاج لمسارات الفواتير، لا شهادة الامتثال؟
- هل
binarySecurityTokenفي الترويسة كما جاء في الرد، بلا ترميز ثانٍ ولا فكّ ترميز؟ - هل بين الشهادة والسرّ نقطتان، وهل رُمّز النص كاملًا بـ Base64 بعد الجمع؟
وأما رفض الفاتورة نفسها، لا الطلب، فرسالته تحمل كود القاعدة، وكل الأكواد مشروحة في دليل أكواد أخطاء ZATCA.
طريق أقصر
إن أردت الربط داخل نظامك دون كتابة هذا كله، فـمكتبة ZATCA Tools SDK لبايثون مفتوحة المصدر تتولى المفتاح وطلب الشهادة والفحوص وترويسة المصادقة والتجديد من داخل تطبيقك. وإن أردت ألا تحفظ شهادة أصلًا، فـواجهة ZATCA Tools المستضافة تستقبل الفاتورة بطلب JSON واحد وتتولى الباقي، وتوثيقها في ZATCA API. ابدأ من هنا — أسبوع مجانًا بدون دفع من يوم ربط منشأتك، ثم بأسعار منافسة جدًا: 49 ريالًا شهريًا لباقة النمو و149 لباقة الأعمال، في نظام سلس وسريع يُصدر الفاتورة ويرسلها للهيئة في ثوانٍ.