المصادقة والمفاتيح

كل طلب (ما عدا GET /v1/plans) يحتاج مفتاح API في ترويسة Authorization:

Authorization: Bearer fwt_live_K8mP2nQ9xY4vB7cL3dF6gH1j

كبديل متوافق مع بعض العملاء، تُقبل أيضًا الترويسة X-Api-Key بنفس القيمة.

لا تخلط بين مفتاحين. fwt_… يصادقك لدينا. أمّا Client-Id و Secret-Key فيصادقان منشأتك لدى البوابة، وتصدرهما من شاشة «ربط الأجهزة» في منصة الفوترة الوطني وتضعهما في الإعدادات مرّة واحدة — انظر مفاتيح البوابة من المنصة.

وضعا المفاتيح

البادئة	الوضع	السلوك
`fwt_test_`	اختبار	لا اتصال بالبوابة إطلاقًا. استجابة محاكاة فورية، فواتير غير محدودة، لا أثر ضريبي.
`fwt_live_`	إنتاج	إرسال فعلي إلى بوابة الفوترة الوطنية. يُحسب على حصة خطتك الشهرية.

كل ردّ يحمل ترويسة X-Fawtara-Mode بقيمة live أو test — استخدمها كحماية إضافية في نظامك.

الصلاحيات (Scopes)

امنح كل مفتاح أقل صلاحية يحتاجها. المفتاح الذي لا يملك الصلاحية يُرفض برمز 403 insufficient_scope.

الصلاحية	الوصف	النقاط المتأثّرة
`invoices:write`	إنشاء وإرسال الفواتير والمرتجعات	`POST /v1/invoices`, `/credit-notes`, `/retry`, `/preview`
`invoices:read`	قراءة الفواتير والسجل والـ UBL والـ QR	`GET /v1/invoices…`
`webhooks:write`	إدارة نقاط الإشعار	`/v1/webhooks`
`account:read`	قراءة بيانات الحساب والاستهلاك	`/v1/account`, `/v1/usage`

تخزين المفتاح

لا تضع المفتاح في كود الواجهة (JavaScript في المتصفّح أو تطبيق جوّال) — المفتاح يمنح صلاحية إصدار فواتير باسم منشأتك.
استخدم متغيّرات البيئة أو خدمة أسرار، ولا تُدخله في مستودع الكود.
نحتفظ بـ بصمة SHA-256 للمفتاح فقط، لذا لا يمكننا استعادته لك — أنشئ مفتاحًا جديدًا إن فُقد.

التبديل الآمن (Rotation)

أنشئ مفتاحًا جديدًا بنفس الصلاحيات.

انشره في بيئة نظامك وتأكّد من نجاح الطلبات (راقب سجل الطلبات).

أبطِل المفتاح القديم. الإبطال يسري فورًا ويُعيد 401 revoked_api_key.

أخطاء المصادقة

الرمز	`error.type`	السبب
401	`missing_api_key`	لم تُرسل ترويسة `Authorization`.
401	`invalid_api_key`	المفتاح غير موجود أو به خطأ نسخ.
401	`revoked_api_key`	أُبطل المفتاح من اللوحة.
401	`expired_api_key`	انتهت صلاحية المفتاح.
403	`insufficient_scope`	المفتاح لا يملك الصلاحية المطلوبة.
403	`account_suspended`	الحساب موقوف إداريًا.

إذا استخدمت Apache، تأكّد أن ترويسة Authorization تُمرَّر إلى PHP. ملف .htaccess المرفق مع المنصّة يفعل ذلك عبر E=HTTP_AUTHORIZATION.

→ البدء السريع مفاتيح البوابة من المنصة ←