ربط الفاتورة الإلكترونية ببايثون: مكتبة مفتوحة المصدر تُصدر الفاتورة وترسلها للهيئة في ثلاث خطوات

مطوّر في شركة برمجيات، أو مستقل طلب منه عميل «اربط النظام بالمرحلة الثانية»: أمامك عادة طريقان. أن تبني الربط من الصفر — الشهادة، وتوقيع XML، وسلسلة البصمات، ورمز QR، والحديث مع واجهة الهيئة — أو أن ترسل فواتيرك إلى خدمة وسيطة تفعل ذلك عنك. ZATCA Tools SDK طريق ثالث: مكتبة بايثون مفتوحة المصدر برخصة MIT تعمل داخل تطبيقك، وتتصل بالهيئة مباشرة، بلا حساب لدينا وبلا خادم لنا في المنتصف. بياناتك تذهب من خادمك إلى الهيئة، ولا تمرّ بنا.

التثبيت وأول فاتورة في دقيقة

بايثون 3.10 فما فوق، وحزمة واحدة فيها الفواتير والاتصال بالهيئة وطباعة PDF:

pip install zatca-tools-sdk

ثم هذا المثال كما هو، ويعمل على بيئة الاختبار العامة لدى الهيئة دون أن تجهّز شيئًا:

from zatca_tools import Zatca

zatca = Zatca("sandbox")
zatca.onboard()  # the sandbox's test credentials, straight from ZATCA

invoice = zatca.create_invoice({
    "number": "INV-1001",
    "type": "simplified",
    "items": [
        {"name": "Product", "quantity": 2, "unit_price": 100},
    ],
})

result = zatca.submit(invoice)
if result.success:
    print("ZATCA says:", result.status)  # REPORTED
    invoice.save_xml("INV-1001.xml")
    invoice.save_pdf("INV-1001.pdf")
else:
    print(result.error.message)
    print(result.error.help_url)

والناتج سطر واحد: ZATCA says: REPORTED. ثلاث دوال فقط:

• onboard() يربط نظامك بالهيئة مرة واحدة. في بيئة الاختبار يأخذ شهادة الاختبار المشتركة في ثوانٍ، ولا يطلب منك شيئًا.
• create_invoice() يفحص الفاتورة ويحسب الضريبة والإجماليات ويوقّعها على جهازك. لا يُرسَل شيء بعد.
• submit() يرسلها إلى الهيئة ويعيد جوابها.

جواب الهيئة، مع رابط يشرح الخطأ

أصعب ما في الربط ليس الإرسال بل فهم الرفض. فالنتيجة تجيب عن ثلاثة أسئلة بثلاثة حقول: هل نجحت؟ result.success. ولماذا لا؟ result.error.message. وكيف أصلحها؟ result.error.help_url، وهو رابط إلى الشرح: دليل الكود في مرجع أكواد أخطاء ZATCA إن كان له دليل (بنص الهيئة الرسمي وشرح السبب والإصلاح)، وإلا فموضعه في المرجع. والتحذيرات التي تأتي مع القبول في result.warnings، ولكلٍّ منها رابطه.

وsuccess صحيحة فقط حين تقبل الهيئة الفاتورة فعلًا، مبلَّغة أو مُجازة. أما الحالات الأخرى فـstatus يسمّيها:

• REPORTED أو CLEARED: قبلتها الهيئة. احفظها واقرأ التحذيرات.
• NOT_REPORTED أو NOT_CLEARED: رفضتها الهيئة. أصلح ما تقوله الأخطاء ثم أصدر فاتورة مصحّحة جديدة، فالفاتورة المرفوضة أخذت مكانها في السلسلة.
• NOT_SENT: لا اتصال، والهيئة لم ترها. أرسل الفاتورة نفسها مرة أخرى.
• UNKNOWN: أُرسلت ولم يرجع جواب. أرسل الفاتورة نفسها مرة أخرى، لا فاتورة جديدة للبيعة نفسها.
• FAILED: رفضت الهيئة الطلب لا الفاتورة. أصلح السبب في error ثم أرسلها.

من بيئة الاختبار إلى فواتير حقيقية

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

1. بيانات منشأتك كما هي مسجّلة لدى الهيئة: الرقم الضريبي والاسم ورقم السجل التجاري والعنوان.
2. رمز OTP من بوابة فاتورة لكل نظام تربطه، يُستخدم مرة واحدة وينتهي بعد ستين دقيقة. ولا تستطيع أي مكتبة أو خدمة أن تولّده عنك: صاحب المنشأة وحده يفعل. والخطوات مشروحة هنا.
3. مكان آمن لسرّ (مدير أسرار أو تخزين مشفّر)، وقيمتان في قاعدة بياناتك.

ثم Zatca("production", seller=...) وonboard(otp="..."): تُنشئ المكتبة المفتاح الخاص على جهازك، وترسل طلب الشهادة، وتوقّع الفواتير التجريبية التي تشترطها الهيئة وترسلها، وتحصل على شهادة الإنتاج. والمفتاح الخاص يبقى في بيانات الاعتماد ولا يُرسَل إلى أي جهة. وبين الاختبار والإنتاج بيئة «المحاكاة» برقمك أنت وفواتير غير ضريبية، والكود واحد في الثلاث: لا يتغيّر إلا الوسيط الأول.

ما يبقى عليك أنت

المكتبة تعمل داخل تطبيقك، فبعض المسؤولية عندك، ونقولها صراحة:

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

الفاتورة المطبوعة

احفظ ملف XML دائمًا: هو الفاتورة الإلكترونية نفسها. ومعه ملف PDF من نوع PDF/A-3 وفي داخله ملف XML، فالنسخة التي يقرؤها الإنسان والنسخة التي يقرؤها النظام ملف واحد، بالعربية والإنجليزية، وبشعارك ولونك. ونسخة الفاتورة الضريبية المطبوعة تحمل النسخة المُجازة من الهيئة.

كيف نعرف أنها تعمل

ما يلي قسناه بتشغيل فعلي، لا وعود:

• تعمل من أولها إلى آخرها على بيئة الاختبار لدى الهيئة: فاتورة مبسطة تُبلَّغ، وفاتورة ضريبية تُجاز، وإشعارات دائنة ومدينة، وتجديد الشهادة.
• الحساب وملف XML هما نفسهما في منصة ZATCA Tools التي توقّع فواتير حقيقية في الإنتاج.
• كل ملفات PDF في تجاربنا اجتازت فحص veraPDF على أنها PDF/A-3b، ورمز QR المطبوع فيها يُقرأ فيعيد الرمز الموقّع نفسه.
• أكثر من 600 اختبار آلي تمرّ على لينكس وويندوز، لإصدارات بايثون من 3.10 إلى 3.13.

المكتبة أم المنصة؟

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

المكتبة مجانية. وإن اخترت المنصة المستضافة بدلها: ابدأ من هنا — أسبوع مجانًا بدون دفع من يوم ربط منشأتك، ثم بأسعار منافسة جدًا: 49 ريالًا شهريًا لباقة النمو و149 لباقة الأعمال، في نظام سلس وسريع يُصدر الفاتورة ويرسلها للهيئة في ثوانٍ.