# نتائج الهيئة

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

كل فاتورة مبيعات وإشعار دائن يحمل الكائن `zatca`، ويوضح وضع المستند لدى هيئة الزكاة والضريبة والجمارك (ZATCA). وإذا كانت الهيئة جديدة عليك فاقرأ [ابدأ من هنا](https://docs.kosoor.com.sa/ar/start-here.md#zatca-in-five-minutes) أولاً.

```json
{
  "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`:

```json
{
  "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`:

```json
{
  "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** هاتين النتيجتين في كل مرة. التفاصيل في [وضع الاختبار](https://docs.kosoor.com.sa/ar/test-mode.md).

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

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

المصدر: https://docs.kosoor.com.sa/ar/zatca