Skip to Content

Saudi Arabia - POS Direct ZATCA Integration | تكامل نقاط البيع مع الزكاة والدخل

by
Odoo

$ 90.50

v 18.0 Third Party
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Point of Sale (point_of_sale)
• Discuss (mail)
• Inventory (stock)
• Invoicing (account)
Community Apps Dependencies
Lines of code 5448
Technical Name am_l10n_sa_edi_pos_direct
LicenseLGPL-3
Websitehttps://idealitsetup.com
Versions 17.0 18.0 19.0
You bought this module and need support? Click here!
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Point of Sale (point_of_sale)
• Discuss (mail)
• Inventory (stock)
• Invoicing (account)
Community Apps Dependencies
Lines of code 5448
Technical Name am_l10n_sa_edi_pos_direct
LicenseLGPL-3
Websitehttps://idealitsetup.com
Versions 17.0 18.0 19.0
ZATCA POS Direct Integration

تكامل نقاط البيع المباشر مع هيئة الزكاة والدخل

Saudi Arabia POS Direct ZATCA Integration

المرحلة الثانية - فاتورة | Phase 2 - FATOORA

Odoo 18 License ZATCA Phase 2 90 $

نظرة عامة | Overview

هذا المودول يوفر تكامل مباشر ومحسّن مع نظام فاتورة (ZATCA) لأنظمة نقاط البيع في المملكة العربية السعودية. بدلاً من إنشاء فاتورة محاسبية لكل طلب ثم إرسالها، يقوم هذا المودول بتوليد XML مباشرة من طلب نقطة البيع وإرساله لهيئة الزكاة.

This module provides a direct and optimized integration with the ZATCA (FATOORA) system for Point of Sale in Saudi Arabia. Instead of creating an accounting invoice for each order and then submitting it, this module generates XML directly from the POS order and submits it to ZATCA.

تحسين الأداء بنسبة 70%! - لأن المودول لا ينشئ فواتير محاسبية، بل يرسل مباشرة من طلب نقطة البيع.
70% Performance Improvement! - Because the module doesn't create accounting invoices, it sends directly from POS orders.

دعم B2C و B2B | B2C & B2B Support

الفواتير المبسطة (B2C) | Simplified Invoices

Reporting API
  • للعملاء الأفراد - بدون رقم ضريبي
  • يتم الإرسال عبر Reporting API
  • Clearance-Status: 0
  • العميل يكون من نوع person أو بدون عميل
  • لا يتطلب بيانات عنوان العميل

الفواتير الضريبية (B2B) | Standard/Tax Invoices

Clearance API
  • للشركات - مع رقم ضريبي
  • يتم الإرسال عبر Clearance API
  • Clearance-Status: 1
  • العميل يكون من نوع company
  • يتطلب: VAT، العنوان، المدينة، الرمز البريدي
كيف يتم التمييز؟ المودول يتحقق تلقائياً من نوع العميل (partner.company_type):
- إذا كان company = فاتورة ضريبية B2B (Clearance API)
- إذا كان person أو بدون عميل = فاتورة مبسطة B2C (Reporting API)

المميزات الرئيسية بالتفصيل | Detailed Features

1. رمز QR المرحلة الثانية (9 حقول) | Phase 2 QR Code

يتم توليد رمز QR متوافق مع المرحلة الثانية يحتوي على 9 حقول مشفرة بـ TLV:

Tagالحقل | Fieldالوصف | Description
1Seller Nameاسم البائع (الشركة)
2VAT Numberالرقم الضريبي
3Timestampتاريخ ووقت الفاتورة (ISO 8601)
4Total with VATالمبلغ الإجمالي شامل الضريبة
5VAT Amountمبلغ الضريبة
6Invoice Hashهاش الفاتورة (SHA256)
7ECDSA Signatureالتوقيع الرقمي
8Public Keyالمفتاح العام
9Certificate Signatureتوقيع الشهادة

2. حفظ ملف XML الموقّع | Signed XML Storage

يتم حفظ ملف XML الموقّع لكل طلب في حقل l10n_sa_zatca_xml_file:

  • يمكن تحميل الملف من شاشة الطلب
  • يحتوي على التوقيع الرقمي الكامل
  • يمكن استخدامه للتدقيق والمراجعة
  • اسم الملف: Order [reference].xml

3. سلسلة الفواتير PIH (BR-KSA-61) | Invoice Hash Chain

Previous Invoice Hash - كل فاتورة تحتوي على هاش الفاتورة السابقة لضمان سلسلة غير قابلة للتعديل:

<cac:AdditionalDocumentReference> <cbc:ID>PIH</cbc:ID> <cac:Attachment> <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain"> [Previous Invoice Hash Base64] </cbc:EmbeddedDocumentBinaryObject> </cac:Attachment> </cac:AdditionalDocumentReference>
أول فاتورة: تستخدم الهاش الافتراضي من ZATCA
NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==

4. عداد الفواتير ICV (BR-KSA-33) | Invoice Counter Value

عداد تسلسلي بدون فجوات باستخدام ir.sequence:

  • No-gap: لا توجد أرقام مفقودة
  • Per Company: عداد منفصل لكل شركة
  • Sequence Code: zatca.icv.[company_id]
  • يبدأ من 1 ويزيد تلقائياً
<cbc:ID>ICV</cbc:ID> <cbc:UUID>[Sequential Counter]</cbc:UUID>

5. دعم المرتجعات | Refund Support

دعم كامل لإشعارات الدائن مع أسباب الإرجاع:

الكود | Codeالوصف | Description
DESC_ERRORعيب في الوصف | Description Error
QTY_ERRORخطأ في الكمية | Quantity Error
PRICE_ERRORخطأ في السعر | Price Error
PRODUCT_DEFECTعطل في المنتج | Product Defect
CUSTOMER_REQUESTإلغاء بطلب العميل | Customer Cancellation
OTHER_REASONأسباب أخرى | Other Reasons

المرتجعات تتضمن:

  • InvoiceTypeCode = 381 (Credit Note)
  • مرجع للفاتورة الأصلية (BillingReference)
  • سبب الإرجاع في PaymentMeans/InstructionNote

6. الإرسال غير المتزامن | Asynchronous Submission

يتم الإرسال لهيئة الزكاة عبر Cron Jobs لضمان عدم تأخير عمليات نقطة البيع:

Cron Jobالتردد | Frequencyالوظيفة | Function
ZATCA POS Sync كل دقيقة إرسال الطلبات الجديدة
ZATCA Retry Failed كل 15 دقيقة إعادة محاولة الطلبات الفاشلة

مسار حالة الإرسال | Status Workflow

Legacy
→
Pending
→
Generated
→
Queued
→
Submitted
Error
→ (Retry via Cron or Manual) →
Submitted
الحالة | Statusالوصف | Description
Legacy طلبات قبل تثبيت المودول - لن يتم معالجتها
Pending في انتظار توليد البيانات المحلية
Generated تم توليد UUID و QR محلياً
Queued في طابور الإرسال لـ ZATCA
Submitted تم الإرسال بنجاح لـ ZATCA
Error فشل الإرسال - سيتم إعادة المحاولة

التوافق التقني مع ZATCA | Technical ZATCA Compliance

Business Ruleالوصف | Descriptionالتطبيق | Implementation
BR-KSA-33 Invoice Counter Value (ICV) ir.sequence مع no_gap
BR-KSA-61 Previous Invoice Hash (PIH) l10n_sa_invoice_hash field
BR-KSA-17 Refund Reason Code l10n_sa_zatca_refund_reason
BR-KSA-25 QR Code 9 Fields TLV encoding with signature
KSA-2 Invoice Type Code 388 (Invoice) / 381 (Credit Note)
KSA-10 Payment Means 10 (Cash) / 30 (Credit) / 48 (Card)
CustomizationID:
urn:oasis:names:specification:ubl:schema:xsd:Invoice-2

ProfileID:
reporting:1.0

مرجع الحقول المضافة | Added Fields Reference

حقول نموذج pos.order

الحقل | Fieldالنوع | Typeالوصف | Description
l10n_sa_zatca_status Selection حالة الإرسال لـ ZATCA
l10n_sa_zatca_submission_time Datetime وقت الإرسال الناجح
l10n_sa_zatca_error_message Text رسالة الخطأ في حالة الفشل
l10n_sa_zatca_refund_reason Selection سبب الإرجاع للمرتجعات
l10n_sa_qr_code_image Html صورة QR Code للعرض
l10n_sa_zatca_xml_file Binary ملف XML الموقّع
l10n_sa_zatca_xml_filename Char اسم ملف XML
l10n_sa_invoice_hash Char هاش الفاتورة (PIH)

حقول نموذج pos.config

الحقل | Fieldالنوع | Typeالوصف | Description
l10n_sa_edi_pos_direct_mode_enabled Boolean تفعيل وضع ZATCA المباشر

خطوات التثبيت | Installation Steps

1. المتطلبات الأساسية | Prerequisites

  • Odoo 18 Enterprise
  • التوطين السعودي (l10n_sa, l10n_sa_edi, l10n_sa_pos)
  • مودول queue_job من OCA
  • إكمال عملية Onboarding مع ZATCA

2. تثبيت المودول | Install Module

  1. ضع المودول في مجلد addons
  2. حدّث قائمة التطبيقات
  3. ابحث عن "ZATCA POS Direct" وثبّته

3. تكوين نقطة البيع | Configure POS

  1. اذهب إلى: نقطة البيع ← إعدادات ← نقاط البيع
  2. اختر نقطة البيع المطلوبة
  3. فعّل "ZATCA Direct Mode"
  4. اختر Journal الفواتير (يجب أن يكون مكوّن مع ZATCA)
تنبيه هام: تأكد من إكمال عملية Onboarding مع ZATCA والحصول على شهادة CSID قبل تفعيل المودول.

كيف يعمل المودول؟ | How It Works

الخطوة 1: إتمام الطلب في نقطة البيع

عند الضغط على "تأكيد" في نقطة البيع:

  • يتم توليد UUID فريد
  • يتم توليد رمز QR (5 حقول أساسية)
  • الحالة = generated

الخطوة 2: حفظ الطلب

عند حفظ الطلب في السيرفر:

  • يتم التحقق من اكتمال البيانات
  • الحالة = queued

الخطوة 3: معالجة Cron Job

كل دقيقة يتم:

  • جلب الطلبات بحالة queued
  • توليد XML من قالب UBL 2.1
  • التوقيع الرقمي باستخدام شهادة CSID
  • حساب Invoice Hash

الخطوة 4: الإرسال لـ ZATCA

حسب نوع الفاتورة:

  • B2C: Reporting API → /invoices/reporting/single
  • B2B: Clearance API → /invoices/clearance/single

الخطوة 5: تحديث النتيجة

  • نجاح: الحالة = submitted، حفظ XML والـ Hash
  • فشل: الحالة = error، حفظ رسالة الخطأ

الإجراءات المتاحة | Available Actions

الإجراء | Actionالموقع | Locationالوصف | Description
Retry ZATCA شاشة الطلب إعادة محاولة الإرسال للطلبات الفاشلة
Sync All Pending ZATCA قائمة الطلبات (Server Action) إرسال جميع الطلبات المعلقة دفعة واحدة

استكشاف الأخطاء | Troubleshooting

خطأ: "No PCSID data found"

السبب: لم يتم إكمال عملية Onboarding مع ZATCA

الحل: اذهب إلى Journal ← ZATCA وأكمل عملية التسجيل

خطأ: "Invoice hash mismatch"

السبب: تم تعديل XML بعد التوقيع

الحل: تأكد من عدم وجود تعديلات على XML بين التوقيع والإرسال

خطأ: "Clearance rejected"

السبب: بيانات العميل ناقصة (B2B)

الحل: تأكد من وجود VAT وعنوان كامل للعميل

المتطلبات التقنية | Technical Requirements

المتطلب | Requirementالقيمة | Value
الاسم التقني | Technical Name l10n_sa_edi_pos_direct
الإصدار | Version 18.0.1.4.0
المتطلبات | Dependencies point_of_sale, l10n_sa_pos, l10n_sa_edi, queue_job
الترخيص | License LGPL-3
إصدار Odoo | Odoo Version 18.0 (Enterprise)
الدولة | Country Saudi Arabia (SA)

لقطات الشاشة | Screenshots

شاشة إعدادات نقطة البيع | POS Configuration

POS Configuration

شاشة الطلب مع معلومات ZATCA | Order with ZATCA Information

Order ZATCA Info

قائمة الطلبات مع حالة ZATCA | Orders List with ZATCA Status

Orders List

التواصل والدعم | Contact & Support

90 $

للحصول على الدعم الفني والتخصيصات

المطور | Developer: Ahmed Magdy
البريد الإلكتروني | Email: qarsan4@gmail.com
الموقع | Website: idealitsetup.com
واتساب | WhatsApp: +966 509818413

ملاحظة: هذا المودول يتطلب Odoo Enterprise مع التوطين السعودي (l10n_sa_edi)
Note: This module requires Odoo Enterprise with Saudi localization (l10n_sa_edi)

Last updated: January 2025 | Version 18.0.1.4.0

Please log in to comment on this module

  • The author can leave a single reply to each comment.
  • This section is meant to ask simple questions or leave a rating. Every report of a problem experienced while using the module should be addressed to the author directly (refer to the following point).
  • If you want to start a discussion with the author or have a question related to your purchase, please use the support page.