نتائج الهيئة

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

{
  "kind": "standard",
  "status": "cleared",
  "uuid": "e7f8a9b0-c1d2-4e3f-a4b5-c6d7e8f9a0b1",
  "counter": 18,
  "hash": "zXab+32ksuccBzrDiE27f65AmOvbZ2ixbnSSRnoRKzA=",
  "qr": "ARBTYW5kYm94IE1lcmNoYW50Ag8zOTk5OTk5OTk5MDAwMDMDFDIwMjYtMTEtMDdUMDk6NDE6MjJaBAYyMzAuMDAFBTMwLjAw",
  "submittedAt": "2026-11-07T09:41:21.884Z",
  "clearedAt": "2026-11-07T09:41:22.517Z",
  "reportedAt": null,
  "errors": []
}

الحقل	المعنى
kind	standard للعميل من نوع شركة، و simplified للعميل الفرد
status	pending أو cleared أو reported أو rejected
uuid	الـ UUID للمستند في سجلات الهيئة
counter	عدّاد الفواتير لدى الهيئة
hash	الـ Hash للمستند، ويرتبط به المستند الذي يليه
qr	رمز QR بصيغة Base64، وفي المستند الضريبي هو الرمز الذي أرجعته الهيئة عند الاعتماد
submittedAt	وقت توقيع كسور للمستند، بتوقيت UTC
clearedAt	وقت اعتماد الهيئة للمستند الضريبي، بتوقيت UTC
reportedAt	وقت قبول الهيئة التبليغ بالمستند المبسط، بتوقيت UTC
errors	رسائل الهيئة إذا رفضت المستند، ولكل رسالة code و category و message

تبقى قيم uuid و counter و hash و qr و submittedAt بقيمة null حتى توقّع كسور المستند.

ماذا تفعل مع كل حالة

pending

المستند صادر وصحيح في كسور، لكن الهيئة لم تقبله بعد.

• المبسط: هذه الحالة الطبيعية بعد الإصدار مباشرة. تبلّغ كسور الهيئة بالمستند بعد الرد، ثم يصبح reported. وملف PDF جاهز فوراً، أما ملف XML فيرجع 409 invoice_not_cleared حتى تقبل الهيئة التبليغ.
• الضريبي: لم ترد الهيئة أثناء اعتماد كسور له. تعيد كسور إرساله لاحقاً، فيصبح cleared أو rejected. وحتى ذلك الحين يرجع ملفا PDF و XML القيمة 409 invoice_not_cleared، وكذلك أي إشعار دائن عليه.

لا تُصدر عملية البيع مرة أخرى، فالفاتورة الجديدة عملية بيع ثانية. وإذا انتهت مهلة طلبك ولم تعرف هل وصل أم لا، فأرسله مرة أخرى بالـ Idempotency-Key نفسه، فيرجع لك الرد الأول.

cleared

اعتمدت الهيئة هذا المستند الضريبي، وملفا PDF و XML جاهزان، ويحمل qr رمز QR الذي أرجعته الهيئة. لا يلزمك شيء.

reported

قبلت الهيئة التبليغ بهذا المستند المبسط، وملف XML جاهز. لا يلزمك شيء.

rejected

رفضت الهيئة المستند، ورسائلها في errors:

{
  "kind": "standard",
  "status": "rejected",
  "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "counter": 20,
  "hash": "PO9Je+Enxi/tc010iSgP6H+piJDaQh6zQZ41v6aDPsk=",
  "qr": "ARBTYW5kYm94IE1lcmNoYW50Ag8zOTk5OTk5OTk5MDAwMDMDFDIwMjYtMTEtMDdUMTA6MDI6MTFaBAYxMTUuMDAFBTE1LjAw",
  "submittedAt": "2026-11-07T10:02:11.430Z",
  "clearedAt": null,
  "reportedAt": null,
  "errors": [
    { "code": "BR-KSA-63", "category": "KSA", "message": "Buyer street is missing" }
  ]
}

يبقى المستند في كسور، لكن:

• ملف XML يرجع 409 invoice_not_cleared دائماً، وكذلك ملف PDF للمستند الضريبي؛
• الفاتورة التي رفضتها الهيئة لا يصدر عليها إشعار دائن عن طريق الـ API (422 invoice_not_creditable).

اعرض رسائل الهيئة على التاجر، ويصحح التاجر عملية البيع من لوحة تحكم كسور.

عندما ترفض الهيئة الفاتورة الضريبية وقت الإصدار

الفاتورة الضريبية تُعتمد قبل أن ترد كسور. فإذا رفضتها الهيئة حينها لا يُحفظ أي شيء، ولا يُستهلك رقم فاتورة، ويرجع الطلب 422 zatca_rejected ورسائل الهيئة في zatcaErrors:

{
  "error": {
    "type": "business_rule_error",
    "code": "zatca_rejected",
    "message": "رفضت هيئة الزكاة والضريبة والجمارك الفاتورة، ولم يُحفظ أي شيء. رسائل الهيئة موضحة في zatcaErrors.",
    "param": null,
    "docUrl": "https://docs.kosoor.com.sa/ar/errors#zatca_rejected",
    "zatcaErrors": [
      { "code": "BR-KSA-63", "category": "KSA", "message": "Sandbox sample rejection: the buyer's street is missing" }
    ]
  }
}

صحّح البيانات التي تذكرها الهيئة، وغالباً تكون في بيانات العميل فتعدّلها بـ PATCH /v1/customers/{id}، ثم أرسل الفاتورة مرة أخرى بـ Idempotency-Key جديد. والأمر نفسه ينطبق على الإشعار الدائن على فاتورة ضريبية.

وفي بيئة الاختبار يعطي العميلان الجاهزان Sandbox ZATCA Pending Co و Sandbox ZATCA Rejected Co هاتين النتيجتين في كل مرة. التفاصيل في وضع الاختبار.

النتائج التي تأتي لاحقاً

المستند الذي رجع بحالة pending تصله نتيجته لاحقاً. وتُرسلها كسور إلى نظامك فور وصولها: سجّل Webhook Endpoint لأحداث salesInvoice.zatca* و creditNote.zatca*. التفاصيل في Webhooks. وبدون ذلك، اقرأ المستند مرة أخرى بـ GET /v1/sales-invoices/{id} أو GET /v1/credit-notes/{id} عندما يحتاج نظامك حالته، واستخدم الفلتر zatcaStatus=pending في القائمتين لتعرف المستندات التي ما زالت تنتظر.