# فحص الانتحال

> اعثر على مقاطع من نص عادي تتطابق مع صفحات الويب العامة وويكيبيديا عبر POST /text/plagiarism. حقول الطلب والاستجابة، والمصادر، والتطابقات، والاستثناءات، والنطاق، والحدود، والفوترة.

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

يفحص `POST /text/plagiarism` نصًا واحدًا بالنموذج `plagiarism-1`. يبحث في صفحات الويب العامة وويكيبيديا عن مقاطع تتطابق مع النص، ويعيد المقاطع المتطابقة والمصادر التي تتطابق معها ونسبة النص المتطابق. وهو متزامن ويستغرق عادةً من 20 إلى 60 ثانية: أبقِ الاتصال مفتوحًا.

يعمل مع العربية والإنجليزية والفرنسية والإسبانية. احفظ نصًا من 50 كلمة أو أكثر باسم `essay.txt` لتشغيل الأمثلة.

**الطلب: cURL**

```bash
curl https://api.fileverity.com/v1/text/plagiarism \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3e8d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e31" \
  --max-time 120 \
  -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"
```

**الطلب: JavaScript**

```javascript
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const response = await fetch("https://api.fileverity.com/v1/text/plagiarism", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ text: await readFile("essay.txt", "utf8"), language: "en" }),
  signal: AbortSignal.timeout(120_000),
});
const check = await response.json();
```

**الطلب: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/text/plagiarism",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"},
    timeout=120,
)
check = response.json()
```

## محتوى الطلب

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `text` | string | نعم | نص عادي لا يقل عن 50 كلمة ولا يزيد على 30,000 حرف. |
| `model` | string | لا | الافتراضي `plagiarism-1`. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة `plagiarism-1-2026-11-16`. |
| `language` | string أو null | لا | رمز ISO 639-1: `en` أو `es` أو `fr` أو `ar`. يُكتشف تلقائيًا عند عدم إرساله. يحدّد إصدار ويكيبيديا ولغة البحث. |

تُرفض الحقول غير المعروفة برمز الخطأ `invalid_parameter`. ويُعاد `unsupported_language` للنص بلغة أخرى أو الذي يتعذّر التعرف على لغته.

## الاستجابة

**200 OK**

```json
{
  "id": "tpl_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "text.plagiarism",
  "created": 1794787200,
  "model": "plagiarism-1-2026-11-16",
  "livemode": true,
  "language": "en",
  "words": 812,
  "scored_words": 744,
  "excluded_words": {
    "quoted": 23,
    "reference": 45
  },
  "matched_words": 61,
  "similarity": 0.082,
  "sources": [
    {
      "id": 1,
      "url": "https://en.wikipedia.org/wiki/Photosynthesis",
      "title": "Photosynthesis",
      "host": "en.wikipedia.org",
      "words": 38,
      "share": 0.051,
      "partial": false
    },
    {
      "id": 2,
      "url": "https://example.org/biology/light-reactions",
      "title": "The light reactions of photosynthesis",
      "host": "example.org",
      "words": 23,
      "share": 0.031,
      "partial": false
    }
  ],
  "matches": [
    {
      "start": 1022,
      "end": 1288,
      "words": 38,
      "source": 1,
      "excerpt": "Photosynthesis is a system of biological processes by which photopigment-bearing autotrophic organisms, such as most plants, algae and cyanobacteria, convert light energy into the chemical energy necessary to fuel their metabolism.",
      "quoted": false,
      "reference": false,
      "exact": true
    },
    {
      "start": 2410,
      "end": 2566,
      "words": 23,
      "source": 2,
      "excerpt": "In the light-dependent reactions, one molecule of the pigment chlorophyll absorbs one photon and loses one electron.",
      "quoted": false,
      "reference": false,
      "exact": false
    },
    {
      "start": 3105,
      "end": 3230,
      "words": 19,
      "source": 1,
      "excerpt": "The term photosynthesis usually refers to oxygenic photosynthesis, a process that releases oxygen as a byproduct.",
      "quoted": true,
      "reference": false,
      "exact": true
    }
  ],
  "queries": 12,
  "pages": 9,
  "version": "2026.11-p1",
  "usage": {
    "characters": 5120,
    "billed_units": 6,
    "credits": 6
  }
}
```

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `id` | string | معرّف الفحص، بالبادئة `tpl_`. |
| `object` | string | دائمًا `text.plagiarism`. |
| `created` | integer | طابع زمني بصيغة Unix. |
| `model` | string | النسخة المؤرَّخة التي أنتجت النتيجة. |
| `livemode` | boolean | `false` لمفاتيح الاختبار. |
| `language` | string | اللغة المستخدمة: التي أرسلتها، أو التي اكتُشفت. |
| `words` | integer | عدد الكلمات في النص. |
| `scored_words` | integer | الكلمات خارج علامات الاقتباس وقائمة المراجع. وهي مقام `similarity`. |
| `excluded_words` | object | `quoted` للكلمات داخل علامات الاقتباس و`reference` للكلمات في قائمة المراجع، لتتمكن من إعادة حساب النسبة باستثناءات أخرى. |
| `matched_words` | integer | الكلمات المحتسبة داخل المقاطع المتطابقة، وتُحسب كل كلمة مرة واحدة. |
| `similarity` | number | من 0 إلى 1: `matched_words` مقسومًا على `scored_words`. نسبة من النص المتطابق، وليست حكمًا. |
| `sources` | array | المصادر التي فيها مقطع متطابق واحد على الأقل، من الأكبر إلى الأصغر. لكل مصدر `id` و`url` و`title` و`host` و`words` و`share` و`partial`، وقيمته `true` عندما لم يمكن مقارنة سوى مقتطف البحث من الصفحة. |
| `matches` | array | المقاطع المتطابقة بترتيب ورودها في النص. لكل منها `start` و`end` (غير مضمَّن في النطاق) و`words` و`source` (قيمة `id` المصدر) و`excerpt` (النص المتطابق في المصدر، حتى 300 حرف) و`quoted` و`reference` و`exact`. |
| `queries` | integer | العبارات التي جرى البحث عنها. |
| `pages` | integer | الصفحات التي جرت مقارنتها. |
| `version` | string | إصدار طريقة المطابقة. قارن النتائج داخل الإصدار الواحد فقط. |
| `usage` | object | `characters` الأحرف التي جرى تقييمها، و`billed_units` الوحدات المحتسبة، و`credits` وحدات رصيد المخصومة. |

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

## كيف يعمل الفحص وما الذي يغطيه

- يُبحث عن عبارات مميزة من النص كعبارات حرفية في الويب العام وفي إصدار ويكيبيديا بلغة النص. وتُجلب الصفحات التي تظهر وتُقارَن بالنص كلمةً كلمة، فيلزم لكل تطابق عدة كلمات بالترتيب نفسه؛ ويظل تغيير بضع كلمات أو إدراجها تطابقًا، ويُبلَّغ عن المقطع حينئذٍ مع `exact` بقيمة `false`.
- المصادر التي شملها البحث: صفحات الويب العامة وويكيبيديا. لا يطّلع الفحص على الكتب ولا الدوريات العلمية المدفوعة ولا أبحاث الطلاب الآخرين ولا منصات التعلّم ولا قواعد البيانات الخاصة. والصفحات التي ترفض الوصول الآلي تُقارَن عبر مقتطف البحث منها فقط (`partial`).
- ما لا يُكتشف: النص المُعاد صياغته والنص المترجَم والنص الذي مصدره غير عام. فقد يكون النص منسوخًا ولا يُعثر على أي تطابق.
- الاستثناءات: المقاطع الواقعة بين علامات اقتباس تكون فيها `quoted` بقيمة `true`، والمقاطع التي تلي عنوانًا مثل References أو Bibliography أو Références أو Referencias أو المراجع تكون فيها `reference` بقيمة `true`. ويُستبعد الاثنان من `similarity`؛ استخدم `excluded_words` لتضمينهما.
- تُرسل عبارات من النص إلى Brave Search وإلى ويكيبيديا للعثور على الصفحات المرشَّحة. ولا يُرسل النص كاملًا إليهما أبدًا، ولا يُضاف شيء إلى أي قاعدة بيانات.

## الإزاحات

`start` و`end` لكل تطابق إزاحتان في النص الذي أرسلته، تُحسبان بنقاط رمز Unicode، وليس بالبايتات ولا بوحدات UTF-16. تفهرس سلاسل JavaScript بوحدات UTF-16، لذا قسّم النص إلى نقاط رمز أولًا:

**اقتطاع مقطع متطابق: JavaScript**

```javascript
const points = Array.from(text);
for (const { start, end, source } of check.matches) {
  console.log(source, points.slice(start, end).join(""));
}
```

**اقتطاع مقطع متطابق: Python**

```python
for match in check["matches"]:
    print(match["source"], text[match["start"]:match["end"]])
```

## الفوترة

- تبلغ تكلفة فحص الانتحال وحدة رصيد واحدة لكل 1,000 حرف، تُحتسب بنقاط رمز Unicode. يُقرَّب كل طلب إلى وحدات كاملة بالرفع، بحد أدنى وحدة واحدة.
- `usage.billed_units` هو عدد الوحدات المحتسبة و`usage.credits` وحدات الرصيد المخصومة. مثال: يُحتسب 5,120 حرفًا بـ 6 وحدات، أي 6 وحدات رصيد.
- يُحتسب الفحص الذي لا يجد أي مصدر متطابق أيضًا: فقد أُجري البحث. ولا تُحتسب الطلبات المرفوضة قبل التقييم، ويُلغى حجز وحدات الرصيد للفحص الذي يفشل داخل الخدمة (`service_unavailable`) فلا يُحتسب.
- عند عدم كفاية وحدات الرصيد يُرجع الطلب `insufficient_balance` (402). عبر API يتاح فحص الانتحال لمساحات العمل التي اشترت وحدات رصيد، ويستهلك وحدات رصيد دائمًا؛ أما على الموقع وفي لوحة التحكم فهو ضمن خطة Pro.

## ما الذي يُخزَّن

وتُحفظ نسخة من النص مشفّرة مدة تصل إلى 3 سنوات لتدريب نماذج الكشف في Fileverity وتقييمها؛ راجع [الاحتفاظ بالبيانات والأمان](https://fileverity.com/ar/docs/security.md#retention). تحتفظ Fileverity بالنتيجة (المصادر، وإزاحات التطابقات مع مقتطفات قصيرة من المصادر، والأعداد، والاستخدام) مدة 7 أيام، حتى تعرضها لوحة التحكم ويمكن احتساب الاستخدام وتدقيقه. ولا تُحفظ الصفحات المجلوبة، إذ تُقارَن في الذاكرة. ويحصل الطلب المُعاد الذي يحمل `Idempotency-Key` نفسه على النتيجة المحفوظة خلال 24 ساعة. عمليات فحص الانتحال متزامنة: فلا تظهر في `GET /analyses` ولا تُرسل أحداث Webhook. ولا تسجّل مفاتيح الاختبار شيئًا. راجع [الاحتفاظ بالبيانات والأمان](https://fileverity.com/ar/docs/security.md).

## الأخطاء

| الرمز | الحالة | السبب |
| --- | --- | --- |
| `text_too_short` | 400 | أقل من 50 كلمة. |
| `text_too_long` | 413 | أكثر من 30,000 حرف. قسّم النص إلى عدة طلبات. |
| `unsupported_language` | 400 | النص ليس بالعربية أو الإنجليزية أو الفرنسية أو الإسبانية، أو تعذّر التعرف على لغته. أرسل `language` لاختيار إحداها. |
| `unsupported_media_type` | 415 | لم يُرسل محتوى الطلب بصيغة `application/json`. |
| `invalid_json`, `missing_parameter`, `invalid_parameter` | 400 | المحتوى ليس كائن JSON، أو `text` مفقود، أو نوع أحد الحقول خاطئ، أو أُرسل حقل غير معروف. |
| `model_not_found` | 404 | قيمة `model` غير معروفة. |
| `plan_required` | 403 | لم تشترِ مساحة العمل وحدات رصيد بعد. اشترِ باقة وحدات رصيد من لوحة التحكم. |
| `insufficient_balance` | 402 | الرصيد لا يغطي الطلب. |
| `spend_limit_reached` | 402 | بلغ المفتاح حد إنفاقه الشهري. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | استُخدم `Idempotency-Key` مع محتوى طلب مختلف، أو لا يزال طلبه الأول قيد التنفيذ. |
| `service_unavailable`, `analysis_failed` | 503, 502 | تعذّر إكمال البحث أو المقارنة. لا تُحتسب رسوم؛ أعد المحاولة. يحمل `service_unavailable` ترويسة `retry-after`. |

> **ملاحظة.** أرسل `Idempotency-Key` حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع [منع التكرار](https://fileverity.com/ar/docs/idempotency.md).

