أخطاء زاتكا في الفاتورة الإلكترونية وحلولها

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

العدّاد والهاش (السلسلة)

BR-KSA-33 و BR-KSA-34 · عدّاد الفاتورة (ICV)

المعنى: كل فاتورة لازم تحمل عدّاد الفاتورة (ICV) في cac:AdditionalDocumentReference برقم ICV، وقيمته أرقام بس. غيابه خطأ يرفض الفاتورة.

الحل: عدّاد لكل جهاز يزيد واحد مع كل فاتورة وما ينعاد ضبطه. زِده بعد قبول الهيئة للفاتورة، والفاتورة المرفوضة صلّحها وأرسلها بنفس العدّاد. تفاصيل BR-KSA-33

BR-KSA-61 و BR-KSA-26 · هاش الفاتورة السابقة (PIH)

كل فاتورة تحمل هاش اللي قبلها (SHA-256 بصيغة base64). أول فاتورة على الجهاز تستخدم القيمة الابتدائية المنشورة في SDK الهيئة، وبعدها احفظ invoice_hash من كل رد مقبول. تفاصيل BR-KSA-61

الهاش ينكسر بعد التوقيع

أي تعديل على الـ XML بعد حساب الهاش، حتى إعادة تنسيقه، يخلّي الهاش غلط. احسب الهاش آخر شي، ولا تلمس المستند بعده.

البائع والمشتري

BR-KSA-09 و BR-KSA-37 · عنوان البائع

عنوان البائع لازم فيه الشارع، ورقم المبنى، والرمز البريدي، والمدينة، والحي، ورمز الدولة (BR-KSA-09)، ورقم المبنى ٤ أرقام بالضبط (BR-KSA-37). BR-KSA-09 · BR-KSA-37

BR-KSA-08 · معرّف البائع

معرّف البائع (BT-29) يجي مرة وحدة بأحد المخططات: CRN أو MOM أو MLS أو SAG أو OTH أو 700، وبحروف وأرقام بس. الأشهر: السجل التجاري بـ schemeID="CRN". تفاصيل

BR-KSA-42 و BR-KSA-81 و BR-KSA-44 · بيانات المشتري في الفاتورة الضريبية

الفاتورة الضريبية (B2B) وإشعاراتها لازم فيها اسم المشتري (BR-KSA-42). وإذا المشتري ما عنده رقم ضريبي، لازم معرّف ثاني له (BR-KSA-81). وإذا فيه رقم ضريبي، لازم يكون ١٥ رقم يبدأ وينتهي بـ ٣ (BR-KSA-44). المبسّطة ما تحتاجها. BR-KSA-42 · BR-KSA-81 · BR-KSA-44

BR-KSA-10 · عنوان المشتري

عنوان المشتري في الفاتورة الضريبية لازم فيه الشارع والمدينة ورمز الدولة. رسالة الهيئة تذكر المشتري من خارج السعودية، لكن الفحص الفعلي في SDK يطبّقها على كل فاتورة ضريبية. ما تنطبق على المبسّطة. تفاصيل

الإشعارات الدائنة والمدينة

BR-KSA-56 و BR-KSA-17 · مرجع الإشعار وسببه

الإشعار الدائن (381) والمدين (383) لازم يرجع للفاتورة الأصلية (BillingReference، BR-KSA-56)، ولازم يذكر سبب الإصدار (BR-KSA-17، وغيابه خطأ يرفض الإشعار). وخلّ المبالغ موجبة، فنوع المستند هو اللي يحدد الاتجاه. BR-KSA-56 · BR-KSA-17

المجاميع والبنود

BR-CO-10 و BR-CO-13 و BR-CO-15 · المجاميع

مجموع صافي البنود يساوي مجموع البنود (BR-CO-10)، والإجمالي قبل الضريبة يساوي البنود ناقص الخصومات زائد الرسوم على مستوى المستند (BR-CO-13)، والإجمالي مع الضريبة يساوي الإجمالي قبلها زائد الضريبة (BR-CO-15، خطأ يرفض الفاتورة). تفاصيل BR-CO-15

BR-KSA-EN16931-11 و BR-KSA-51 · حساب البند

صافي البند = الكمية × السعر (على كمية الأساس) + رسوم البند − خصوماته، والبند مع الضريبة = صافيه + ضريبته. تفاصيل

BR-16 و BR-25 و BR-26 · البنود

الفاتورة لازم فيها بند واحد على الأقل (BR-16)، وكل بند له اسم (BR-25) وسعر صافي (BR-26). حتى لو برنامجك يرسل الإجمالي بس، سوّ بند واحد يحمل المبلغ كامل.

BR-KSA-19 · سبب الرسوم

كل رسوم على مستوى المستند تحتاج رمز سبب. تفاصيل

BR-KSA-EN16931-08 و BR-CO-18 · مجموع الضريبة

عنصر TaxTotal واحد بس يحمل تفصيل الضريبة (TaxSubtotal)، والفاتورة لازم فيها تفصيل ضريبة واحد على الأقل (BR-CO-18). تفاصيل

الضريبة والإعفاء

BR-KSA-CL-04 و BR-KSA-24 · رمز سبب الإعفاء

البند الصفري (Z) أو المعفى (E) يحتاج رمز سبب من قائمة الهيئة (VATEX-SA-…، BR-KSA-CL-04)، والخارج عن نطاق الضريبة (O) يحتاج رمز استثناء (BR-KSA-24) وهو VATEX-SA-OOS. انتبه: الرمز القديم VAT-OOS-SA يعطي تحذير CL-04، جرّبناها على قواعد SDK الهيئة. BR-KSA-CL-04 · BR-KSA-24

BR-KSA-68 و BR-KSA-EN16931-02 · عملة الضريبة

TaxCurrencyCode لازم يكون موجود (BR-KSA-68) وقيمته SAR (BR-KSA-EN16931-02)، والاثنين أخطاء ترفض الفاتورة. تفاصيل

BR-KSA-16 · رمز طريقة الدفع

إذا الفاتورة فيها طريقة دفع (BT-81)، رمزها لازم من قائمة UNTDID 4461 المعتمدة (مثل 10 للكاش، 30 للتحويل، 48 للبطاقة). تفاصيل

المهلة وطول الحقول

BR-KSA-98 · مهلة الـ ٢٤ ساعة

الفاتورة المبسّطة لازم تتبلّغ للهيئة خلال ٢٤ ساعة من إصدارها. تفاصيل

BR-KSA-F-06 · طول الحقول

عائلة قواعد لحدود طول كل حقل. القيمة الفاضية أو الأطول من الحد تعطي تحذير. جدول الحدود كلها

أشياء ما لها كود لكنها توقفك

كل القواعد مع شروحاتها متاحة كبيانات مفتوحة (JSON) على GitHub.

عندك رد من الهيئة؟ الصقه في قارئ رد زاتكا ويشرح لك كل كود فيه.

وشوف وين قواعد زاتكا تختلف عن نصها: ٦ ملاحظات مجرّبة.

كل قواعد زاتكا

قواعد السعودية (BR-KSA)

قواعد الفاتورة الأساسية (EN 16931)

المجاميع والحسابات (BR-CO)

فئات الضريبة (S, Z, E, O)

قوائم الرموز (BR-CL)

صيغ الحقول (BR-KSA-F)

جرّب فاتورة على زاتكا الحين

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

جرّب فاتورة أو اقرأ دليل الربط ←