# التحليلات

> أنشئ تحليلات الصور والمستندات، وانتظر النتيجة عبر Prefer: wait أو بالاستعلام المتكرر، وألغِ التحليل، ونزّل تقرير PDF، واقرأ كائن التقرير وصفحة التحقق.

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

التحليل هو فحص صورة أو مستند واحد. يفحص ملفًا مرفوعًا واحدًا بنموذج `fvimg-2` (الصور) أو `fvdoc-3` (المستندات). ارفع الملف أولًا (راجع [الملفات](https://fileverity.com/ar/docs/files.md))، ثم أنشئ التحليل.

للاطلاع على نظرة عامة على المنتج مع مثال على طلب واستجابة، راجع [واجهة API لكشف الصور المولَّدة بالذكاء الاصطناعي](https://fileverity.com/ar/api/ai-image-detection) و[واجهة API لكشف تزوير المستندات](https://fileverity.com/ar/api/document-fraud-detection).

## إنشاء تحليل

يعيد `POST /analyses` كائن التحليل. يُحجز السعر عند إنشاء التحليل ويُحرَّر إذا فشل أو أُلغي.

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `model` | string | نعم | `fvimg-2` أو `fvdoc-3`، أو معرّف نسخة مؤرَّخة مثل `fvimg-2-2026-10-30`. |
| `file` | string | نعم | معرّف ملف مرفوع. |
| `metadata` | object | لا | حتى 16 زوجًا نصيًا. المفاتيح حتى 40 حرفًا والقيم حتى 500. تُعاد مع التحليل وفي Webhooks. |
| `options.password` | string | لا | كلمة مرور مستند مشفَّر، حتى 256 حرفًا. |
| `options.locale` | string | لا | لغة مؤشرات المستند: `en` أو `fr` أو `de` أو `es` أو `zh` أو `vi` أو `ar`. القيمة الافتراضية `en`. |

**إنشاء تحليل: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \
  -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'
```

**إنشاء تحليل: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),
});
const analysis = await response.json();
```

**إنشاء تحليل: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},
)
analysis = response.json()
```

## الانتظار أو الاستعلام المتكرر أو استخدام Webhooks

يعيد الإنشاء `202` مع `status: processing`. لديك ثلاث طرق للحصول على النتيجة:

- **الانتظار.** أرسل `Prefer: wait=N`، حيث N حتى 60 ثانية. يبقى الطلب معلّقًا حتى ينتهي التحليل أو تمر N ثانية. يعيد التحليل المنتهي `200`؛ وإلا فتحصل على `202`. وتؤكد ترويسة الاستجابة `preference-applied: wait=N` الانتظار.
- **الاستعلام المتكرر.** استدعِ `GET /analyses/{id}` كل بضع ثوانٍ حتى لا تعود قيمة `status` هي `processing`.
- **Webhook.** اشترك في `analysis.completed` و`analysis.failed` واجلب التحليل عند وصول الحدث. راجع [Webhooks](https://fileverity.com/ar/docs/webhooks.md).

**الاستعلام المتكرر حتى الاكتمال: JavaScript**

```javascript
let analysis = created;
while (analysis.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, {
    headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
  });
  analysis = await response.json();
}
```

**الاستعلام المتكرر حتى الاكتمال: Python**

```python
import time

analysis = created
while analysis["status"] == "processing":
    time.sleep(3)
    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json()
```

**202 Accepted (مستند)**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "processing",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": null,
  "progress": {
    "stage": "queued",
    "done": 0,
    "total": 0,
    "position": 1
  },
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": null,
  "expires_at": null
}
```

أثناء معالجة التحليل تكون `progress.stage` إحدى القيم `queued` أو `reading` أو `analyzing` أو `reporting`، وتكون `position` موضع الطلب في قائمة الانتظار ما دامت المرحلة `queued`. يمكن أن تنتظر المستندات في قائمة الانتظار. الانتظار اختياري للمستندات وقد ينتهي قبل جاهزية النتيجة، لذا تعامل دائمًا مع الاستجابة `202`.

## عندما تكون السعة المتاحة مستخدمة بالكامل

عندما تكون السعة مشغولة، يعيد `POST /analyses` الرمز `503` مع الخطأ `service_unavailable` وترويسة `retry-after`. ولا تُحتسب عليك رسوم. انتظر عدد الثواني المذكور في `retry-after`، ثم أعد المحاولة مع `Idempotency-Key` نفسه حتى لا تُجري الإعادة فحصًا مرتين. وللحصول على أعلى إنتاجية، نفّذ تحليلات الصور واحدًا تلو الآخر بدلًا من تنفيذها بالتوازي.

**إعادة المحاولة عند انشغال الخدمة: JavaScript**

```javascript
async function create(body, key) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch("https://api.fileverity.com/v1/analyses", {
      method: "POST",
      headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },
      body: JSON.stringify(body),
    });
    if (response.status !== 503) return response;
    const wait = Number(response.headers.get("retry-after")) || 15;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Service busy");
}
```

**إعادة المحاولة عند انشغال الخدمة: Python**

```python
import time

def create(body, key):
    for attempt in range(5):
        response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body)
        if response.status_code != 503:
            return response
        time.sleep(int(response.headers.get("retry-after", 15)))
    raise RuntimeError("Service busy")
```

## الحالات

| الحالة | المعنى |
| --- | --- |
| `processing` | التحليل قيد التنفيذ. قيمة `result` هي `null`. |
| `succeeded` | النتيجة جاهزة. تكون الحقول `report_id` و`report_url` و`summary` و`result` معبّأة. |
| `failed` | تعذّر إكمال التحليل. يحتوي الحقل `error` على `code` و`message`. ولم تُحتسب عليك رسوم. |
| `canceled` | ألغيتَ التحليل. قيمة `error.code` هي `canceled`. ولم تُحتسب عليك رسوم. |

**تحليل فاشل**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "failed",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

## كائن التقرير

يحمل التحليل الناجح التقرير نفسه الذي يعرضه الموقع وملف PDF وصفحة التحقق.

| الحقل | الوصف |
| --- | --- |
| `report_id` | رقم التقرير، `FV-XXXX-XXXX-XXXX`. |
| `report_url` | صفحة التحقق العامة للتقرير. يستطيع كل من يملك الرابط مطابقة رقم التقرير وقيمة تجزئة الملف والطابع الزمني بالسجل، دون حساب. |
| `summary` | الحكم المختصر. انظر أدناه. |
| `result.report` | التقرير الكامل. قيمة `result.report.schema` هي `fileverity.report/1` للصور و`fileverity.docpro/1` للمستندات. |
| `result.stamped_at` | طابع زمني بصيغة Unix للطابع الزمني الصادر للتقرير وفق RFC 3161، أو `null`. |
| `usage` | `amount` المحتسب بالسنتات (0 لفحوصات رصيد البدء المجاني وللفحوصات الفاشلة) و`currency` و`funding` (`trial` أو `balance`). |
| `metadata` | البيانات الوصفية التي أرسلتها، أو `null`. |
| `expires_at` | طابع زمني بصيغة Unix تُزال بعده النتيجة `result`. تُحفظ النتائج 7 أيام. |

**200 OK (صورة)**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": "FV-7K2M-9QXD-4T8R",
  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
  "summary": {
    "level": "L2",
    "assessment": "authentic_untouched",
    "action": "accept",
    "ai": "very_low",
    "edit": "none"
  },
  "result": {
    "report": {
      "schema": "fileverity.report/1",
      "id": "FV-7K2M-9QXD-4T8R"
    },
    "stamped_at": 1793700130
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 199,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": 1793700131,
  "expires_at": 1794304931
}
```

كائن `report` مختصر أعلاه؛ أما الكائن الحقيقي فيحمل المؤشرات الكاملة.

`summary` هو الحكم الثابت القابل للقراءة آليًا. و`result.report` هو التقرير الكامل الذي يعرضه الموقع وملف PDF. وتتبع بنيته المخطط المذكور في `result.report.schema`. وضمن إصدار المخطط نفسه تحتفظ الحقول المذكورة باسمها ومعناها، ويمكن إضافة حقول جديدة، لذا تجاهل الحقول التي لا تعرفها.

### ملخص الصورة

| الحقل | القيم |
| --- | --- |
| `level` | `L0` غير محدد، `L1` المصدر موثَّق، `L2` لم تُرصد حالات شاذة، `L3` يحتاج إلى مراجعة يدوية، `L4` مثير للشبهة بدرجة عالية، `L5` أدلة قوية ضد الأصالة. |
| `action` | `accept`, `review`, `reject`, `resubmit` |
| `assessment` | `authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined` |
| `ai` | `labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated` |
| `edit` | `detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated` |

### ملخص المستند

| الحقل | الوصف |
| --- | --- |
| `kind` | دائمًا `docpro`. |
| `level` | `L0` غير محدد، `L1` المصدر موثَّق، `L2` لا مؤشرات على تلاعب، `L3` يحتاج إلى مراجعة يدوية، `L4` مخاطر عالية، `L5` مشكلات مثبتة. |
| `action` | `accept` أو `note` (قارن المحتوى المكتوب بالذكاء الاصطناعي المعلَّم في التقرير بسياستك) أو `review` أو `reject` أو `resubmit`. |
| `reason` | المؤشر أو الحالة التي بُني عليها المستوى، مثل `clean` أو `incomplete` أو معرّف مؤشر، أو `null`. |
| `findings` | معرّفات المؤشرات المهمة. |
| `pages`, `images` | صفحات المستند والصور المضمَّنة التي فُحصت. |
| `text` | الحكم على نص المستند (`ai_generated` أو `mixed` أو `human` أو `inconclusive`)، أو `null` إذا لم يُقيَّم النص. |
| `strong` | `true` عندما يكون أحد المؤشرات المذكورة قويًا. ويغيب الحقل فيما عدا ذلك. |

**200 OK (مستند)**

```json
{
  "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa",
  "object": "analysis",
  "created": 1793700300,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": "FV-3PXH-6WQ2-8NDC",
  "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC",
  "summary": {
    "kind": "docpro",
    "level": "L3",
    "action": "review",
    "reason": null,
    "findings": [],
    "pages": 12,
    "images": 3,
    "text": "human"
  },
  "result": {
    "report": {
      "schema": "fileverity.docpro/1",
      "id": "FV-3PXH-6WQ2-8NDC"
    },
    "stamped_at": 1793700340
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": null,
  "completed_at": 1793700341,
  "expires_at": 1794305141
}
```

### حقول تقرير الصورة

`result.report` لتحليل صورة. الكائنات المتداخلة مدرجة في [مرجع API](https://fileverity.com/ar/docs/api-reference.md#create-analysis).

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | نعم |  |
| `id` | string | نعم | رقم التقرير، FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | لا | موجود في التقارير النموذجية الثابتة التي تعيدها مفاتيح الاختبار. |
| `issuedAt` | string | لا | وقت إصدار التقرير، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time. |
| `issuer` | object | لا | الجهة التي أصدرت التقرير. |
| `file` | object | لا | الصورة المفحوصة. |
| `pro` | object | لا | الحكم. القيم نفسها الواردة في summary، مع reason. |
| `score` | integer أو null | لا | درجة الأصالة من 0 إلى 100 بخطوات قدرها 5: مدى قوة الأدلة التي تدعم كون الصورة التقاطًا أصيلًا غير معدَّل. وتكون null عند عدم التقييم. |
| `confidence` | إحدى القيم `"high"` أو `"medium"` أو `"low"` | لا | مقدار ما يتيح هذا الملف للتحليل إثباته. وغالبًا ما يعكس انخفاض الثقة الملف نفسه، مثل انخفاض الدقة أو الضغط الشديد. |
| `questions` | object | لا | الأسئلة الثلاثة التي يجيب عنها التقرير. |
| `generator` | object أو null | لا | أداة التوليد بالذكاء الاصطناعي المنسوبة إلى الصورة، أو null. |
| `regions` | array من object | لا | المناطق المعلَّمة، بالبكسل في الصورة المعروضة. |
| `provenance` | object | لا | ما تذكره سجلات الملف نفسه عن منشئه. |
| `digest` | string | لا | قيمة تجزئة محتوى التقرير، تستخدمها صفحة التحقق. |

### حقول تقرير المستند

`result.report` لتحليل مستند.

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | نعم |  |
| `id` | string | نعم | رقم التقرير، FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | لا | موجود في التقارير النموذجية الثابتة التي تعيدها مفاتيح الاختبار. |
| `issuedAt` | string | لا | وقت إصدار التقرير، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time. |
| `receivedAt` | string | لا | وقت استلام الملف، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time. |
| `issuer` | object | لا | الجهة التي أصدرت التقرير. |
| `file` | object | لا | المستند المفحوص. |
| `level` | إحدى القيم `"L0"` أو `"L1"` أو `"L2"` أو `"L3"` أو `"L4"` أو `"L5"` | لا | مستوى المخاطر، من L0 إلى L5. |
| `action` | إحدى القيم `"accept"` أو `"note"` أو `"review"` أو `"reject"` أو `"resubmit"` | لا |  |
| `reason` | string أو null | لا | المؤشر أو الحالة التي بُني عليها المستوى. |
| `findings` | array من object | لا | المؤشرات التي بُني عليها المستوى، مع الصفحات والصور المضمَّنة التي يشير إليها كل منها. |
| `text` | object | لا | نتيجة نص المستند. |
| `images` | array من object | لا | الصور والرسومات المضمَّنة، مرقَّمة بحسب ترتيبها في المستند. |
| `structure` | object أو null | لا | سجل تعديلات الملف، أو null إذا لم يُفحص. |
| `provenance` | object | لا | ما تذكره سجلات الملف نفسه عن منشئه. |
| `digest` | string | لا | قيمة تجزئة محتوى التقرير، تستخدمها صفحة التحقق. |

## الجلب وعرض القائمة والإلغاء

- يعيد `GET /analyses/{id}` التحليل، مع نتيجته ما دامت محفوظة.
- يعرض `GET /analyses` تحليلات مساحة العمل، من الأحدث إلى الأقدم. وقيمة `limit` من 1 إلى 100 (الافتراضي 20)، ويصفّي `type` بحسب `image` أو `document`، ويأخذ `starting_after` القيمة `next_cursor` من الصفحة السابقة. ولا تتضمن عناصر القائمة `result` أبدًا.
- يلغي `POST /analyses/{id}/cancel` تحليل مستند لا يزال قيد المعالجة ويحرّر المبلغ المحتسب. ولا يمكن إلغاء تحليلات الصور؛ ويعيد الإلغاء المتأخر أو الإلغاء بعد الاكتمال `not_cancelable`.

**العرض والإلغاء: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses?limit=20&type=document" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"

curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

## تقرير PDF

ينزّل `GET /analyses/{id}/report.pdf` تقرير PDF المختوم لتحليل ناجح ما دامت نتيجته محفوظة. أضف `?locale=` مع `en` أو `fr` أو `de` أو `es` أو `zh` أو `vi` أو `ar` (الافتراضي `en`). أرسل ترويسة `Authorization`؛ والاستجابة بصيغة `application/pdf`.

**تنزيل ملف PDF: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf
```

بالنسبة إلى المستندات، تُحفظ صور الصفحات ومقتطفات النص مدة 3 ساعات بعد الفحص. وبعد ذلك يخلو ملف PDF منها، وتصبح قيمة ترويسة الاستجابة `x-evidence-included` هي `false`. نزّل ملف PDF عند انتهاء التحليل إذا أردت أن يتضمن الأدلة.

## الأخطاء

| الرمز | الحالة | السبب |
| --- | --- | --- |
| `file_not_found` | 400 | معرّف الملف غير معروف أو منتهي الصلاحية أو سبق استخدامه، أو أن الرفع إلى `upload.url` لم ينتهِ بعد. |
| `model_not_found` | 404 | نموذج غير معروف. |
| `invalid_parameter` | 400 | حقل مفقود أو من نوع خاطئ أو غير معروف. وتُستخدم نماذج النصوص مع `POST /text/detections`. |
| `unsupported_file`, `invalid_file` | 415, 422 | صيغة الملف غير مدعومة لهذا النموذج، أو أن الملف تالف. |
| `file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long` | 413 | جرى تجاوز حد الحجم. |
| `password_required`, `wrong_password` | 422 | المستند مشفَّر. أرسل `options.password`. |
| `not_examinable` | 422 | لا يوجد في المستند ما يمكن فحصه. لا تُحتسب رسوم. |
| `insufficient_balance`, `spend_limit_reached` | 402 | الرصيد أو الحد الشهري للمفتاح لا يكفي لتغطية السعر. |
| `service_unavailable`, `analysis_failed` | 503, 502 | عطل مؤقت أو ازدحام في الخدمة. لا تُحتسب رسوم؛ أعد المحاولة. وتحمل `service_unavailable` ترويسة `retry-after`. راجع [عندما تكون السعة المتاحة مستخدمة بالكامل](https://fileverity.com/ar/docs/analyses.md#busy). |
| `unsupported_media_type` | 415 | لم يُرسل محتوى الطلب بصيغة `application/json`. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | استُخدم `Idempotency-Key` مع محتوى طلب مختلف، أو أن طلبه الأول لا يزال قيد التنفيذ. راجع [Idempotency](https://fileverity.com/ar/docs/idempotency.md). |
| `not_cancelable` | 409 | لا يمكن إلغاء سوى المستندات التي لا تزال قيد المعالجة. |

> **ملاحظة.** تحدث بعض حالات الفشل بعد إنشاء التحليل، مثلًا عندما يتعذر على نموذج إكمال عمله. وهي تضبط `status: failed` و`error` على التحليل بدلًا من إفشال استدعاء الإنشاء، ويُرسَل حدث Webhook من النوع `analysis.failed`. راجع [الأخطاء](https://fileverity.com/ar/docs/errors.md).