دليل · السعودية
أخطاء رفض الفاتورة الإلكترونية في زاتكا وطريقة حلها
أخطاء وتحذيرات التحقق اللي تظهر أكثر في ربط الكاشير والمحاسبة. لكل واحد رمزه، وما يفحصه، والسبب المعتاد، والحل.
الأخطاء والتحذيرات: كيف تتعامل معها الهيئة
الهيئة ترد على كل مستند بإحدى ثلاث نتائج. مقبول، ويرجع برمز HTTP 200. مقبول مع تحذيرات، ويرجع 202. مرفوض، ويرجع 400، وخطأ واحد يكفي: الهيئة تقول إن المستند اللي فيه خطأ واحد ترفضه كله.
التحذيرات حالة ثانية. الهيئة تقول إنها مقبولة بشكل مؤقت وممكن تتحول إلى رفض في المستقبل، وإن التحذيرات المتواصلة تدخل في التحقيق، وإن تكرار عدم الالتزام اللي يطلع منه تحذيرات ممكن يعرّضك للغرامات المنطبقة. لا ترسل من جديد فاتورة رجعت بتحذيرات. أصلح السبب في نظامك لتصل الفواتير التالية نظيفة.
الجداول تحت فيها الرموز اللي تظهر أكثر في ربط الكاشير والمحاسبة، القائمة الكاملة في معيار XML أطول. نص القاعدة من معيار تنفيذ XML الصادر عن الهيئة (الإصدار 1.2). والصفوف المعلّمة «في SDK فقط» من أداة التحقق SDK، وفيها قواعد ما هي في المعيار. وتصنيف الرمز كخطأ أو تحذير حسب وقت الكتابة (إصدار SDK 238-R3.4.8). الهيئة تغيّر التصنيف بين الإصدارات، وكان تصنيف BR-KSA-08 وBR-KSA-F-01 مختلف في نسخة أقدم. راجع التصنيف في الإصدار اللي تختبر عليه قبل ما تعتمد على أي صف.
الأخطاء: الهيئة ترفض الفاتورة
| الرمز | القاعدة | السبب المعتاد في ربط الكاشير | الحل |
|---|---|---|---|
| BR-KSA-03 | المستند فيه UUID (KSA-1) من حروف وأرقام وشرطات فقط. | الـ UUID ناقص، أو بقيت معه أقواس من صيغة GUID في ويندوز. | أنشئ UUID لكل مستند واحذف الأقواس. |
| BR-KSA-04 | تاريخ الإصدار (BT-2) ما يتجاوز تاريخ اليوم. | ساعة السيرفر أو المنطقة الزمنية غلط، أو الفاتورة مؤرخة بتاريخ قادم. | زامن الساعة مع NTP، وتعامل مع المناطق الزمنية صح: وقت الإصدار بتوقيت السعودية أو UTC مع حرف Z. |
| BR-KSA-05BR-04 | رمز نوع الفاتورة موجود ومن قائمة الهيئة: 388 فاتورة، 381 إشعار دائن، 383 إشعار مدين، 386 دفعة مقدمة. | أنواع المستندات في الكاشير ترسل كما هي بدون تحويل. | حوّل كل نوع مستند في الكاشير إلى الرمز المقابل في قائمة الهيئة. |
| BR-KSA-06 | رمز المعاملة (KSA-2) يتبع بنية الأعلام المحددة: يبدأ بـ 01 للفاتورة الضريبية وبـ 02 للمبسطة. | سلسلة الأعلام ناقصة أو شكلها غلط. | ابنها كما يصفها معيار XML: ابدأ بـ 01 للفاتورة الضريبية وبـ 02 للمبسطة. |
| BR-KSA-14 | إذا أُرسل معرّف للمشتري (BT-46)، يلزم أن يكون بنوع مسموح (TIN وCRN وMOM وMLS و700 وSAG وNAT وGCC وIQA وPAS وOTH) وحروف وأرقام فقط. | معرّف المشتري مرسل بدون نوع، أو بنوع غير موجود في القائمة، أو فيه مسافات أو شرطات. | حوّل نوع كل معرّف عميل إلى أحد الرموز المسموحة واحذف أي رموز غير الحروف والأرقام. |
| BR-KSA-17 | الإشعار الدائن والمدين (381 و383) يحمل السبب (KSA-10). | مرتجع أو إلغاء يرسل بدون سبب. | اجعل حقل السبب إلزامي في المرتجعات واربطه بـ KSA-10. |
| BR-KSA-18 | رمز فئة الضريبة واحد من: S وZ وE وO. | رموز ضريبة مخصصة مثل VAT15 ترسل كما هي. | حوّل جدول الضرائب إلى S أو Z أو E أو O. |
| BR-KSA-33BR-KSA-34 | قيمة عداد الفواتير (KSA-16) موجودة وأرقام فقط. | العداد ناقص، أو قبله رمز فرع. | استخدم عداد أرقام فقط، ومنفصل لكل وحدة. |
| BR-KSA-39 | الرقم الضريبي للبائع (BT-31) موجود. | ملف البائع ما انضبط. | ضع الرقم الضريبي للبائع في إعدادات الربط. |
| BR-KSA-40BR-KSA-44 | الرقم الضريبي للبائع، وللمشتري إذا وجد، من 15 رقم يبدأ بـ 3 وينتهي بـ 3. | خطأ إملائي أو مسافات، أو استخدام رقم تعريف ضريبي من 10 أرقام. | تحقق من الصيغة عند الإعداد وعند إنشاء العميل. |
| BR-KSA-52BR-KSA-53 | ضريبة السطر (KSA-11) ومبلغ السطر مع الضريبة (KSA-12) موجودين في الفواتير الضريبية (01). | المجاميع تحسب على مستوى المستند فقط. | أرسل لكل سطر TaxTotal فيه TaxAmount وRoundingAmount. |
| BR-KSA-68BR-KSA-EN16931-02 | رمز عملة الضريبة (BT-6) موجود ويساوي SAR. | الحقل ناقص، أو فاتورة بعملة أجنبية ترسل USD كعملة للضريبة. | أرسل cbc:TaxCurrencyCode بقيمة SAR في كل فاتورة، وحوّل مبلغ الضريبة في BT-111. |
| BR-KSA-70 | وقت الإصدار (KSA-25) موجود بصيغة hh:mm:ss، أو hh:mm:ssZ لـ UTC. | الوقت ناقص، أو معه ميلي ثانية أو إزاحة. | التزم بالصيغة بالضبط. |
| BR-KSA-84في SDK فقط | نسبة الضريبة المعيارية 5 أو 15 فقط. | النسبة مرسلة 0.15، أو نسبة قديمة. | أرسل النسبة كرقم مثل 15. |
| BR-KSA-DEC-02 | نسبة الضريبة بين 0.00 و100.00، بمنزلتين عشريتين كحد أقصى وبدون علامة %. | نص مثل "15%" أو 15.000. | أرسل رقم بمنزلتين عشريتين كحد أقصى. |
| BR-KSA-F-01 | التواريخ بصيغة YYYY-MM-DD. | صيغة تاريخ محلية مثل 24/10/2026، أو تاريخ هجري. | استخدم صيغة ISO 8601.صنفته نسخة أقدم من SDK على أنه تحذير. |
| BR-KSA-F-04 | كل المبالغ والكميات موجبة، إلا ما استثنته القاعدة. | المرتجعات ترسل كفواتير بكميات سالبة. | أصدر إشعار دائن (381) بمبالغ موجبة بدل الأسطر السالبة. |
| BR-CO-14BR-CO-15 | إجمالي الضريبة (BT-110) = مجموع ضرائب الفئات (BT-117)، والإجمالي مع الضريبة (BT-112) = الإجمالي بدون ضريبة (BT-109) + إجمالي الضريبة (BT-110). | تقريب كل سطر يعطي فرق هللة عن تقريب كل فئة، أو أسعار الكاشير الشاملة للضريبة تحسب بالعكس بتقريب غير ثابت. | احسب BT-110 كمجموع قيم BT-117، واشتق باقي الإجماليات من نفس القيم المقربة. |
| BR-CUSTOM-VALIDATION-01في SDK فقط | الرقم الضريبي للبائع يختلف عن الرقم الضريبي للمشتري. | الرقم الضريبي للبائع مستخدم كبديل مؤقت في خانة المشتري. | اترك خانة الرقم الضريبي للمشتري فارغة، واستخدم BT-46 إذا احتجت معرّف. |
التحذيرات: الهيئة تقبل الفاتورة
| الرمز | القاعدة | السبب المعتاد في ربط الكاشير | الحل |
|---|---|---|---|
| BR-KSA-98في SDK فقط | الفاتورة المبسطة ترسل خلال 24 ساعة من إصدارها. | طابور كاشير يعمل بدون إنترنت، أو مهمة ليلية تجمع الفواتير. | أرسل أول بأول وأعد المحاولة. وإذا منعك انقطاع، عند الهيئة نموذج للإبلاغ عن الأعطال. |
| BR-KSA-61 | قيمة hash للفاتورة السابقة (KSA-13) موجودة. | حقل PIH فاضي. | احفظ آخر hash لكل وحدة وأرسله مع كل مستند. |
| BR-KSA-26 | الـ PIH بصيغة base64 لقيمة SHA-256 محسوبة بالتحويل اللي حددته الهيئة. وللمستند الأول هو hash للرقم 0. | تهيئة XML (canonicalization) غلط، أو حساب الـ hash على XML الموقّع. | اتبع خطوات التحويل في معيار XML (BR-KSA-26) وفي الدليل الفني. |
| BR-KSA-27 | المستند فيه رمز QR (KSA-14) بصيغة base64Binary. | رمز QR غير مضمّن في XML. | ضمّنه كـ AdditionalDocumentReference بمعرّف QR. |
| BR-KSA-60 | ختم التشفير موجود على المستندات المبسطة (02). | الكاشير يرسل الفواتير المبسطة بدون توقيع ويتوقع أن الهيئة تختمها. | وقّع عليها في وحدتك. الهيئة ما تختم الفواتير المبسطة. |
| BR-KSA-08 | معرّف البائع (BT-29) يظهر مرة واحدة بنوع مسموح (CRN وMOM وMLS وSAG وOTH و700)، وحروف وأرقام فقط. | السجل التجاري ناقص في ملف البائع، أو فيه أكثر من معرّف. | أضف السجل التجاري للفرع.التصنيف اختلف بين نسخ SDK. |
| BR-KSA-09 | عنوان البائع فيه الشارع ورقم المبنى والرمز البريدي والمدينة والحي والدولة. | العنوان الوطني ناقص. | أكمل العنوان الوطني في الإعدادات. |
| BR-KSA-42BR-KSA-81 | اسم المشتري (BT-44) موجود في الفواتير الضريبية، ومعرّف آخر للمشتري (BT-46) موجود إذا غاب رقمه الضريبي. | بيع شركات مسجل على عميل عابر، أو عميل شركة بدون رقم ضريبي وبدون سجل تجاري. | اجعل اختيار العميل إلزامي في مبيعات الشركات، وسجّل السجل التجاري أو الهوية. |
| BR-KSA-56 | الإشعار الدائن والمدين يحمل مرجع الفاتورة الأصلية (BT-25). | المرتجع غير مربوط بالبيع الأصلي. | احفظ رقم الفاتورة الأصلية وأرسله. |
| BR-KSA-23BR-KSA-24BR-KSA-69BR-KSA-CL-04BR-KSA-83 | كل تفصيل ضريبي (BG-23) لفئة معفاة (E) أو غير خاضعة (O) أو بنسبة صفر (Z) يحمل رمز سبب الإعفاء أو الاستثناء من الهيئة مع نصه. | أصناف بنسبة صفر معرّفة بدون سبب. | حوّل الأصناف إلى رموز VATEX-SA حسب معيار XML. |
| BR-KSA-51 | مبلغ السطر مع الضريبة (KSA-12) = صافي السطر (BT-131) + ضريبة السطر (KSA-11). | التقريب على مستوى الوحدة بدل السطر. | قرّب على مستوى السطر بنفس الطريقة في كل مرة. |
| BR-KSA-85BR-KSA-86في SDK فقط | شكل رقم هاتف المشتري وبريده الإلكتروني سليم، إذا وجدا. | رقم هاتف فيه مسافات أو شرطات. | نظّف الصيغة، أو لا ترسل الحقل. |
إخفاقات بدون رمز منشور
بعض الإخفاقات تأتي من واجهة API نفسها. ما لقينا قائمة منشورة من الهيئة برموز هذه الردود، فلا نذكر أي رمز منها. لكن آلياتها موثقة، وفيها يتعطل الربط الشغال عادة.
- سلسلة الـ hash. كل مستند يحمل hash للمستند المولّد قبله مباشرة. ولازم يكون آخر مستند مولّد حتى لو رفضته الهيئة، لأن المنصة تسجل hash المستندات المرفوضة. ومثال الهيئة يقول استخدم hash المستند المرفوض، لا hash المستند اللي قبله.
- إعادة استخدام العداد. الهيئة تقول إن قيمة العداد إذا استخدمت في مستند فلا تذكر على مستند ثاني. فالمستند المصحح أو المعاد بناؤه يأخذ قيمة عداد جديدة. أما إعادة إرسال نفس المستند بعد رد 429 أو 5xx فليست مستند جديد، فيبقى بقيمه.
- الشهادات. الهيئة تقول إن الفواتير الموقّعة بشهادة غير صالحة ترفضها. ورد HTTP 401 معناه: افحص شهادة المصادقة والسر وأعد الإرسال. وفحوصات التوافق تفشل إذا كانت شهادة Compliance CSID ناقصة أو غير صالحة أو منتهية.
- التسجيل. طلب CSR ممكن ترفضه الهيئة بسبب OTP غير صالح أو منتهي، أو OTP لا يطابق الرقم الضريبي، أو رقم ضريبي غير صالح، أو حقل ناقص. والمسجل الجديد في ضريبة القيمة المضافة ينتظر يومين عمل قبل ما يسجل وحدته، والفواتير الصادرة له كمشتري ترفضها الهيئة حتى تمضي هذه المدة.
كيف تتصرف مع مستند مرفوض
الإصلاح يكون بمستند جديد: UUID جديد، وقيمة عداد جديدة، وhash جديد، وقيمة PIH فيه هي hash المستند المولّد قبله مباشرة.
- الفاتورة الضريبية (B2B) ما تصير صالحة قبل الاعتماد. صحّحها وأرسلها من جديد، وحدّث تاريخ الفاتورة.
- الإيصال المبسط (B2C) عند العميل بالفعل، فلا تصدره له من جديد. صحّح البيانات وأرسله كمستند جديد بتاريخ العملية الأصلي. وفي دليل الهيئة سؤال آخر يقول إن الفاتورة تلغيها بإشعار دائن وتصدر فاتورة جديدة، فاسأل محاسبك أي طريق ينطبق عليك.
- أعد المحاولة على أخطاء HTTP 429 و500 و503 و504، وعندها تكتب الهيئة «أعد الإرسال». ولا تعيد إرسال مستند رجع بـ 400 كما هو.
- جرّب قبل الإرسال. SDK من الهيئة يفحص ملفات XML ورموز QR بدون اتصال، والبيئة التجريبية تحاكي التسجيل والإرسال.
لمعرفة من يجب أن يربط، وطريقي الاعتماد والإرسال، وكيف يرتبط الكاشير السحابي من البداية، اقرأ دليل ربط الفاتورة الإلكترونية مع زاتكا.
أسئلة شائعة
لا. رد التحذيرات (HTTP 202) معناه أن الهيئة قبلت الفاتورة. أصلح السبب في نظامك لتصل الفواتير التالية نظيفة. الهيئة تقول إن التحذيرات مقبولة الآن وممكن تتحول إلى رفض في المستقبل، وإن المتواصل منها يدخل في التحقيق.
ما تصير صالحة قبل أن تعتمدها الهيئة. صحّحها وأرسلها كمستند جديد له UUID جديد وقيمة عداد جديدة وhash جديد. والهيئة تقول حدّث تاريخ الفاتورة.
لا تصدر الإيصال للعميل من جديد. صحّح البيانات وأرسلها كمستند جديد بتاريخ العملية الأصلي. وفي دليل الهيئة نفسه سؤال آخر يقول إن الفاتورة غير المرسلة تلغيها بإشعار دائن وتستبدلها، فاسأل محاسبك أي طريق ينطبق عليك.
لا. الهيئة تقول إنها تعتبر الفاتورة مرة واحدة حسب معرّفات مثل UUID وhash. أما الفجوات في تسلسل الفواتير فمسألة ثانية: الهيئة تقول إنها تخضع لمزيد من التحقيق وممكن تنتج عنها غرامات.
المصادر
كل رمز واقتباس في هذه الصفحة من مستندات الهيئة أدناه، كما راجعناها في 24 أكتوبر 2026. التصنيفات قرأناها من نسخة SDK 238-R3.4.8 لأن الملف خلف تسجيل دخول في موقع الهيئة، ويلزم تأكيدها من تنزيل جديد. والأسباب والحلول ملاحظاتنا الهندسية.
- معيار تنفيذ XML للفاتورة الإلكترونية (الإصدار 1.2، 19 مايو 2023)، القسم 13: قواعد التحقق (بالإنجليزية)
- صفحة تنزيل مجموعة أدوات التحقق (SDK) من الهيئة
- الدليل الإرشادي التفصيلي للفوترة الإلكترونية (الإصدار 2، مايو 2023)
- الدليل الفني التفصيلي للفوترة الإلكترونية (الإصدار 2، نوفمبر 2022، بالإنجليزية فقط)
- معايير تنفيذ ميزات الأمان (الإصدار 1.2، 19 مايو 2023)
- قرار التطبيق: الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية (النص العربي)
اعرف سبب رجوع فواتيرك.
ابدأ بجلسة تقييم 30 دقيقة. نشوف ما يرسله نظامك للهيئة وأين يختلف عن القواعد، سواء تعاملت معنا أو لا.