هذه الصفحة تمنحك نموذج فاتورة XML جاهزًا للنسخ واللصق: ملف فاتورة ضريبية معيارية (B2B) مكتوب بالكامل وفق معيار UBL 2.1 الذي اعتمدته هيئة الزكاة والضريبة والجمارك (ZATCA) في المرحلة الثانية من الفاتورة الإلكترونية. كل كتلة في النموذج مشروحة بالعربية، سطرًا سطرًا، حتى تفهم ما تفعله قبل أن تعتمد عليها في بيئة المحاكاة (Sandbox) أو الإنتاج.
الفرق بين هذه الصفحة والصفحات الأخرى في مركز المطوّرين مهم. هنا تجد مثالًا كاملًا تنسخه وتجرّبه، لا شرحًا للتنسيق. إذا أردت فهم التنسيق التقني للملف، فارجع إلى فاتورة XML: التنسيق التقني للفاتورة الإلكترونية. وإذا أردت فهم بنية المستند وأقسامه الثلاثة وكيف تتداخل في شجرة واحدة، فارجع إلى بنية الفاتورة الإلكترونية. تلك الصفحتان تشرحان الشكل، وهذه الصفحة تعطيك المضمون الجاهز.
الجمهور المستهدف هنا هو المطوّر أو محلّل التكامل الذي يبني نظام فوترة، أو يربط نظامًا قائمًا مع منصة فاتورة، أو يختبر استجابة الـ API قبل الإطلاق. النموذج أدناه يصلح كنقطة انطلاق تستبدل فيها بيانات البائع والمشتري والبنود ببيانات منشأتك الفعلية، ثم تمرّره على مرحلة التحقق قبل الإرسال.
ما الذي ستجده في هذا النموذج
النموذج الكامل يمثّل فاتورة ضريبية معيارية موجّهة من منشأة إلى منشأة أخرى. هذا النوع يخضع لـالمقاصة (Clearance): ترسله إلى منصة فاتورة، تعتمده الهيئة وتختمه، ثم يعود إليك لتسلّمه للمشتري. وهذا يختلف عن الفاتورة الضريبية المبسّطة الموجّهة للأفراد، التي تُصدر فورًا وتُبلَّغ خلال 24 ساعة. سنعرض النموذج المعياري كاملًا، ثم نوضّح الفروق التي تحوّله إلى نموذج مبسّط.
النموذج يغطّي العناصر التي تطلبها المرحلة الثانية كلها: ترويسة تحمل هوية الفاتورة وأطرافها، بندًا واحدًا على الأقل بتفاصيل الصنف وضريبته، وكتلة إجماليات تحمل صافي القيمة ومقدار الضريبة والإجمالي شامل الضريبة. كما يحمل الحقول التقنية الإلزامية: المعرّف الفريد (UUID)، وعدّاد الفاتورة (ICV)، وتجزئة الفاتورة السابقة (PIH)، وموضع الختم التشفيري ورمز الاستجابة السريع (QR).
ملاحظة منهجية مهمة قبل أن تبدأ: قيمة الختم التشفيري وقيمة رمز QR وقيمة التجزئة في النموذج هي قيم توضيحية مختصرة (placeholder). هذه القيم يولّدها نظامك أو منصة فاتورة آليًا عند الإصدار باستخدام شهادة CSID، ولا تُكتب يدويًا. النموذج يبيّن موضعها في الملف، لا قيمها النهائية.
النموذج الكامل: فاتورة ضريبية معيارية (B2B)
انسخ الكتلة التالية كاملة. هي ملف UBL 2.1 صالح بنيويًا، يبدأ بإعلان مساحات الأسماء (namespaces) ثم يمرّ على الترويسة فالأطراف فالبند فالإجماليات. بعد الكتلة، نشرح كل قسم على حدة.
هذا الملف يمثّل بيعًا واحدًا: عشر وحدات من خدمة استشارية، سعر الوحدة 100 ر.س، فيكون صافي السطر 1,000 ر.س، والضريبة 15% أي 150 ر.س، فالإجمالي 1,150 ر.س. لاحظ كيف تتطابق هذه الأرقام في كل كتلة من الملف. هذا التطابق شرط أساسي لاجتياز مرحلة التحقق.
شرح إعلان مساحات الأسماء (Namespaces)
UBLExtensions: الامتدادات والختم
الترويسة: المعرّفات والتواريخ والنوع
الأطراف: البائع والمشتري
البنود والإجماليات: InvoiceLine وTotals
كل ملف فاتورة يبدأ بسطر إعلان XML يحدّد الإصدار والترميز، ثم العنصر الجذر Invoice. داخل هذا العنصر تُعلَن أربع مساحات أسماء. المساحة الافتراضية تُعرّف نوع المستند نفسه كفاتورة UBL 2.1. ومساحة cac تختصر «المكوّنات المجمّعة المشتركة» وتُستخدم للكتل المركّبة كالأطراف والبنود. ومساحة cbc تختصر «المكوّنات الأساسية المشتركة» وتُستخدم للقيم المفردة كالتاريخ والمبلغ. ومساحة ext تُخصَّص لقسم الامتدادات الذي يحمل التوقيع والختم.
لا تعدّل هذه السطور إطلاقًا. الترميز يجب أن يبقى UTF-8 لأن الملف يحوي نصًا عربيًا كاسم المنشأة واسم الصنف. وأي خطأ في عنوان مساحة الأسماء يجعل الملف غير صالح من حيث المخطط (Schema)، فيُرفض في أول خطوة من التحقق قبل أن يصل إلى أي قاعدة عمل.
لتفهم لماذا اختارت الهيئة هذا المعيار تحديدًا وكيف يضمن توافق الأنظمة المختلفة، راجع معيار UBL 2.1 في الفاتورة الإلكترونية. هذه الصفحة تشرح المعيار، وما نفعله هنا هو تطبيقه عمليًا.
شرح كتلة الامتدادات (UBLExtensions)
كتلة ext:UBLExtensions تأتي أولًا داخل العنصر الجذر، قبل أي حقل آخر، وهذا ترتيب إلزامي في معيار UBL. في النموذج تركناها شبه فارغة عمدًا، لأن محتواها يُملأ آليًا عند الإصدار.
عند إصدار الفاتورة، يضع نظامك أو منصة فاتورة داخل هذه الكتلة التوقيع الرقمي المبني على المفتاح الخاص بمنشأتك، والختم التشفيري المرتبط بشهادة CSID المعتمدة من الهيئة. هذان العنصران معًا يثبتان أن الفاتورة صدرت من منشأة مسجّلة ولم تُعدَّل بعد ختمها.
أهم خطأ يقع فيه المطوّرون هنا هو محاولة كتابة التوقيع يدويًا أو نسخه من فاتورة أخرى. التوقيع يُحسب على محتوى الفاتورة نفسها، فأي فاتورة لها توقيع فريد. النموذج يترك القسم فارغًا ليبيّن لك موضعه فقط، وعملية التوقيع تتولّاها شهادة CSID آليًا. لفهم آلية الختم بالتفصيل، راجع صفحة الختم التشفيري في مركز المطوّرين.
شرح ترويسة الفاتورة (Header)
| الحقل | من يولّده |
|---|---|
| ID (رقم الفاتورة) | تسلسل المنشأة |
| UUID | النظام آلياً |
| IssueDate/Time | النظام |
| InvoiceTypeCode | حسب نوع الفاتورة |
| ICV / PIH | النظام (عدّاد وسلسلة) |
الترويسة تحمل هوية الفاتورة. الحقل cbc:ID هو رقم الفاتورة المتسلسل عندك، ويجب أن يكون فريدًا داخل دفاترك. أما cbc:UUID فهو معرّف عالمي فريد يولّده نظامك لكل فاتورة، ولا يتكرر أبدًا. لا تخلط بينهما: الأول رقمك التجاري، والثاني بصمة تقنية. لمزيد من التفصيل راجع صفحة المعرّف الفريد UUID في مركز المطوّرين.
الحقلان cbc:IssueDate وcbc:IssueTime يحملان تاريخ الإصدار ووقته بالصيغة المعيارية. التاريخ بصيغة سنة فشهر فيوم، والوقت بنظام 24 ساعة. هذان الحقلان يدخلان في حساب رمز QR والتوقيع، فأي تباين بينهما وبين وقت الإرسال الفعلي قد يثير ملاحظة من قواعد التحقق.
الحقل cbc:InvoiceTypeCode هو الأهم في تحديد نوع الفاتورة. القيمة 388 تعني فاتورة ضريبية معيارية. والسمة name التي قيمتها 0100000 هي راية مكوّنة من سبع خانات، تصف خصائص الفاتورة. الخانة الثانية هنا قيمتها 1، وتعني أن الفاتورة موجّهة من منشأة إلى منشأة، أي معيارية تخضع للمقاصة. هذه الراية هي ما سنغيّره لاحقًا لتحويل النموذج إلى مبسّط.
الحقلان cbc:DocumentCurrencyCode وcbc:TaxCurrencyCode يثبتان أن العملة هي الريال السعودي. في فواتير السوق المحلي تكون القيمتان SAR دائمًا. لو اختلفت عملة المستند عن عملة الضريبة، لزم إضافة حقول تحويل، وهذا نادر في الفوترة المحلية.
شرح عدّاد الفاتورة (ICV) والتجزئة السابقة (PIH)
تحت الترويسة يأتي حقلان تقنيان يضمنان تسلسل الفواتير. الأول هو عدّاد الفاتورة ICV: رقم يتزايد بمقدار واحد مع كل فاتورة تصدرها المنشأة، ولا يعود للوراء أبدًا. في النموذج قيمته 123، أي أنها الفاتورة رقم 123 في سلسلة هذا الجهاز. لمزيد من التفصيل راجع صفحة عدّاد الفاتورة ICV.
الثاني هو تجزئة الفاتورة السابقة PIH: بصمة مشفّرة للفاتورة التي سبقتها مباشرة، مرمّزة بـ Base64. هذه القيمة تربط كل فاتورة بالتي قبلها في سلسلة لا يمكن كسرها. لو حذف أحد فاتورة من المنتصف، انكسرت السلسلة وظهر التلاعب فورًا. أول فاتورة في حياة الجهاز تحمل قيمة تجزئة ثابتة معروفة، ثم تأخذ كل فاتورة لاحقة تجزئة سابقتها.
القيمة المعروضة في النموذج مختصرة لأغراض الشرح. القيمة الحقيقية أطول، وهي ناتج خوارزمية SHA-256 على الفاتورة السابقة بعد ترميزه بـ Base64. نظامك يحسبها آليًا ويضعها في موضعها، ولا تكتبها يدويًا.
لماذا يهتم المطوّر بهذين الحقلين تحديدًا؟ لأنهما أكثر مصدرين للأخطاء في التكامل الجديد. لو أعاد نظامك الترقيم من واحد بعد إعادة تشغيل الخادم، تكرّر العدّاد وانكسرت السلسلة. ولو أرسلت فاتورتين بالتوازي دون ترتيب، اختلطت قيم التجزئة. القاعدة العملية: ولّد العدّاد والتجزئة في خيط واحد متسلسل لكل جهاز إصدار، ولا تسمح بإصدار فاتورتين في اللحظة نفسها على المسار نفسه. هذا يحفظ التسلسل سليمًا ويجنّبك أصعب أخطاء التحقق على الإطلاق.
شرح كتلة البائع (Supplier)
كتلة cac:AccountingSupplierParty تحمل هوية من أصدر الفاتورة. أهم حقل فيها هو cbc:CompanyID داخل cac:PartyTaxScheme، وهو رقم تسجيل ضريبة القيمة المضافة المكوّن من 15 خانة. هذا الرقم يجب أن يبدأ وينتهي بالرقم 3، وأن يكون مطابقًا لتسجيلك لدى الهيئة، وإلا رُفضت الفاتورة في المقاصة.
الحقل cbc:ID schemeID="CRN" يحمل رقم السجل التجاري للمنشأة. وكتلة cac:PostalAddress تحمل العنوان الوطني: اسم الشارع ورقم المبنى والحي والمدينة والرمز البريدي ورمز الدولة SA. هذه الحقول إلزامية في الفاتورة المعيارية، وحذف أي منها يثير خطأ تحقق.
الحقل cbc:RegistrationName داخل cac:PartyLegalEntity يحمل الاسم النظامي للمنشأة كما هو في السجل. اكتبه بالعربية كما هو مسجّل، ولا تترجمه. هنا تظهر فائدة ترميز UTF-8 الذي أعلنّاه في رأس الملف.
شرح كتلة المشتري (Customer)
كتلة cac:AccountingCustomerParty تشبه كتلة البائع، لكنها تصف من تشتري منه أو من تبيع له. في الفاتورة المعيارية الموجّهة من منشأة إلى منشأة، يجب أن يحمل المشتري رقم تسجيل ضريبي صالحًا في cbc:CompanyID، لأن الطرفين خاضعان للضريبة، والمشتري سيخصم ضريبة المدخلات بناءً على هذه الفاتورة.
هذا الفرق جوهري. في الفاتورة المعيارية يكون الرقم الضريبي للمشتري إلزاميًا، بينما في الفاتورة المبسّطة الموجّهة للأفراد لا يُطلب لأن الفرد لا يخصم ضريبة مدخلات. لتفصيل فواتير الأفراد تقنيًا راجع فواتير B2C للأفراد تقنياً.
عنوان المشتري هنا أبسط قليلًا من عنوان البائع، لأن بعض حقوله اختيارية في المرحلة الثانية. مع ذلك، يبقى رمز الدولة واسم المدينة والرمز البريدي عناصر يُنصح بإكمالها لتفادي ملاحظات التحقق وضمان وضوح الفاتورة.
نقطة عملية للمطوّر: لا تفترض أن المشتري دائمًا منشأة. ابنِ تكاملك بحيث يقرأ نوع المشتري أولًا، ثم يقرّر هل يضيف كتلة cac:PartyTaxScheme أم يحذفها. لو أدرجت رقمًا ضريبيًا فارغًا أو غير صالح في فاتورة فرد، فقد يثير ذلك خطأ بدل أن يحلّه. المرونة في توليد هذه الكتلة حسب نوع الطرف هي ما يميّز تكاملًا ناضجًا عن آخر هشّ.
شرح بند الفاتورة (Invoice Line)
الكمية × سعر الوحدة = صافي السطر
صافي السطر × 15% = الضريبة
صافي + ضريبة = الإجمالي
كتلة cac:InvoiceLine هي قلب الفاتورة. كل صنف تبيعه يصبح بندًا مستقلًا. في النموذج بند واحد، لكنك تكرّر هذه الكتلة لكل صنف إضافي مع زيادة قيمة cbc:ID بمقدار واحد. لتفصيل أعمق راجع بنود الفاتورة (Invoice Lines) في XML.
الحقل cbc:InvoicedQuantity يحمل الكمية، والسمة unitCode فيه تحدّد وحدة القياس. القيمة PCE تعني «قطعة»، وهناك رموز أخرى للكيلوغرام والساعة والمتر. والحقل cbc:LineExtensionAmount يحمل صافي السطر قبل الضريبة، وهو حاصل ضرب الكمية في سعر الوحدة. في النموذج: 10 وحدات في 100 ر.س فينتج 1,000 ر.س.
كتلة cac:Item تحمل اسم الصنف وتصنيفه الضريبي. والحقل cbc:ID داخل cac:ClassifiedTaxCategory قيمته S أي «خاضع للنسبة المعيارية»، والنسبة 15%. هذا التصنيف يخبر الهيئة كيف تُحسب الضريبة على هذا الصنف. لو كان الصنف معفى لاختلفت القيمة، ولو كان صفري النسبة لاختلفت كذلك.
كتلة cac:Price تحمل سعر الوحدة الواحدة في cbc:PriceAmount. انتبه إلى الفرق: سعر الوحدة 100 ر.س، وصافي السطر 1,000 ر.س. النظام يتحقق من أن صافي السطر يساوي الكمية مضروبة في سعر الوحدة، فأي تباين يثير خطأ حسابيًا في التحقق.
شرح كتلة الإجماليات (Totals)
بعد البنود تأتي كتلتان للإجماليات. الأولى cac:TaxTotal على مستوى الفاتورة كلها، وتحمل مجموع الضريبة موزّعًا حسب فئة الضريبة في cac:TaxSubtotal. هنا يظهر الوعاء الخاضع TaxableAmount بقيمة 1,000 ر.س، ومقدار الضريبة TaxAmount بقيمة 150 ر.س، والنسبة 15%.
الكتلة الثانية cac:LegalMonetaryTotal هي الإجماليات النقدية النهائية. فيها TaxExclusiveAmount أي الإجمالي قبل الضريبة (1,000 ر.س)، وTaxInclusiveAmount أي الإجمالي شامل الضريبة (1,150 ر.س)، وPayableAmount أي المبلغ المستحق الدفع (1,150 ر.س). في فاتورة بلا خصومات أو سلف، يتساوى الإجمالي شامل الضريبة مع المبلغ المستحق.
القاعدة الذهبية في كتلة الإجماليات هي التطابق التام. مجموع LineExtensionAmount لكل البنود يجب أن يساوي TaxExclusiveAmount، ومجموع الضرائب يجب أن يساوي TaxAmount في كتلة الفاتورة. أكثر أخطاء التحقق شيوعًا هو تباين بريال واحد بسبب تقريب خاطئ. احسب الضريبة على مستوى البند أو على مستوى الفاتورة بطريقة موحّدة، ولا تخلط بينهما.
دع قيود يولّد ملف XML نيابةً عنك
يبني قيود ملف الفاتورة المعياري بالكامل، ويوقّعه ويختمه عبر منصة فاتورة، ويتحقق منه قبل الإرسال. أنت تكتب الفاتورة، والباقي آلي.
كيف تحوّل النموذج إلى فاتورة مبسّطة (B2C)
النموذج أعلاه معياري موجّه من منشأة إلى منشأة. لتحويله إلى فاتورة ضريبية مبسّطة موجّهة للأفراد، تغيّر عناصر محدّدة فقط، والبنية العامة تبقى نفسها.
أول تغيير في الترويسة: قيمة cbc:InvoiceTypeCode تبقى 388، لكن السمة name تتغيّر من 0100000 إلى 0200000. الخانة الثانية صارت 2، وتعني أن الفاتورة موجّهة من منشأة إلى مستهلك. هذا التغيير وحده يحوّل مسار الفاتورة من المقاصة إلى الإبلاغ.
التغيير الثاني في كتلة المشتري: لم يعد رقم التسجيل الضريبي للمشتري إلزاميًا، لأن المستهلك الفرد لا يخصم ضريبة مدخلات. يمكنك حذف cac:PartyTaxScheme من كتلة المشتري، وقد تكتفي باسم المشتري أو تتركه عامًا.
التغيير الثالث جوهري في المسار لا في الملف: الفاتورة المبسّطة لا تُرسل للمقاصة قبل تسليمها. تصدرها وتسلّمها للمشتري فورًا، ثم تبلّغ بها منصة فاتورة خلال 24 ساعة. كما يصبح رمز QR إلزاميًا ومرئيًا على الفاتورة المطبوعة، لأن المستهلك يستخدمه للتحقق. لفهم آلية المقاصة والإبلاغ بالتفصيل راجع صفحتي المقاصة والإبلاغ في مركز المطوّرين.
اقرأ الملف من أعلاه لأسفله مرة واحدة
قبل أن تعدّل النموذج، تدرّب على قراءته كما يقرأه المحقّق. ابدأ من إعلان XML الذي يحدّد الإصدار والترميز. ثم العنصر الجذر Invoice بمساحات الأسماء الأربع. ثم كتلة الامتدادات الفارغة التي ستحمل التوقيع لاحقًا. هذا الترتيب ليس اعتباطيًا، فمعيار UBL يفرض أن تأتي الامتدادات أولًا.
بعدها تمرّ على حقول الترويسة بترتيبها: رقم الفاتورة، فالمعرّف الفريد، فالتاريخ والوقت، فراية نوع الفاتورة، فالعملة. ثم العداد والتجزئة. كل حقل في موضعه المحدّد، ولا يجوز تقديم أحدها على الآخر. ثم تنتقل إلى البائع فالمشتري، ثم البنود، ثم الإجماليات. هذا المسار هو نفسه الذي يسلكه نظام التحقق حين يقرأ ملفك.
الفائدة من هذا التمرين أنك تكتسب حدسًا بمكان الخطأ قبل أن يخبرك المحقّق. لو رأيت كتلة بنود قبل كتلة المشتري، عرفت فورًا أن الترتيب مكسور. ولو رأيت رقمًا ضريبيًا لا يبدأ بالرقم 3، توقّعت رفضًا في الهوية. القراءة المتأنية مرة واحدة توفّر عليك جولات تصحيح كثيرة لاحقًا. اطبع النموذج، وأشّر بقلمك على كل كتلة، واربطها بالشرح المقابل في هذه الصفحة.
قبل أن ترسل: مرّ النموذج على التحقق
النموذج صالح بنيويًا، لكن صلاحية البنية شيء واجتياز قواعد العمل شيء آخر. قبل أن ترسل أي فاتورة إلى الإنتاج، مرّرها على بيئة المحاكاة (Sandbox) وعلى قواعد التحقق التي تطبّقها الهيئة. لتفصيل هذه القواعد راجع قواعد التحقق (Validation Rules) للفاتورة.
أكثر الأخطاء التي تظهر في التحقق ثلاثة. الأول حسابي: تباين بين مجموع البنود وكتلة الإجماليات بسبب تقريب. الثاني في الهوية: رقم تسجيل ضريبي لا يطابق الصيغة المطلوبة أو لا يبدأ وينتهي بالرقم 3. الثالث في الترتيب: كتلة موضوعة في غير موضعها داخل الشجرة، مثل وضع البنود قبل الأطراف.
القاعدة العملية: لا تختبر مباشرة على الإنتاج. ابدأ ببيئة المحاكاة بشهادة تجريبية، وأصلح كل ملاحظة، ثم انتقل للإنتاج بشهادة CSID الفعلية. هذا يحميك من تراكم فواتير مرفوضة في سجلّك الرسمي.
ابنِ خطوة التحقق جزءًا ثابتًا من تكاملك، لا خطوة تختبرها مرة وتنساها. اجعل نظامك يتحقق من كل فاتورة محليًا قبل إرسالها، ويسجّل سبب أي رفض بوضوح. كثير من الفرق تكتشف أن خطأً واحدًا في التقريب أو في صيغة رقم التسجيل يتكرر في مئات الفواتير لأنه لم يُرصد مبكرًا. حلقة تحقق قصيرة عند كل إصدار أرخص بكثير من تصحيح دفعة كاملة بعد رفضها.
الفرق بين هذه الصفحة وصفحات البنية والتنسيق
قد تتساءل متى تستخدم هذه الصفحة ومتى تستخدم صفحات الشرح. الفرق في الغرض. هذه الصفحة عملية: تنسخ النموذج وتعدّله وتجرّبه. صفحة فاتورة XML: التنسيق التقني مرجعية: تشرح ما هو الملف وكيف يُقرأ. وصفحة بنية الفاتورة الإلكترونية تحليلية: تفكّك المستند إلى أقسامه الثلاثة وتشرح كيف تتداخل.
الترتيب الموصى به: اقرأ صفحة البنية أولًا لتفهم الأقسام، ثم صفحة التنسيق لتفهم القواعد، ثم عُد إلى هذه الصفحة لتأخذ النموذج الجاهز وتطبّق ما فهمته. ثلاث صفحات تكمّل بعضها، كل واحدة تخدم لحظة مختلفة في رحلتك.
وإذا أردت التأكد من أن ملفك يطابق المخطط الرسمي قبل أي شيء، فصفحة مخطط الفاتورة (Invoice Schema) والتحقق منه تشرح كيف يتحقق النظام من الملف مقابل المخطط المعتمد.
كيف يتولّى قيود توليد ملف XML نيابةً عنك
كل ما شرحناه في هذه الصفحة يحدث في قيود تلقائيًا. عندما تنشئ فاتورة في قيود، يبني النظام ملف UBL 2.1 بكل كتله: الترويسة والأطراف والبنود والإجماليات، ويحسب العداد ICV والتجزئة PIH، ويرتّب العناصر في الشجرة الصحيحة، ويوقّع الفاتورة ويختمها عبر منصة فاتورة، ويتحقق منها قبل الإرسال.
هذا يعني أنك لا تكتب سطر XML واحدًا في التشغيل اليومي. تكتب بيانات الفاتورة في واجهة بسيطة، وقيود يحوّلها إلى ملف متوافق مع المرحلة الثانية. النموذج في هذه الصفحة يفيدك إن كنت تبني تكاملًا خاصًا أو تختبر، لكن في الاستخدام العادي قيود يكفيك العبء التقني كله.
قيود متوافق مع المرحلة الثانية من الفاتورة الإلكترونية، ويدير شهادة CSID آليًا، ويخزّن سلسلة التجزئة للتحقق، ويوفّر دعمًا فنيًا على مدار 24 ساعة طوال أيام الأسبوع. هكذا تركّز على عملك، ويتولّى النظام الامتثال التقني نيابةً عنك.
الأسئلة الشائعة
هل النموذج في هذه الصفحة جاهز للإرسال إلى الإنتاج مباشرة؟
لا. النموذج صالح بنيويًا وجاهز للنسخ والتعديل، لكنه يحمل بيانات توضيحية وقيم ختم مختصرة. استبدل بيانات البائع والمشتري والبنود ببياناتك الفعلية، ثم مرّره على بيئة المحاكاة وقواعد التحقق، ودع نظامك يولّد التوقيع والختم قبل الإرسال.
لماذا قيمة الختم التشفيري ورمز QR مختصرة في النموذج؟
لأن هذه القيم تُحسب آليًا على محتوى الفاتورة نفسها وقت الإصدار باستخدام شهادة CSID. لا تُكتب يدويًا ولا تُنسخ من فاتورة أخرى. النموذج يبيّن موضعها في الملف فقط، وقيمتها النهائية يولّدها النظام.
ما الفرق الجوهري بين النموذج المعياري والمبسّط؟
المعياري موجّه من منشأة إلى منشأة، يحمل الرقم الضريبي للطرفين، ويخضع للمقاصة قبل التسليم. المبسّط موجّه للأفراد، لا يلزم فيه الرقم الضريبي للمشتري، ويُسلَّم فورًا ثم يُبلَّغ خلال 24 ساعة. التغيير في الملف يبدأ من راية نوع الفاتورة في الترويسة.
هل يجب أن أكتب الأسماء بالعربية داخل الملف؟
نعم، اكتب اسم المنشأة واسم الصنف بالعربية كما هي مسجّلة لدى الهيئة. ولهذا يجب أن يبقى ترميز الملف UTF-8، فهو الترميز الذي يحمل الحروف العربية دون تلف.
ماذا أفعل إذا رفض التحقق فاتورتي بسبب تباين بريال واحد؟
هذا خطأ تقريب. تأكد أنك تحسب الضريبة بطريقة موحّدة، إما على مستوى كل بند ثم تجمع، أو على مستوى الفاتورة كاملة، دون خلط. وتأكد أن مجموع صافي البنود يساوي الإجمالي قبل الضريبة في كتلة الإجماليات.
هل أحتاج إلى كتابة XML يدويًا إذا استخدمت قيود؟
لا. في الاستخدام اليومي تكتب بيانات الفاتورة في واجهة قيود، والنظام يبني الملف ويوقّعه ويتحقق منه ويرسله. هذا النموذج مفيد للمطوّرين الذين يبنون تكاملًا خاصًا أو يختبرون، لا للتشغيل اليومي.
