# قائمة التحقق قبل التشغيل الفعلي

> ما يجب التحقق منه في الربط قبل أن تمر عن طريقه أول عملية بيع حقيقية للتاجر.

راجع هذه القائمة بمفتاح الاختبار قبل أن تنتقل إلى المفتاح الفعلي.

## المفاتيح

- [ ] المفتاح محفوظ على السيرفر عندك فقط، وليس في تطبيق جوال أو متصفح أو مستودع كود.
- [ ] المفتاح الفعلي يحمل الصلاحيات التي يستخدمها نظامك فقط، والفروع التي يعمل فيها فقط.
- [ ] يقرأ نظامك المفتاح من الإعدادات، فلا يحتاج تغييره إلى إصدار جديد من نظامك.
- [ ] تعرف من الشخص لدى التاجر الذي يبطل المفتاح ويصدر غيره، ونظامك يتعامل مع `401 revoked_api_key` و `401 expired_api_key` بتنبيه شخص مسؤول، وليس بإعادة المحاولة.
- [ ] إذا كان للمفتاح تاريخ انتهاء، فهناك شخص مسؤول عن تجديده قبل ذلك اليوم.

## الطلبات

- [ ] كل طلب `POST` و `PATCH` يرسل `Idempotency-Key`، مفتاحاً واحداً لكل عملية، وإعادة المحاولة ترسل المفتاح نفسه.
- [ ] لا تعيد المحاولة إلا عند انتهاء المهلة، أو انقطاع الاتصال، أو `409 idempotency_in_progress`، أو `5xx`، وبالمفتاح نفسه. التفاصيل في [منع تكرار الطلبات](https://docs.kosoor.com.sa/ar/idempotency.md).
- [ ] الكود عندك يعتمد على `code` وليس على `message`.
- [ ] تسجّل الـ `Request-Id` لكل طلب، لترسله إلى الدعم عند الحاجة.
- [ ] معرّفات الفروع والأصناف وطرق الدفع تأتي من `GET /v1/branches` و `GET /v1/items` و `GET /v1/payment-methods`، وليست ثابتة في الكود.
- [ ] كل فاتورة مبيعات ودفعة وإشعار دائن يحمل `referenceId` خاصاً بك، ونظامك يتعامل مع `409 reference_id_taken` بقراءة `existingId`.
- [ ] رقم الجوال في الـ Query String مكتوب بالشكل `%2B966...` وليس `+966...`.

## المبالغ

- [ ] تقرأ `total` و `lines[].unitDiscount` و `amountPaid` و `amountDue` من الرد، وليس من طلبك.
- [ ] لدفع الفاتورة كاملة ترسل `payment` بدون `amount`.
- [ ] البيع للعميل الفرد يُدفع عند الإصدار، والبيع بالآجل للشركات فقط.

## هيئة الزكاة والضريبة والجمارك

- [ ] يعرض نظامك أو يخزّن `zatca.status` لكل فاتورة وإشعار دائن، ويتعامل مع `pending` على أنها صادرة وليست فاشلة.
- [ ] المستند المرفوض (`rejected`) يصل إلى شخص لدى التاجر يستطيع تصحيحه.
- [ ] نظامك يتعامل مع `422 zatca_rejected` و `422 customer_address_incomplete` في الفواتير الضريبية، واختبرتهما بالعملاء الجاهزين في بيئة الاختبار.
- [ ] لا تطلب ملف PDF للفاتورة الضريبية إلا بعد أن تصبح `cleared`.

## الانتقال إلى التشغيل الفعلي

- [ ] أصدر التاجر مفتاحاً فعلياً بالصلاحيات والفروع نفسها التي في مفتاح الاختبار.
- [ ] يتحقق نظامك من الـ Header `Kosoor-Mode`: موجود بقيمة `test` في بيئة الاختبار، وغير موجود في البيانات الفعلية.
- [ ] أرسلت طلباً فعلياً واحداً، ووجده التاجر في **الإعدادات ← المطوّرون ← سجل الطلبات** تحت **فعلي**.
- [ ] العملاء الذين أنشأتهم في بيئة الاختبار تنشئهم من جديد، أو تجدهم، في البيانات الفعلية، فعملاء بيئة الاختبار خاصون بها.

## الدعم

دعم كسور متاح عبر واتساب فقط على الرقم [+966 12 606 1770](https://wa.me/966126061770)، بلا مكالمات ولا بريد إلكتروني. أرسل الـ `Request-Id` للطلب، وما كنت تتوقعه.

المصدر: https://docs.kosoor.com.sa/ar/go-live