# فحص الطلب

> أرسل كل طلب إلى Antiro قبل قبوله، واحصل على القرار.

هذه صفحة واحدة من توثيق Antiro (https://docs.antiro.io/ar/api/assessments). كل الصفحات في ملف واحد: https://docs.antiro.io/ar/llms-full.txt

`POST https://api.antiro.io/v1/assessments`

## حقول الطلب

كل الحقول اختيارية، لكن دقة القرار تتبع ما ترسله.

- `session_token` (string, موصى به): مرجع الطلب: الحقل `antiro_token` في النموذج، أو الكوكي `_atr_st`، أو `Antiro.token()`.
- `order_id` (string, موصى به): رقم الطلب عندك. إعادة إرسال الرقم نفسه تعيد القرار الأول ولا تنشئ شيئاً جديداً.
- `phone` (string, موصى به): هاتف الزبون كما كتبه.
- `ip` (string, موصى به): عنوان IP الحقيقي للزبون، لا عنوان خادمك. خلف Cloudflare تجده في الرأس `CF-Connecting-IP`.
- `name` (string): اسم الزبون.
- `address` (string): عنوان التوصيل.
- `wilaya` (string): الولاية.
- `commune` (string): البلدية.
- `total` (number): مبلغ الطلب. القيمة التي ليست رقماً تُهمَل.
- `sdk_expect` (forms | collect): يبيّن كيف تشغّل صفحة هذا الطلب السكربت. انظر [أخبر Antiro بالطريقة التي تستعملها](https://docs.antiro.io/ar/sdk/modes#%D8%A3%D8%AE%D8%A8%D8%B1-antiro-%D8%A8%D8%A7%D9%84%D8%B7%D8%B1%D9%8A%D9%82%D8%A9-%D8%A7%D9%84%D8%AA%D9%8A-%D8%AA%D8%B3%D8%AA%D8%B9%D9%85%D9%84%D9%87%D8%A7). لا ترسله إلا لطلبات من صفحات تشغّل السكربت.
- `sdk_required` (boolean): الوضع الصارم لهذا الطلب، ولا يُقرأ إلا مع `sdk_expect`. بالقيمة `true` يُرفض الطلب الذي لا يحمل أي مرجع بدل أن يُوقف للمراجعة. انظر [الوضع الصارم](https://docs.antiro.io/ar/sdk/modes#%D8%A7%D9%84%D9%88%D8%B6%D8%B9-%D8%A7%D9%84%D8%B5%D8%A7%D8%B1%D9%85).
- `client_headers` (object): رؤوس طلب الزبون نفسه بأسماء صغيرة: `user-agent` و`accept-language` و`sec-ch-ua` و`sec-ch-ua-mobile` و`sec-ch-ua-platform` و`sec-fetch-site` و`sec-fetch-mode` و`sec-fetch-dest` و`x-requested-with` و`origin` و`referer`. وأي اسم آخر يُحذف.

## مثال على الطلب

**POST /v1/assessments · cURL**

```bash
curl https://api.antiro.io/v1/assessments \
  -H "X-API-Key: $ANTIRO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "<antiro_token>",
    "sdk_expect": "forms",
    "order_id": "1042",
    "phone": "0661234567",
    "name": "Yacine Benali",
    "address": "Cite 200 logements, Bab Ezzouar",
    "wilaya": "Alger",
    "total": 4900,
    "ip": "105.101.22.7"
  }'
```

**POST /v1/assessments · Node.js**

```js
const API = 'https://api.antiro.io/v1/assessments';

const res = await fetch(API, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ANTIRO_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    session_token: req.body.antiro_token,
    sdk_expect: 'forms',
    order_id: order.id,
    phone: order.phone,
    name: order.name,
    address: order.address,
    wilaya: order.wilaya,
    total: order.total,
    ip: req.ip,
  }),
  signal: AbortSignal.timeout(6000),
});

const { action, reasons } = await res.json();
```

**POST /v1/assessments · PHP**

```php
$token = $_POST['antiro_token']
    ?? $_COOKIE['_atr_st'] ?? '';

$ch = curl_init('https://api.antiro.io/v1/assessments');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 6,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ANTIRO_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'session_token' => $token,
        'sdk_expect' => 'forms',
        'order_id' => $order['id'],
        'phone' => $order['phone'],
        'name' => $order['name'],
        'address' => $order['address'],
        'wilaya' => $order['wilaya'],
        'total' => $order['total'],
        'ip' => $_SERVER['REMOTE_ADDR'],
    ]),
]);

$answer = json_decode(curl_exec($ch), true);
$action = $answer['action'] ?? null;
```

## الجواب

يعود الفحص الناجح بالرمز `201 Created`.

- `action` (string): ما تفعله بالطلب: `allow` أو `review` أو `block`. انظر [تنفيذ القرار](https://docs.antiro.io/ar/api/decisions).
- `recommended` (string): قرار Antiro نفسه. يختلف عن `action` في [وضع المراقبة](https://docs.antiro.io/ar/api/decisions#%D8%A3%D9%88%D8%B6%D8%A7%D8%B9-%D8%A7%D9%84%D8%AD%D9%85%D8%A7%D9%8A%D8%A9).
- `probability` (number): احتمال أن يكون الطلب وهمياً، من 0 إلى 1.
- `confidence` (number): ثقة Antiro في هذا الاحتمال، من 0 إلى 1.
- `reasons` (array): أسباب القرار، مرتبة من الأقوى. انظر [الأسباب](https://docs.antiro.io/ar/api/assessments#%D8%A7%D9%84%D8%A3%D8%B3%D8%A8%D8%A7%D8%A8).
- `id` (string): معرّف هذا الفحص. استعمله في `assessment_id` عند [إبلاغ النتيجة](https://docs.antiro.io/ar/api/outcomes)، أو [لقراءة الفحص لاحقاً](https://docs.antiro.io/ar/api/assessments#%D9%82%D8%B1%D8%A7%D8%A1%D8%A9-%D9%81%D8%AD%D8%B5-%D8%B3%D8%A7%D8%A8%D9%82).
- `order_id` (string): معرّف الطلب في Antiro، وهو غير رقم الطلب عندك.

**201 Created**

```json
{
  "id": "dfe0a5d8-9284-48d6-a2cd-ec49f2957f3b",
  "order_id": "94074eb2-6c23-42e0-92f9-9f865cf88452",
  "action": "review",
  "recommended": "review",
  "probability": 0.94,
  "confidence": 0.65,
  "reasons": [
    {
      "code": "contact.phone:pattern",
      "group": "contact",
      "weight": 1.36,
      "label": {
        "en": "Fake-looking phone number",
        "ar": "رقم هاتف يبدو وهمياً",
        "fr": "Numéro d’apparence factice"
      }
    },
    {
      "code": "contact.address:weak",
      "group": "contact",
      "weight": 0.51,
      "label": {
        "en": "Incomplete delivery address",
        "ar": "عنوان توصيل ناقص",
        "fr": "Adresse de livraison incomplète"
      }
    }
  ]
}
```

### الأسباب

لكل عنصر في `reasons` هذه الحقول:

- `code` (string): رمز قصير للسبب.
- `group` (string): العائلة التي ينتمي إليها السبب.
- `weight` (number): مقدار تأثير السبب.
- `label` (object): نص جاهز لفريقك، في `en` و`ar` و`fr`.

## قراءة فحص سابق

`GET https://api.antiro.io/v1/assessments/:id`

يعيد فحصاً سابقاً عبر `id` الموجود في جوابه. يحتوي الجواب الحقول السابقة، وهذه الثلاثة أيضاً:

- `kind` (string): نوع الفحص. لفحص الطلب تكون القيمة `order`.
- `verdict` (string): الحكم الذي أبلغت عنه عبر [`POST /v1/outcomes`](https://docs.antiro.io/ar/api/outcomes)، أو `null`.
- `created_at` (string): وقت الفحص.

**GET /v1/assessments/:id**

```bash
curl https://api.antiro.io/v1/assessments/<id> \
  -H "X-API-Key: $ANTIRO_SECRET_KEY"
```

**200 OK**

```json
{
  "id": "dfe0a5d8-9284-48d6-a2cd-ec49f2957f3b",
  "order_id": "94074eb2-6c23-42e0-92f9-9f865cf88452",
  "kind": "order",
  "action": "review",
  "recommended": "review",
  "probability": 0.94,
  "confidence": 0.65,
  "reasons": [],
  "verdict": "fake",
  "created_at": "2026-10-30T10:03:06.493Z"
}
```