أدوات MCP

الفواتير والفوترة الإلكترونية

أدوات MCP للفواتير الضريبية وإشعارات الدائن والمدين مع هيئة الزكاة والضريبة والجمارك، وسجل النشاط والأرشيف والتحقق من السلسلة.

الفاتورة هنا مستند ضريبي يصدر وفق قواعد الفوترة الإلكترونية لدى هيئة الزكاة والضريبة والجمارك (ZATCA): فاتورة ضريبية أو إشعار دائن أو إشعار مدين. يبدأ مسودة تعدلها وتحذفها كما تشاء، ثم يصدر فيأخذ رقمه المتسلسل وختمه ورمز الاستجابة السريعة ويرسل إلى الهيئة. وبعد ذلك لا يعدل، والتصحيح يكون بإشعار دائن أو مدين يشير إليه. وتجد شرح الميزة كاملا في الفواتير الإلكترونية.

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

ملاحظة:قبل أن تصبح وحدة الفوترة فعالة تصدر الفواتير بوضع المرحلة الأولى: رقم متسلسل ورمز استجابة سريعة من خمسة حقول، دون إرسال إلى الهيئة، وتبقى zatca_status عندها none. وتعد الوحدة مرة واحدة من التطبيق في الإعدادات ← ZATCA. وتتوقف الفوترة هنا عند المستند نفسه: لا مدفوعات ولا تواريخ استحقاق ولا ذمم مدينة، ويستلم برنامجك المحاسبي الفاتورة الصادرة من هنا بصيغة PDF أو XML.

الأداة	ما تفعله
invoices_list	عرض الفواتير
invoices_get	عرض فاتورة
invoices_create	إنشاء مسودة فاتورة
invoices_update	تعديل مسودة فاتورة
invoices_delete	حذف مسودة فاتورة
invoices_issue	إصدار فاتورة
invoices_submit	إعادة إرسال فاتورة إلى الهيئة
invoice_pdf	تنزيل ملف PDF للفاتورة
invoice_xml	تنزيل ملف XML للفاتورة
invoice_archive_zip	تنزيل أرشيف XML للفواتير
invoice_events_list	عرض سجل نشاط الفواتير
zatca_chain_verify	التحقق من سلسلة الفواتير وسجل النشاط

قراءة الفواتير

invoices_list

يعرض فواتير مؤسستك وإشعاراتها الدائنة والمدينة، الأحدث أولا. رشح النتائج بالمرحلة أو بنتيجة الهيئة أو بنوع المستند أو بأمر البيع المرتبط به أو بالفاتورة التي يصححها إشعار، أو ابحث بنص حر.

للقراءة فقط · الصلاحية invoices.read · الأدوار: المالك، المدير، المبيعات، المشتريات، المشاهد · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`status`	`string`	لا	المسودات فقط (`draft`) أو المستندات الصادرة فقط (`issued`).
`zatca_status`	`string`	لا	المستندات التي لها هذه النتيجة لدى الهيئة: `none` (لا نتيجة بعد، أي مسودة أو فاتورة صدرت دون وحدة فعالة)، و`pending` (تعذر الوصول إلى الهيئة)، و`cleared` (معتمدة)، و`reported` (مبلغ عنها)، و`rejected` (مرفوضة).
`document_type`	`string`	لا	نوع المستند: `invoice` فاتورة ضريبية، أو `credit_note` إشعار دائن، أو `debit_note` إشعار مدين.
`transaction_type`	`string`	لا	نوع الفاتورة: `standard` ضريبية بين منشآت، أو `simplified` مبسطة للمستهلك.
`sales_order_id`	`integer`	لا	المستندات الخاصة بأمر البيع هذا فقط. ويأتي معرفه من `sales_orders_list`.
`original_invoice_id`	`integer`	لا	الإشعارات الدائنة والمدينة التي تصحح هذه الفاتورة فقط.
`q`	`string`	لا	كلمة أو رقم يبحث عنه في رقم الفاتورة واسم العميل والرقم الضريبي للمشتري، حتى 200 حرف.
`page`	`integer`	لا	رقم الصفحة، ويبدأ من 1.
`page_size`	`integer`	لا	عدد النتائج في الصفحة: 20 افتراضيا، وحده الأقصى 100.

{
  "status": "issued",
  "zatca_status": "rejected",
  "page_size": 50
}

مثال على المعاملات

ما يعيده: صفحة من الفواتير، لكل منها الرقم والمعرف الفريد (UUID) والنوع والمرحلة ونتيجة الهيئة واسم المشتري والمجاميع وأمر البيع والمنافسة المرتبطان به، مع العدد الكلي.

المسودات تحمل zatca_status بقيمة none أيضا. أضف status: issued لتجد الفواتير التي صدرت دون وحدة فعالة فقط.

invoices_get

يعيد فاتورة واحدة كاملة: الترويسة والبنود والمشتري والمجاميع ونتيجة الهيئة ورسائلها ورمز الاستجابة السريعة، مع أمر البيع وعرض السعر والمنافسة المرتبطة بها والإشعارات التي تصححها. وللمسودة يعدد ما ينقصها قبل الإصدار.

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.

ما يعيده: كائن فيه invoice وitems وreadiness_issues وqr_image (صورة PNG بصيغة data URI، وتكون فارغة في المسودة) وsales_order وquotation وtender وoriginal_invoice وcorrections (الإشعارات التي تصححها) وegs (بيئة الوحدة وحالتها) وevents (أحدث 50 سطرا من سجل نشاط الفاتورة).

readiness_issues قائمة رموز لما ينقص المسودة، وتكون فارغة بعد الإصدار. الرموز التي تبدأ بـseller_ تخص سجل المؤسسة في الإعدادات ولا تصلح على الفاتورة. وبقية الرموز تسمي حقلا ناقصا في المشتري أو البنود أو الإشعار، مثل buyer_identity وsupply_date وoriginal_invoice وline_exemption_reason.
رسائل الهيئة عند الرفض في invoice.zatca_error وinvoice.zatca_response. أما ملفا XML الموقع والمعتمد فلا يردان هنا، وتنزلهما بـinvoice_xml.

المسودات

المسودة بلا رقم ولا بصمة ولا ملف XML. احفظها ناقصة إن شئت، فلا يفحص شيء وفق متطلبات الهيئة حتى الإصدار، ويعرض invoices_get ما ينقصها.

invoices_create

يحفظ فاتورة ضريبية أو إشعارا دائنا أو مدينا مسودة ببند واحد على الأقل. لا يرقم شيء ولا يوقع ولا يرسل حتى تصدر المسودة. اذكر ملف عميل ليملأ اسم المشتري ومعرفه وعنوانه، وأرسل أي حقل تريد أن يغلب ما في الملف.

يغير البيانات · الصلاحية invoices.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`customer_id`	`integer`	لا	ملف عميل تبدأ منه، ويأتي معرفه من `customers_list`. يملأ منه كل حقل مشتر لم ترسله بحسب المعاملة الضريبية للعميل، وما ترسله أنت يغلب ما في الملف. أرسل `null` إن لم تستخدم ملفا.
`customer_name`	`string`	لا	اسم المشتري كما يطبع، من 1 إلى 200 حرف. مطلوب إلا إذا أرسلت `customer_id`، وإن أرسلتهما معا اعتمد هذا الاسم.
`document_type`	`string`	لا	نوع المستند: `invoice` فاتورة ضريبية (الافتراضي)، أو `credit_note` إشعار دائن، أو `debit_note` إشعار مدين.
`transaction_type`	`string`	لا	نوع الفاتورة: `standard` ضريبية بين منشآت وتعتمدها الهيئة قبل أن تصل إلى المشتري (الافتراضي)، أو `simplified` مبسطة للمستهلك ويبلغ عنها. وإشعار حددت فاتورته الأصلية يأخذ نوع تلك الفاتورة إن لم ترسل النوع.
`original_invoice_id`	`integer`	لا	في الإشعار الدائن أو المدين: الفاتورة الضريبية الصادرة التي يصححها. يلزم للإصدار، ويمكن تركه والمستند مسودة. ويجب أن تكون فاتورة ضريبية صادرة من مؤسستك، لا مسودة ولا إشعارا آخر. ويهمل في `invoice`. أرسل `null` لمسحه.
`reason`	`string`	لا	في الإشعار الدائن أو المدين: سبب إصداره، حتى 500 حرف. يلزم للإصدار. أرسل `null` لمسحه.
`buyer_vat_number`	`string`	لا	الرقم الضريبي للمشتري في المملكة: 15 رقما يبدأ وينتهي بالرقم 3. والرقم بصيغة خاطئة يمنع الإصدار. أرسل `null` لمسحه.
`buyer_id_scheme`	`string`	لا	نوع المعرف الآخر للمشتري الذي لا رقم ضريبي له: `CRN` السجل التجاري، `MOM` رخصة وزارة الشؤون البلدية والقروية والإسكان، `MLS` رخصة وزارة الموارد البشرية والتنمية الاجتماعية، `700` الرقم الموحد 700، `SAG` رخصة وزارة الاستثمار، `NAT` الهوية الوطنية، `GCC` هوية مواطن خليجي، `IQA` الإقامة، `PAS` جواز السفر، `OTH` معرف آخر. ترسله مع `buyer_id_value`. أرسل `null` لمسحه.
`buyer_id_value`	`string`	لا	قيمة المعرف الآخر، مثل رقم السجل التجاري، حتى 50 حرفا. تلزم مع `buyer_id_scheme` في الفاتورة الضريبية لمشتر بلا رقم ضريبي. أرسل `null` لمسحها.
`buyer_street_name`	`string`	لا	الشارع في العنوان الوطني للمشتري، حتى 200 حرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_building_number`	`string`	لا	رقم المبنى، حتى 10 أحرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_district`	`string`	لا	الحي، حتى 100 حرف. أرسل `null` لمسحه.
`buyer_city`	`string`	لا	المدينة، حتى 100 حرف. تلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحها.
`buyer_postal_code`	`string`	لا	الرمز البريدي، حتى 10 أحرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_additional_number`	`string`	لا	الرقم الإضافي للعنوان الوطني، حتى 10 أحرف. أرسل `null` لمسحه.
`buyer_country_code`	`string`	لا	رمز دولة المشتري من حرفين وفق ISO 3166-1. الافتراضي `SA`.
`sales_order_id`	`integer`	لا	أمر البيع الذي تخصه الفاتورة، ويأتي من `sales_orders_list`. ويجب أن يكون من أوامر مؤسستك. أرسل `null` لفك الارتباط.
`quotation_id`	`integer`	لا	عرض السعر الذي نشأ منه البيع، ويأتي من `quotations_list`. ويجب أن يكون من عروض مؤسستك. أرسل `null` لفك الارتباط.
`tender_id`	`integer`	لا	المنافسة المرتبطة بالبيع للرجوع إليها، وتأتي من `tenders_list`. أرسل `null` لفك الارتباط.
`currency`	`string`	لا	رمز العملة من ثلاثة أحرف وفق ISO 4217. الافتراضي `SAR`.
`supply_date`	`string`	لا	تاريخ التوريد بصيغة `YYYY-MM-DD`. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`payment_means_code`	`string`	لا	طريقة الدفع برمز UNTDID 4461: `10` نقدا، و`30` تحويل مصرفي (الافتراضي)، و`42` حساب مصرفي، و`48` بطاقة، و`1` غير محددة. تطبع على المستند، ولا تسجل بها دفعة.
`notes`	`string`	لا	ملاحظات حرة على الفاتورة، حتى 2000 حرف. أرسل `null` لمسحها.
`items`	`object[]`	نعم	بنود الفاتورة، من 1 إلى 500 بند. وتوصف حقول كل بند أدناه بالصيغة `items[].…`.
`items[].product_id`	`integer`	لا	منتج من الكتالوج يخصه هذا البند، ويأتي من `products_list`. ويجب أن يكون من منتجات مؤسستك.
`items[].sales_order_item_id`	`integer`	لا	بند أمر البيع الذي يخصه هذا البند من الفاتورة.
`items[].description`	`string`	نعم	وصف ما تتضمنه الفاتورة في هذا البند، من 1 إلى 1000 حرف.
`items[].quantity`	`number`	نعم	الكمية، وهي أكبر من صفر.
`items[].unit_code`	`string`	لا	وحدة القياس برمز التوصية 20 من UN/ECE، حتى 10 أحرف. الافتراضي `PCE` (قطعة)، ومنها `BX` (علبة) و`PK` (عبوة) و`KGM` (كيلوغرام).
`items[].unit_price`	`number`	نعم	سعر الوحدة قبل الضريبة بالعملة المحددة للفاتورة، صفر أو أكثر، وحتى أربع منازل عشرية.
`items[].discount_amount`	`number`	لا	خصم بالمبلغ لا بالنسبة على هذا البند، صفر أو أكثر. وإن زاد على إجمالي البند قبل الخصم خفض إلى هذا الإجمالي.
`items[].vat_category`	`string`	لا	فئة الضريبة: `S` خاضع للنسبة الأساسية (الافتراضي)، و`Z` بنسبة الصفر، و`E` معفى، و`O` خارج النطاق.
`items[].vat_rate`	`number`	لا	نسبة الضريبة بنسبة مئوية صحيحة من 0 إلى 100. الافتراضي 15 للفئة `S` و0 لغيرها. وللإصدار يلزم أن تكون النسبة فوق صفر في بند `S` وصفرا في بند `Z` أو `E` أو `O`.
`items[].vat_exemption_code`	`string`	لا	رمز سبب الإعفاء لدى الهيئة لبند `Z` أو `E` أو `O`، حتى 30 حرفا، مثل `VATEX-SA-35` للأدوية والمعدات الطبية. ويلزم للإصدار في هذه البنود، ويهمل في بند `S`. أرسل `null` لمسحه.
`items[].vat_exemption_reason`	`string`	لا	نص سبب الإعفاء، حتى 500 حرف. وإن لم ترسله أخذته المنصة من الرمز متى كان الرمز في قائمة الهيئة. أرسل `null` لمسحه.

{
  "customer_id": 214,
  "transaction_type": "standard",
  "sales_order_id": 87,
  "supply_date": "2026-10-04",
  "payment_means_code": "30",
  "items": [
    {
      "description": "Disposable syringe 5 ml, box of 100",
      "quantity": 40,
      "unit_code": "BX",
      "unit_price": 38.5,
      "vat_category": "Z",
      "vat_exemption_code": "VATEX-SA-35"
    },
    {
      "description": "Delivery to Riyadh warehouse",
      "quantity": 1,
      "unit_price": 150
    }
  ]
}

مثال على المعاملات

ما يعيده: معرف المسودة الجديدة في invoice_id. اقرأها بـinvoices_get.

تحسب المجاميع لكل بند وتقرب إلى أقرب هللة: الصافي هو الكمية في سعر الوحدة ناقص الخصم، والضريبة بنسبة البند، ومجاميع الفاتورة هي مجاميع بنودها.
الفاتورة الضريبية تحتاج قبل الإصدار إلى الرقم الضريبي للمشتري أو معرف آخر، وإلى الشارع ورقم المبنى والمدينة والرمز البريدي، وإلى تاريخ التوريد. والمبسطة تكفيها تسمية العميل. وبند الدواء المعفى بنسبة الصفر فئته Z ورمز إعفائه VATEX-SA-35.
يرد 404 إذا لم تجد في مؤسستك العميل أو أمر البيع أو عرض السعر أو المنتج أو الفاتورة الأصلية التي ذكرتها، أو لم تكن المنافسة متاحة لك. ويرد 400 إذا لم تكن الفاتورة الأصلية للإشعار فاتورة ضريبية صادرة.

invoices_update

يعدل مسودة. لا يتغير إلا ما ترسله، وnull يمسح حقلا يقبل الفراغ، وإرسال items يستبدل كل البنود. ولا تعدل فاتورة صدرت، فأصدر إشعارا دائنا أو مدينا يشير إليها.

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.
`customer_id`	`integer`	لا	ملف عميل يرتبط به المستند، ويأتي معرفه من `customers_list`. لا يعيد ملء حقول المشتري، فأرسل الحقول التي تريد تغييرها. أرسل `null` لفك الارتباط.
`customer_name`	`string`	لا	اسم المشتري، من 1 إلى 200 حرف.
`document_type`	`string`	لا	نوع المستند: `invoice` أو `credit_note` أو `debit_note`. والعودة إلى `invoice` تمسح الفاتورة الأصلية والسبب.
`transaction_type`	`string`	لا	نوع الفاتورة: `standard` ضريبية بين منشآت، أو `simplified` مبسطة للمستهلك.
`original_invoice_id`	`integer`	لا	في الإشعار الدائن أو المدين: الفاتورة الضريبية الصادرة التي يصححها. يلزم للإصدار، ويمكن تركه والمستند مسودة. ويجب أن تكون فاتورة ضريبية صادرة من مؤسستك، لا مسودة ولا إشعارا آخر. ويهمل في `invoice`. أرسل `null` لمسحه.
`reason`	`string`	لا	في الإشعار الدائن أو المدين: سبب إصداره، حتى 500 حرف. يلزم للإصدار. أرسل `null` لمسحه.
`buyer_vat_number`	`string`	لا	الرقم الضريبي للمشتري في المملكة: 15 رقما يبدأ وينتهي بالرقم 3. والرقم بصيغة خاطئة يمنع الإصدار. أرسل `null` لمسحه.
`buyer_id_scheme`	`string`	لا	نوع المعرف الآخر للمشتري الذي لا رقم ضريبي له: `CRN` السجل التجاري، `MOM` رخصة وزارة الشؤون البلدية والقروية والإسكان، `MLS` رخصة وزارة الموارد البشرية والتنمية الاجتماعية، `700` الرقم الموحد 700، `SAG` رخصة وزارة الاستثمار، `NAT` الهوية الوطنية، `GCC` هوية مواطن خليجي، `IQA` الإقامة، `PAS` جواز السفر، `OTH` معرف آخر. ترسله مع `buyer_id_value`. أرسل `null` لمسحه.
`buyer_id_value`	`string`	لا	قيمة المعرف الآخر، مثل رقم السجل التجاري، حتى 50 حرفا. تلزم مع `buyer_id_scheme` في الفاتورة الضريبية لمشتر بلا رقم ضريبي. أرسل `null` لمسحها.
`buyer_street_name`	`string`	لا	الشارع في العنوان الوطني للمشتري، حتى 200 حرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_building_number`	`string`	لا	رقم المبنى، حتى 10 أحرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_district`	`string`	لا	الحي، حتى 100 حرف. أرسل `null` لمسحه.
`buyer_city`	`string`	لا	المدينة، حتى 100 حرف. تلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحها.
`buyer_postal_code`	`string`	لا	الرمز البريدي، حتى 10 أحرف. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`buyer_additional_number`	`string`	لا	الرقم الإضافي للعنوان الوطني، حتى 10 أحرف. أرسل `null` لمسحه.
`buyer_country_code`	`string`	لا	رمز دولة المشتري من حرفين وفق ISO 3166-1. الافتراضي `SA`.
`sales_order_id`	`integer`	لا	أمر البيع الذي تخصه الفاتورة، ويأتي من `sales_orders_list`. ويجب أن يكون من أوامر مؤسستك. أرسل `null` لفك الارتباط.
`quotation_id`	`integer`	لا	عرض السعر الذي نشأ منه البيع، ويأتي من `quotations_list`. ويجب أن يكون من عروض مؤسستك. أرسل `null` لفك الارتباط.
`tender_id`	`integer`	لا	المنافسة المرتبطة بالبيع للرجوع إليها، وتأتي من `tenders_list`. أرسل `null` لفك الارتباط.
`currency`	`string`	لا	رمز العملة من ثلاثة أحرف وفق ISO 4217. الافتراضي `SAR`.
`supply_date`	`string`	لا	تاريخ التوريد بصيغة `YYYY-MM-DD`. يلزم لإصدار الفاتورة الضريبية. أرسل `null` لمسحه.
`payment_means_code`	`string`	لا	طريقة الدفع برمز UNTDID 4461: `10` نقدا، و`30` تحويل مصرفي (الافتراضي)، و`42` حساب مصرفي، و`48` بطاقة، و`1` غير محددة. تطبع على المستند، ولا تسجل بها دفعة.
`notes`	`string`	لا	ملاحظات حرة على الفاتورة، حتى 2000 حرف. أرسل `null` لمسحها.
`items`	`object[]`	لا	إن أرسلتها استبدلت كل البنود الحالية بهذه القائمة (من 1 إلى 500) وحسبت المجاميع من جديد. أما إن حذفتها فتبقى البنود كما هي.
`items[].product_id`	`integer`	لا	منتج من الكتالوج يخصه هذا البند، ويأتي من `products_list`. ويجب أن يكون من منتجات مؤسستك.
`items[].sales_order_item_id`	`integer`	لا	بند أمر البيع الذي يخصه هذا البند من الفاتورة.
`items[].description`	`string`	نعم	وصف ما تتضمنه الفاتورة في هذا البند، من 1 إلى 1000 حرف.
`items[].quantity`	`number`	نعم	الكمية، وهي أكبر من صفر.
`items[].unit_code`	`string`	لا	وحدة القياس برمز التوصية 20 من UN/ECE، حتى 10 أحرف. الافتراضي `PCE` (قطعة)، ومنها `BX` (علبة) و`PK` (عبوة) و`KGM` (كيلوغرام).
`items[].unit_price`	`number`	نعم	سعر الوحدة قبل الضريبة بالعملة المحددة للفاتورة، صفر أو أكثر، وحتى أربع منازل عشرية.
`items[].discount_amount`	`number`	لا	خصم بالمبلغ لا بالنسبة على هذا البند، صفر أو أكثر. وإن زاد على إجمالي البند قبل الخصم خفض إلى هذا الإجمالي.
`items[].vat_category`	`string`	لا	فئة الضريبة: `S` خاضع للنسبة الأساسية (الافتراضي)، و`Z` بنسبة الصفر، و`E` معفى، و`O` خارج النطاق.
`items[].vat_rate`	`number`	لا	نسبة الضريبة بنسبة مئوية صحيحة من 0 إلى 100. الافتراضي 15 للفئة `S` و0 لغيرها. وللإصدار يلزم أن تكون النسبة فوق صفر في بند `S` وصفرا في بند `Z` أو `E` أو `O`.
`items[].vat_exemption_code`	`string`	لا	رمز سبب الإعفاء لدى الهيئة لبند `Z` أو `E` أو `O`، حتى 30 حرفا، مثل `VATEX-SA-35` للأدوية والمعدات الطبية. ويلزم للإصدار في هذه البنود، ويهمل في بند `S`. أرسل `null` لمسحه.
`items[].vat_exemption_reason`	`string`	لا	نص سبب الإعفاء، حتى 500 حرف. وإن لم ترسله أخذته المنصة من الرمز متى كان الرمز في قائمة الهيئة. أرسل `null` لمسحه.

{
  "id": 311,
  "supply_date": "2026-10-05",
  "buyer_vat_number": "300012345600003"
}

مثال على المعاملات

ما يعيده: معرف المسودة في invoice_id.

الفاتورة الصادرة ترد بالخطأ 409 مهما أرسلت، ويرد 404 إذا لم توجد الفاتورة في مؤسستك.
إرسال items يحذف البنود الحالية ويحل محلها، فأرسل القائمة كاملة لا البنود المتغيرة وحدها.

invoices_delete

يحذف مسودة. أما الفاتورة الصادرة فسجل ضريبي لا يحذف. ويبقى الحذف مسجلا في سجل النشاط.

يحذف بيانات أو يستبدلها · الصلاحية invoices.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.

ما يعيده: تأكيد الحذف (ok: true).

الفاتورة الصادرة ترد بالخطأ 409. وصحح الفاتورة الصادرة بإشعار دائن أو مدين.

الإصدار والإرسال إلى الهيئة

الإصدار هو الخطوة الوحيدة التي لا رجعة فيها، ولا يقوم بها إلا المدير أو المالك.

invoices_issue

يصدر مسودة: يمنحها رقمها المتسلسل وتاريخ ووقت الإصدار بتوقيت الرياض، ثم يبني ملف XML ويختمه ويضيف رمز الاستجابة السريعة، ويجمد المستند ويرسله إلى الهيئة: اعتمادا للفاتورة الضريبية وإبلاغا للمبسطة. ولا رجعة فيه.

يغير البيانات · الصلاحية invoices.write · الأدوار: المالك، المدير · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.

ما يعيده: invoice_id وinvoice_number وsigned (تكون false إذا صدرت الفاتورة دون وحدة فعالة) وzatca_status (cleared أو reported أو rejected أو pending أو none) وzatca_has_warnings وzatca_error (رسائل الهيئة عند الرفض).

المسودة التي ينقصها ما تشترطه الهيئة ترد بالخطأ 400 مع issues، وهي قائمة رموز الحقول، وتبقى مسودة ولا يستهلك لها رقم. فاقرأ readiness_issues من invoices_get قبل الإصدار.
إذا لم تكن لمؤسستك وحدة فوترة فعالة صدرت الفاتورة برمز استجابة سريعة من خمسة حقول وzatca_status بقيمة none، ولا يمكن إرسالها إلى الهيئة بعد ذلك. أعد الوحدة أولا إذا وجب أن تصل الفاتورة إلى الهيئة.
pending تعني تعذر الوصول إلى الهيئة: الفاتورة صادرة وموقعة، ويعيد invoices_submit إرسال الملف نفسه. والفاتورة rejected تحتفظ برقمها، وإن كان سبب الرفض في جانب الوحدة وأصلح جاز إرسالها مرة أخرى.
يرد 409 إذا كانت الفاتورة صادرة سلفا، وإذا كانت فاتورة أخرى لمؤسستك تصدر في اللحظة نفسها (أعد المحاولة بعد قليل).

invoices_submit

يرسل فاتورة صادرة إلى الهيئة مرة أخرى بالملف الموقع المحفوظ نفسه، فلا تتغير بصمتها. استخدمه لفاتورة بقيت pending بسبب انقطاع الاتصال، أو rejected لسبب في جانب الوحدة وأصلح.

يغير البيانات · الصلاحية invoices.write · الأدوار: المالك، المدير · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.

ما يعيده: invoice_id وinvoice_number وsigned وzatca_status وzatca_has_warnings وzatca_error، بالمعنى نفسه كما في invoices_issue.

يرد 409 للمسودة، وللفاتورة التي صدرت دون وحدة فعالة لأنها بلا ختم، وللفاتورة التي قبلتها الهيئة (cleared أو reported)، وإذا لم تعد الوحدة التي ختمتها فعالة.

الملفات والأرشيف

invoice_pdf

يطبع الفاتورة بصيغة PDF بالعربية والإنجليزية، مع رمز الاستجابة السريعة وجدول الضريبة. وتطبع المسودة معاينة بعلامة مائية ودون رمز استجابة.

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.

ما يعيده: ملف PDF فيه filename وcontent_type وsize_bytes والمحتوى بترميز base64 في base64.

الملف الذي يتجاوز 4 ميغابايت لا يضمن في الرد، فترد الأداة بخطأ يسمي نقطة REST التي تنزله منها. ويسجل كل تنزيل في سجل النشاط.

invoice_xml

يعيد ملف XML الموقع للفاتورة الصادرة، وهو الملف نفسه الذي استلمته الهيئة (بصيغة UBL 2.1). ومع cleared: true يعيد النسخة التي ختمتها الهيئة عند الاعتماد.

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الفاتورة، ويأتي من `invoices_list`.
`cleared`	`boolean`	لا	اجعله `true` لتأخذ النسخة التي ختمتها الهيئة عند الاعتماد بدل المرسلة. وهي لا توجد إلا للفاتورة الضريبية المعتمدة. الافتراضي `false`.

ما يعيده: ملف XML فيه filename وcontent_type وsize_bytes والمحتوى بترميز base64 في base64.

المسودة بلا XML فترد بالخطأ 404، وكذلك طلب cleared: true لفاتورة لم تعد الهيئة نسخة معتمدة منها.

invoice_archive_zip

يجمع ملفات XML الموقعة لكل فاتورة وإشعار دائن ومدين صادر في ملف ZIP واحد، لأرشيفك أو لمدقق. وتسمى الملفات بالصيغة التي تطلب الهيئة حفظها بها، ويسرد الملف manifest.json ما في الأرشيف.

للقراءة فقط · الصلاحية invoices.read · الأدوار: المالك، المدير · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`from`	`string`	لا	أول تاريخ إصدار يدخل في الأرشيف، بصيغة `YYYY-MM-DD`.
`to`	`string`	لا	آخر تاريخ إصدار يدخل في الأرشيف، بصيغة `YYYY-MM-DD`، ويدخل في الأرشيف. ولا يسبقه `from`.

ما يعيده: ملف ZIP فيه filename وcontent_type وsize_bytes والمحتوى بترميز base64 في base64. لكل مستند ملف باسم <الرقم الضريبي>_<تاريخ الإصدار>T<وقت الإصدار>_<رقم الفاتورة>.xml، ومعه نسخة الهيئة المعتمدة بلاحقة .cleared.xml إن وجدت، إضافة إلى manifest.json بالأرقام والمعرفات والعدادات والبصمات.

فترة فيها أكثر من 5000 مستند ترد بالخطأ 413، فضيقها بـfrom وto. وفترة بلا فواتير صادرة ترد بالخطأ 404.
الأرشيف الذي يتجاوز 4 ميغابايت لا يضمن في الرد، فترد الأداة بخطأ يسمي نقطة REST التي تنزله منها. ويسجل كل تصدير في سجل النشاط.

سجل النشاط والتحقق

تكتب المنصة سجل النشاط بنفسها ولا يعدل أحد سطرا فيه ولا يحذفه، وكل سطر مربوط بالسطر السابق ببصمة. وللتحقق أداة تفحص السجلات كلها.

invoice_events_list

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

المعامل	النوع	مطلوب	الوصف
`invoice_id`	`integer`	لا	الأسطر الخاصة بهذه الفاتورة فقط.
`event`	`string`	لا	حدث واحد فقط، وهو أحد: `invoice.created` و`invoice.updated` و`invoice.deleted` و`invoice.issued` و`invoice.submitted` و`invoice.pdf_downloaded` و`invoice.xml_downloaded` و`invoices.archived` و`chain.verified` و`unit.created` و`unit.compliance_csid` و`unit.compliance_checks` و`unit.production_csid` و`unit.renewed` و`unit.reset`.
`scope`	`string`	لا	`all` للكل (الافتراضي)، أو `invoice` للأسطر الخاصة بمستند، أو `unit` للأسطر الخاصة بالوحدة وتصدير الأرشيف والتحقق.
`from`	`string`	لا	بداية الفترة وهي داخلة فيها، بتاريخ أو بوقت ISO. والتاريخ وحده يعني بداية ذلك اليوم بالتوقيت العالمي.
`to`	`string`	لا	نهاية الفترة وهي غير داخلة فيها، بتاريخ أو بوقت ISO.
`page`	`integer`	لا	رقم الصفحة، ويبدأ من 1.
`page_size`	`integer`	لا	عدد الأسطر في الصفحة: 50 افتراضيا، وحده الأقصى 100.

{
  "scope": "invoice",
  "event": "invoice.issued",
  "from": "2026-10-01",
  "page_size": 25
}

مثال على المعاملات

ما يعيده: صفحة من الأسطر، لكل سطر id وinvoice_id وinvoice_number وevent وactor_email وchannel (app أو api أو system) وdetail وcreated_at وprev_hash وentry_hash، مع العدد الكلي.

القناة app هي تطبيق الويب، وapi هي أي استدعاء عبر واجهة API أو MCP أو المساعد باسم عضو، وsystem هي المنصة حين تعمل من تلقاء نفسها.
السطر الذي لا يحمل invoice_id يخص الوحدة أو تصدير الأرشيف أو التحقق.

zatca_chain_verify

يثبت سلامة سجلات الفوترة الإلكترونية. يعيد حساب بصمة كل مستند صادر من ملف XML المحفوظ، ويفحص الختم بالشهادة الموجودة في الملف، وارتباط كل فاتورة بسابقتها وتسلسل العداد، وعداد الوحدة وآخر بصمة لها، وسلسلة سجل النشاط نفسها. ولا يغير شيئا سوى إضافة سطر chain.verified إلى السجل. شغله قبل أي تدقيق.

للقراءة فقط · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: كائن فيه ok وchecked_at وinvoices (عدد المستندات المفحوصة) وchains (سلسلة لكل وحدة ختمت مستندات، وفي كل منها ok وissues وlast_hash وhighest_icv) وphase1 (المستندات التي صدرت دون وحدة) وunit (فحص عداد الوحدة وآخر بصمة) وlog (فحص سلسلة سجل النشاط).

كل مشكلة في issues تسمي الفاتورة ورمز ما لا يصح: hash_mismatch وsignature_invalid وsignature_missing وpih_mismatch وicv_gap وicv_duplicate وxml_row_mismatch وxml_missing وcertificate_unreadable.
تلزم صلاحية الكتابة settings.write رغم أن بيانات الفواتير لا تتغير، لأن الأداة تسجل تشغيلها في سجل النشاط.