فوترة زاتكا في n8n بلا كود: node من ZATCA Tools يفعل ما تفعله واجهة API

إن كان عملك يدور في n8n — طلبات من نموذج، وصفقات تُغلق في CRM، وجدول Google Sheets يسجّل فيه الفريق ما أُنجز — فالسؤال ليس هل تُصدر فاتورة المرحلة الثانية، بل من أين. للمطوّرين جواب جاهز: واجهة API للفوترة الإلكترونية. وهذا المقال لمن لا يكتب الطلب بنفسه: مسؤول العمليات، والمحاسب الذي يؤتمت عمله، والوكالة التي تبني سير العمل لعملائها. الـ node الذي نشرناه على n8n اسمه ZATCA Tools، ويفعل ما تفعله الواجهة عملية بعملية، بلا سطر كود.

أنشئ حسابك وابدأ في وضع التجربة بلا رقم ضريبي — وفي صفحة الـ node تسجيل كامل من التثبيت إلى أول فاتورة.

ما هو الـ node، ولماذا نسمّيه «API بلا كود»

في n8n كل خطوة من سير العمل node يأخذ بيانات الخطوة السابقة ويسلّم ناتجه للتالية. والـ node من ZATCA Tools حزمة مفتوحة المصدر اسمها n8n-nodes-zatca-tools، إصدارها 1.1.1، وهو موثّق من n8n: راجعته n8n فصار ضمن الـ nodes الموثّقة في لوحتها. والتوثيق هنا من n8n للحزمة لا أكثر؛ ZATCA Tools منصة مستقلة لا تتبع هيئة الزكاة والضريبة والجمارك.

والـ node لا يبني ملف XML ولا يوقّع ولا يتحدث مع الهيئة. يرسل بيانات الفاتورة إلى خدمتنا، وهي تتولى الجزء الثقيل: ملف UBL 2.1، والتوقيع XAdES بشهادة منشأتك، وسلسلة ICV/PIH، ورمز QR، ثم الإجازة أو التبليغ. ويعود إلى سير عملك الحكم ورمز QR وروابط XML وPDF. أي أن كل عملية في الواجهة لها مقابل في الـ node:

ويصلح الـ node كذلك أداةً لوكيل ذكاء اصطناعي (AI Agent) يُصدر الفاتورة من محادثة.

التثبيت: من لوحة n8n، بلا npm

1. ثبّت الـ node. على لوحة سير العمل اضغط + (أو N) وابحث عن ZATCA، ثم افتح More from the community واضغط Install. لا طرفية ولا npm. والتثبيت لمالك نسخة n8n أو مديرها، ثم يستخدمه كل الأعضاء. وإن لم يظهر في البحث فالأرجح أن المدير أخفى الـ nodes المجتمعية؛ اطلب منه إظهارها.
2. أنشئ حسابًا في ZATCA Tools واربط منشأتك بمنصة فاتورة، أو ابدأ في وضع التجربة.
3. انسخ المفتاح من الإعدادات ← API. يبدأ بـztk_live_ ويُعرض مرة واحدة.
4. أضف الاعتماد. أنشئ في n8n Credential من نوع ZATCA Tools API والصق المفتاح. يُختبر فورًا، فالمفتاح الخاطئ يفشل الآن لا عند أول فاتورة.

والاعتماد الواحد منشأة واحدة: شهادة واحدة وسلسلة فواتير واحدة.

External ID: الحقل الذي يفصل بين خطأ وخطأ دائم

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

أربعة سير عمل تبنيها في دقائق

1. صف في Google Sheets يصير فاتورة ضريبية

مؤسسة مقاولات أو صيانة يسجّل فريقها كل عمل منجز في جدول: اسم العميل، ورقمه الضريبي، وعنوانه الوطني المختصر، والمبلغ، ورقم أمر العمل.

Google Sheets Trigger (Row Added)
  → ZATCA Tools: Invoice → Create
  → ZATCA Tools: Invoice → Email
  → Google Sheets: Update Row

• في Invoice → Create اختر Standard (B2B) لأن العميل منشأة، فتُجاز الفاتورة قبل أن تصل إليه. ومن Additional Fields املأ Buyer Name وBuyer VAT Number وBuyer National Address من أعمدة الصف بتعبير مثل {{ $json.vat_number }}. والعنوان الوطني المختصر يكفي؛ الخدمة تستخرج منه بقية العنوان.
• السطر: «أعمال صيانة — أمر عمل 311»، والكمية 1، والسعر من عمود المبلغ. وفي External ID رقم أمر العمل.
• في Invoice → Email ضع في UUID القيمة {{ $json.uuid }} من الخطوة السابقة، وفي Send To بريد العميل. أو املأ Buyer Email في خطوة الإنشاء فيصله الملف حين تُقبل الفاتورة.
• أخيرًا اكتب في الصف رقم الفاتورة ومعرّفها وحالتها؛ ستحتاج المعرّف يوم الإشعار.

والمصدر قد يكون نموذج طلب أو صفقة في CRM أو إشعار دفع بدل الجدول. وإن كان المشتري فردًا فاختر Simplified (B2C)؛ الفرق في مقال الفاتورتين.

2. إلغاء أو إرجاع: إشعار دائن من الصف نفسه

Google Sheets Trigger (Row Updated)
  → IF (status = cancelled)
  → ZATCA Tools: Note → Create

• Kind: Credit Note (Reduce)، وInvoice UUID من العمود الذي حفظت فيه المعرّف.
• Reason إلزامي في كل إشعار؛ الإشعار بلا سبب ترفضه الهيئة (BR-KSA-17).
• للإلغاء الكامل فعّل Cancel the Whole Invoice: يُحسب الرصيد المفتوح في الخادم، فلا يُرد مبلغ رُدّ جزئيًا من قبل. وللإرجاع الجزئي اتركه مطفأً واكتب الأسطر المرتجعة بالصافي الذي دفعه المشتري.
• External ID مثل cancel-311، فلا يتكرر الإشعار إن عُدّل الصف ثانية.

ولإعادة عملية أُلغيت يُصدر إشعار مدين بالطريقة نفسها؛ الفرق بينهما في الإشعار الدائن والمدين.

3. المشغّل: تنبيه عند الرفض، وأرشيف لكل مستند

ZATCA Tools Trigger (Invoice Issued · Rejected)
  → ZATCA Tools: Invoice → Get
  → Slack: Send Message

اختر في المشغّل الحالة Rejected، ثم Invoice → Get ليجلب أسباب الهيئة بأكوادها، ثم رسالة إلى Slack أو WhatsApp بالرقم والسبب. المرفوض لا يُعدَّل: يحتفظ برقمه في السلسلة، وتُصدر فاتورة مصحّحة بقيمة External ID جديدة، لأن القديمة تعيد المرفوض نفسه. الأسباب الشائعة في فاتورتك مرفوضة؟، ولكل كود صفحة في مرجع أكواد الأخطاء.

وللأرشيف اختر Any Document Issued. الرابط links.view يُفتح بلا مفتاح، فهو ما تضعه في رسالة لشخص. أما links.pdf فيجلبه HTTP Request بمفتاحك في ترويسة Authorization، ثم يرفعه Google Drive إلى مجلد الشهر.

4. جدول شهري لعقود متكررة

Schedule Trigger (1st of every month)
  → Google Sheets: Get Rows (active contracts)
  → ZATCA Tools: Invoice → Create

لشركة صيانة أو تشغيل عقودها شهرية: Schedule يعمل أول كل شهر، ويقرأ العقود السارية، ويُصدر لكل صف فاتورة ضريبية بقسط الشهر. والسر في External ID: رقم العقد مع الشهر، مثل contract-42-2026-10. إن توقف التشغيل في منتصفه وأعدته، عادت الفواتير الصادرة نفسها ولم يصدر إلا ما بقي. وتفاصيل الأقساط في مقال عقد الصيانة الدوري.

المشغّل يعمل بالاستطلاع، فلا يحتاج رابطًا عامًا

أغلب المشغّلات تنتظر webhook: رابطًا عامًا ترسل إليه الخدمة الحدث، وهذا يتعثر حين تعمل n8n على جهاز في المكتب أو خلف جدار حماية. ZATCA Tools Trigger لا يحتاجه: يسأل خدمتنا على فترات تحددها عمّا صدر بعد آخر مستند رآه. يكفيه أن تصل n8n إلى الإنترنت لا العكس، ويسلّم المستندات بترتيب صدورها.

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

الضريبة لكل سطر، والأسعار الشاملة

منذ الإصدار 1.1.0 يحمل كل سطر حقل VAT Treatment: Standard Rate (15%) أو Zero-Rated (0%) أو Exempt أو Out of Scope. وإن تركته على Establishment Default أخذ معاملة منشأتك المحفوظة في إعداداتها، وهذا ما تحتاجه أغلب المنشآت.

والسطر الصفري أو المعفى يمكن أن يسمّي Exemption Reason من قائمة الهيئة (VATEX-SA-…). والسبب اختياري: إن تركته فارغًا أخذ السطر سبب بقية أسطر الفاتورة، ثم آخر سبب استخدمته منشأتك، وإلا صدرت بلا سبب فتقبلها الهيئة مع ملاحظة.

وفاتورة واحدة تجمع معاملات مختلفة. مورد مستلزمات طبية يفوتر عيادة مثلًا: أدوية مؤهلة بسطر صفري وسبب VATEX-SA-35، ومواد تنظيف بسطر 15%. والحكم على معاملة كل بند لمحاسبك؛ الـ node ينقل ما تختاره ولا يقرره عنك.

وإن كانت مبالغ مصدرك شاملة الضريبة ففعّل Prices Include VAT من Additional Fields وأرسلها كما هي، ولا تقسمها على 1.15 بنفسك؛ الضريبة تُستخرج من كل سطر بنسبته.

جرّب أولًا في وضع التجربة

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

مستندات بيئة الاختبار ليست فواتير نظامية. وحين تنفد يعود الـ node بخطأ trial_exhausted، فتربط منشأتك برقمها الضريبي ورمز OTP من بوابة فاتورة، ويبقى سير العمل كما هو. وAccount → Get يقول لك أي بيئة يستخدمها الحساب وكم بقي في باقتك.

ما لا يفعله الـ node

• ليس نظام محاسبة. لا قيود ولا مخزون؛ هو طبقة الامتثال: التوقيع والإجازة والتبليغ وحفظ الملف الموقّع. راجع هل تحتاج برنامج محاسبة؟
• الريال السعودي فقط. الفواتير بعملة أخرى لا يغطيها اليوم.
• لا فاتورة دفعة مقدّمة (النوع 386). إن كان عملك يقوم على دفعات تُخصم لاحقًا فاتفق مع محاسبك على معالجتها.
• اعتماد واحد لكل منشأة. والمنصة التي تُصدر باسم تجار كثيرين طريقها Partner API.
• يُصدر من المركز الرئيسي. لا يسمّي فرعًا ولا جهازًا؛ فواتير الفروع التي لها أجهزتها تمر عبر الواجهة البرمجية مباشرة.

ابدأ

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