الانتقال إلى المحتوى الرئيسي
عرض بصيغة Markdownفتح في Claudeفتح في ChatGPT

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

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

المفاتيح​

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

الطلبات​

  • كل طلب POST و PATCH يرسل Idempotency-Key، مفتاحاً واحداً لكل عملية، وإعادة المحاولة ترسل المفتاح نفسه.
  • لا تعيد المحاولة إلا عند انتهاء المهلة، أو انقطاع الاتصال، أو 409 idempotency_in_progress، أو 5xx، وبالمفتاح نفسه. التفاصيل في منع تكرار الطلبات.
  • الكود عندك يعتمد على 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، بلا مكالمات ولا بريد إلكتروني. أرسل الـ Request-Id للطلب، وما كنت تتوقعه.