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

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

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

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

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

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

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

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

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

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

• كشف النصوص. يُتحقق من الطلب كما يُتحقق من الطلب الحقيقي: تبقى فحوصات الحد الأدنى للطول والحد الأقصى للطول واللغة سارية. والاستجابة نتيجة 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 للتقارير الحقيقية.

{  "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) قبل بدء أي عمل، ولا يُحتسب عليه أي رسم.
• لا تكلّف فحوصات رصيد البدء المجاني شيئًا ولا تُحتسب ضمن الحد. ولا تُحتسب رسوم على الفحوصات الفاشلة أو الملغاة ولا تدخل في الحد.
• تسري الحدود على المفاتيح الحقيقية. أما مفاتيح الاختبار فلا تنفق شيئًا أبدًا.

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

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

راجع الأخطاء للاطلاع على القائمة الكاملة.