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

> المصادقة بمفاتيح API من نوع Bearer. المفاتيح الحقيقية ومفاتيح الاختبار، وما يعيده وضع الاختبار، وإبطال المفتاح، وتحديد حد إنفاق شهري لكل مفتاح.

المصدر: https://fileverity.com/ar/docs/authentication

يتطلب كل طلب مفتاح API يُرسل بوصفه رمز Bearer في ترويسة `Authorization`.

**طلب مصادَق عليه: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**طلب مصادَق عليه: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/models", {
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
});
```

**طلب مصادَق عليه: Python**

```python
import os
import requests

requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})
```

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

## المفاتيح الحقيقية ومفاتيح الاختبار

المفتاح هو `fv_live_` أو `fv_test_` متبوعًا بعدد 40 من الأحرف والأرقام. وتحدد البادئة الوضع.

|  | مفتاح حقيقي | مفتاح اختبار |
| --- | --- | --- |
| البادئة | `fv_live_...` | `fv_test_...` |
| يشغّل النماذج | نعم | لا |
| يُخصم من رصيدك أو من رصيد البدء المجاني | نعم | أبدًا |
| النتائج | حقيقية | نموذجية ثابتة |
| `livemode` في الاستجابات | `true` | `false` |
| Webhooks | تُرسل | لا تُرسل |

يشترك الوضعان في مساحة عمل واحدة. ويستخدمان نقاط النهاية نفسها وقواعد التحقق نفسها وحدود المعدّل نفسها ورموز الأخطاء نفسها، فيمكنك البناء بمفتاح اختبار ثم تبديل المفتاح للانتقال إلى الإنتاج.

## سلوك وضع الاختبار

- **كشف النصوص.** يُتحقق من الطلب كما يُتحقق من الطلب الحقيقي: تبقى فحوصات الحد الأدنى للطول والحد الأقصى للطول واللغة سارية. والاستجابة نتيجة `human` ثابتة تكون فيها `score` و`ai_fraction` بقيمة `0` ودون `segments`. ويُحسب `usage` من نصك. لا يُحتسب أي رسم ولا يُسجَّل شيء.
- **الملفات.** يُتحقق من صحة الملفات المرفوعة دون تخزين بايتاتها، ويعيد طلب الرفع بصيغة JSON كائن رفع تجريبيًا بدلًا من عنوان URL موقّع مسبقًا حقيقي (قيمة `upload.test` هي `true`)، ويكون الملف في حالة `uploaded` منذ البداية. وتُفصل الملفات بحسب الوضع: لا يستطيع مفتاح الاختبار قراءة الملفات الحقيقية، ولا يستطيع المفتاح الحقيقي قراءة ملفات الاختبار.
- **إنشاء تحليل.** يعيد `200` فورًا مع `status: succeeded` ونموذج ثابت بالمستوى `L2` والإجراء `accept` و`livemode: false`. يبدأ معرّف التحليل بالبادئة `an_test` ويكون هو نفسه للملف نفسه. ويبدأ رقم التقرير بالبادئة `FV-TEST-` وليس له صفحة تحقق عامة. ولا يحتوي التقرير النموذجي إلا على الحقول الواردة في النموذج.
- **جلب تحليل.** يعمل مع معرّفات التحليلات النموذجية فقط. أما عملية **عرض قائمة التحليلات** فتعيد قائمة فارغة دائمًا، وتعيد عملية **الإلغاء** `not_cancelable`، ولا يوجد ملف PDF نموذجي. ولا تستطيع مفاتيح الاختبار قراءة التحليلات الحقيقية ولا ملفات PDF للتقارير الحقيقية.

**عملية كشف نص نموذجية، مفتاح اختبار**

```json
{
  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": false,
  "language": "en",
  "verdict": "human",
  "score": 0,
  "ai_fraction": 0,
  "segments": [],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## إنشاء المفاتيح وإبطالها

أدر المفاتيح في لوحة التحكم ضمن **مفاتيح API**.

- **الإنشاء.** سمِّ المفتاح واختر وضعه. يظهر المفتاح كاملًا مرة واحدة فقط. تخزّن Fileverity قيمة تجزئة SHA-256 وآخر أربعة أحرف فقط، لذلك لا يمكن استرداد مفتاح ضاع؛ أنشئ مفتاحًا جديدًا.
- **الحد.** يمكن أن تضم مساحة العمل حتى 20 مفتاحًا نشطًا. وبعد ذلك يفشل إنشاء مفتاح جديد برمز الخطأ `key_limit`.
- **آخر استخدام.** تعرض لوحة التحكم وقت آخر طلب أجراه كل مفتاح.
- **الإبطال.** تفشل فورًا الطلبات التي تستخدم مفتاحًا مُبطَلًا برمز الخطأ `invalid_api_key`.
- **الأعضاء الذين يغادرون.** عندما يغادر عضو مساحة العمل أو يُزال منها، تُبطَل المفاتيح التي أنشأها. أنشئ مفاتيح الإنتاج من حساب يبقى في مساحة العمل.

### إذا تسرّب مفتاح

1. أنشئ مفتاحًا جديدًا.
2. حدّث برمجياتك لاستخدامه.
3. أبطل المفتاح القديم.

## حدود الإنفاق الشهرية

يمكن أن يكون لكل مفتاح حد إنفاق شهري خاص به، بمبلغ صحيح بالدولار الأمريكي. لا يستطيع تعيينه أو تغييره إلا مالكو مساحة العمل ومسؤولوها، عند إنشاء المفتاح أو لاحقًا عبر **عدّل الحد**. أما المفتاح الذي لا حد له فلا يقيّده إلا رصيدك.

- يحسب الحد ما أنفقه المفتاح في الشهر التقويمي الحالي بالتوقيت العالمي المنسق (UTC)، ويُعاد تعيينه في الأول من الشهر.
- يُرفض الطلب الذي سيجعل المفتاح يتجاوز حده برمز الخطأ `spend_limit_reached` (رمز الحالة 402 في HTTP) قبل بدء أي عمل، ولا يُحتسب عليه أي رسم.
- لا تكلّف فحوصات رصيد البدء المجاني شيئًا ولا تُحتسب ضمن الحد. ولا تُحتسب رسوم على الفحوصات الفاشلة أو الملغاة ولا تدخل في الحد.
- تسري الحدود على المفاتيح الحقيقية. أما مفاتيح الاختبار فلا تنفق شيئًا أبدًا.

> **ملاحظة.** استخدم مفتاحًا منفصلًا، بحد إنفاق خاص به، لكل خدمة أو بيئة. وبذلك لا تستطيع مهمة خارجة عن السيطرة أن تنفق أكثر من حد ذلك المفتاح.

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

| الرمز | الحالة | المعنى |
| --- | --- | --- |
| `missing_api_key` | 401 | لم تُرسل ترويسة `Authorization: Bearer`. |
| `invalid_api_key` | 401 | المفتاح بصيغة غير صحيحة أو غير معروف أو مُبطَل. |
| `spend_limit_reached` | 402 | بلغ المفتاح حد إنفاقه الشهري. |

راجع [الأخطاء](https://fileverity.com/ar/docs/errors.md) للاطلاع على القائمة الكاملة.