Skip to Content

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

by
Odoo

$ 91.24

In-App Purchases
v 19.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)
Lines of code 1947
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)
Lines of code 1947
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 19 License ZATCA Phase 2 Free

جديد في الإصدار 19.0 | What's New in v19.0

التحديثات الجديدة | New Updates

  • NEW اسم بديل للمنتج على الريسيت - حقل جديد لكتابة اسم المنتج بلغة ثانية (مثلاً عربي) يظهر تحت اسم المنتج في الإيصال
  • NEW تخطيط ريسيت محسّن - بيانات الشركة كاملة تحت اللوجو مباشرة (اسم، فرع، سجل تجاري، ضريبي، عنوان، هاتف)
  • NEW رقم السجل التجاري - يظهر تلقائياً في الإيصال من بيانات الشركة
  • NEW بيانات العميل محسّنة - اسم العميل ورقمه الضريبي يظهران بشكل واضح في الإيصال
  • NEW زر إعادة المحاولة للفواتير الفاشلة - زر مخصص لإعادة رفع الفواتير اللي فشلت في الإرسال
  • NEW إخفاء "Powered by Odoo" - إيصال نظيف بدون علامات أودو التجارية
  • NEW إخفاء قسم البورتال - إخفاء "Need an invoice?" من الإيصال
  • IMPROVED توافق كامل مع أودو 19 - تحديث كامل لجميع الـ APIs والـ imports
  • IMPROVED تكامل مع l10n_sa_edi_pos - يعتمد على المديول الرسمي الجديد في أودو 19
  • IMPROVED حجم QR قابل للتعديل - من 130px إلى 350px مع عرض محسّن

نظرة عامة | 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%! - لأن المودول لا ينشئ فواتير محاسبية للطلبات المبسطة (B2C)، بل يرسل مباشرة من طلب نقطة البيع.
70% Performance Improvement! - Because the module doesn't create accounting invoices for simplified (B2C) orders, 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، العنوان، المدينة، الرمز البريدي
  • يستخدم الفاتورة المحاسبية القياسية

مميزات الإيصال | Receipt Features

بيانات الشركة الكاملة

NEW in v19
  • اسم الشركة (بولد)
  • اسم الفرع (نقطة البيع)
  • رقم السجل التجاري (CR)
  • الرقم الضريبي (VAT)
  • العنوان الكامل
  • رقم الهاتف

اسم بديل للمنتجات

NEW in v19
  • حقل "Alternative Name" على كل منتج
  • يظهر تحت اسم المنتج في الإيصال
  • مثالي للغة العربية كلغة ثانية
  • يظهر في POS وفي الطباعة

QR Code المرحلة الثانية

  • 9 حقول مشفرة بـ TLV
  • حجم قابل للتعديل (130-350px)
  • متوافق مع ZATCA Phase 2
  • يشمل التوقيع الرقمي والمفتاح العام

إيصال نظيف ومخصص

NEW in v19
  • إخفاء "Powered by Odoo"
  • إخفاء قسم "Need an invoice?"
  • بيانات العميل مع labels واضحة
  • فوتر ZATCA Phase 2

المميزات التقنية | Technical Features

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

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

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

  • يمكن تحميل الملف من شاشة الطلب
  • يحتوي على التوقيع الرقمي الكامل مع شهادة CSID
  • يمكن استخدامه للتدقيق والمراجعة

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

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

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

عداد تسلسلي بدون فجوات (No-gap) لكل شركة

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

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

Cron Jobالتردد | Frequencyالوظيفة | Function
ZATCA Process Pendingكل دقيقةإرسال الطلبات الجديدة
ZATCA Retry Failedكل 30 دقيقةإعادة محاولة الطلبات الفاشلة (آخر 7 أيام)

NEW زر يدوي لإعادة المحاولة: "Retry Failed ZATCA Orders" و "Sync All Pending ZATCA Orders"

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

Legacy
→
Pending
→
Generated
→
Queued
→
Submitted
Error
→ (Retry via Cron or Manual Button) →
Submitted

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

حقول pos.order

الحقل | Fieldالنوع | Typeالوصف | Description
l10n_sa_zatca_statusSelectionحالة الإرسال لـ ZATCA
l10n_sa_zatca_submission_timeDatetimeوقت الإرسال الناجح
l10n_sa_zatca_error_messageTextرسالة الخطأ في حالة الفشل
l10n_sa_zatca_refund_reasonSelectionسبب الإرجاع للمرتجعات
l10n_sa_qr_code_imageHtmlصورة QR Code للعرض
l10n_sa_zatca_xml_fileBinaryملف XML الموقّع
l10n_sa_invoice_hashCharهاش الفاتورة (PIH)

حقول pos.config

الحقل | Fieldالنوع | Typeالوصف | Description
l10n_sa_edi_pos_direct_mode_enabledBooleanتفعيل وضع ZATCA المباشر
l10n_sa_qr_code_sizeSelectionحجم QR Code (130-350px)

حقول product.template NEW

الحقل | Fieldالنوع | Typeالوصف | Description
l10n_sa_alt_nameCharالاسم البديل للمنتج (يظهر في الإيصال)

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

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

  • Odoo 19 Community or Enterprise
  • التوطين السعودي (l10n_sa_edi_pos - يتم تثبيته تلقائياً)
  • إكمال عملية Onboarding مع ZATCA

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

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

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

  1. اذهب إلى: نقطة البيع → إعدادات → نقاط البيع
  2. اختر نقطة البيع المطلوبة
  3. فعّل "ZATCA Direct Mode"
  4. اختر حجم QR Code المناسب
  5. اختر Journal الفواتير (يجب أن يكون مكوّن مع ZATCA)

4. إضافة أسماء بديلة للمنتجات NEW

  1. افتح أي منتج من قائمة المنتجات
  2. اكتب الاسم البديل في حقل "Alternative Name (Receipt)"
  3. الاسم البديل سيظهر تلقائياً في إيصال نقطة البيع
تنبيه هام: تأكد من إكمال عملية Onboarding مع ZATCA والحصول على شهادة CSID قبل تفعيل المودول.

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

Business Ruleالوصف | Descriptionالتطبيق | Implementation
BR-KSA-33Invoice Counter Value (ICV)ir.sequence مع no_gap
BR-KSA-61Previous Invoice Hash (PIH)l10n_sa_invoice_hash field
BR-KSA-17Refund Reason Codel10n_sa_zatca_refund_reason
BR-KSA-25QR Code 9 FieldsTLV encoding with signature
KSA-2Invoice Type Code388 (Invoice) / 381 (Credit Note)
KSA-10Payment Means10 (Cash) / 30 (Credit) / 48 (Card)

الدعم الفني | Technical Support

Developer: Ahmed Magdy
Email: qarsan4@gmail.com
Website: idealitsetup.com

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.