بيئة الاختبار

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

ما يتغيّر في بيئة الاختبار

محاكاة الرفض

اختبار المسار السعيد وحده لا يكفي. لمحاكاة رفض من البوابة، اجعل invoice_number يبدأ بـ TEST-REJECT:

curl -X POST https://fawtara.codexal.co/api/v1/invoices \
  -H "Authorization: Bearer fwt_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "TEST-REJECT-001",
    "customer": { "name": "عميل اختبار" },
    "lines": [ { "name": "صنف", "quantity": 1, "unit_price": 10 } ]
  }'

HTTP/1.1 202 Accepted

{
  "data": {
    "id": "inv_…",
    "status": "rejected",
    "qr_content": null,
    "jofotara": { "status": "SANDBOX_REJECTED", "http_code": 400 },
    "error": {
      "type": "jofotara_rejected",
      "message": "رفض محاكى من بيئة الاختبار (رقم الفاتورة يبدأ بـ TEST-REJECT)."
    }
  },
  "warning": "لم تُقبل الفاتورة من البوابة. راجع الحقل error …"
}

لماذا الاختبار هنا ليس اختيارياً

هذه رسالة تنبيهية يعرضها نظام الفوترة الوطني قبل تأكيد الربط. بمجرد تفعيله لتسلسل مصدر دخل معيّن، يتوقّف إصدار الفواتير يدوياً من المنصة لذلك التسلسل ويصبح نظامك هو المصدر الوحيد — فلا توجد شبكة أمان تعود إليها إن اكتشفت ثغرة في تكاملك بعد الإطلاق. أنهِ القائمة التالية هنا أولاً. التفاصيل في مفاتيح البوابة من المنصة.

قائمة فحص قبل الإنتاج

• نجاح إنشاء فاتورة نقدية وأخرى ذمم.
• التعامل الصحيح مع 202 و status = rejected (لا تعتبرها نجاحًا!).
• التعامل مع 422 وعرض error.fields لمستخدمك.
• التعامل مع 429 بإعادة محاولة بعد Retry-After.
• إرسال Idempotency-Key فريد لكل فاتورة في نظامك.
• تخزين id و uuid و icv و qr_content في جدول فواتيرك.
• اختبار إشعار دائن على فاتورة اختبارية.
• التحقّق من توقيع الـ Webhook إن كنت تستخدمه.
• مراقبة GET /v1/usage للتنبيه قبل نفاد الحصة.

مختبر داخل اللوحة

إن لم ترغب بكتابة كود بعد، استخدم مختبر الـ API في لوحة التحكم: ألصق JSON، وعايِن مستند UBL، أو أرسل على بيئة الاختبار بزر واحد.