> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# التحقق من أحداث الخادم وتصحيحها

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

## الخطوة 1: أرسل حدثًا تجريبيًا

أرسل حدثًا تجريبيًا واحدًا بقيمة `event_id` معروفة حتى تتمكن من تتبعه:

```bash theme={null}
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002",
    "properties": { "test": true }
  }'
```

يبدو الرد الناجح هكذا:

```json theme={null}
{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}
```

## الخطوة 2: تأكد من ظهوره في لوحة التحكم

1. افتح لوحة تحكم Scanova
2. انتقل إلى **التحليلات ← تتبع التحويلات**
3. افتح موقع التتبع
4. من المفترض أن يظهر `test_event` خلال 30 إلى 60 ثانية

## الخطوة 3: اختبر منع التكرار

أعد إرسال الطلب نفسه بقيمة `event_id` نفسها:

```bash theme={null}
# Same request again
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002"
  }'
```

سيعود الرد `200` في الطلب الثاني، لكن الحدث يُوسم بأنه مكرر ويُستبعد من أعداد التحويلات. فتأكد أن عدد الأحداث في التقارير لم يرتفع.

***

## الأخطاء الشائعة وحلولها

### `401` — مفتاح API مفقود

الترويسة `X-API-Key` غير موجودة في الطلب.

```bash theme={null}
# Wrong — missing header
curl -X POST "https://track.scanova.io/server-events" -d '{...}'

# Correct
curl -X POST "https://track.scanova.io/server-events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{...}'
```

### `403` — مفتاح غير صالح أو موقع غير مصرّح له

إما أن مفتاح API غير صالح أو مُبطل، وإما أن `site_id` في محتوى الطلب لا يخص الموقع الذي ينتمي إليه المفتاح. تحقق مما يلي:

* أن المفتاح نُسخ بشكل صحيح (بلا مسافات أو أسطر زائدة في نهايته)
* أن `site_id` في جسم الطلب يطابق تمامًا الموقع الذي أنشأ المفتاح
* أن المفتاح لم يُبطل في لوحة التحكم

### `422` — خطأ في التحقق

لم يجتز محتوى الطلب التحقق من المخطط. ويتضمن الرد التفاصيل:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

الأسباب الشائعة:

* نقص حقل مطلوب (`site_id` أو `event_name` أو `scan_session_id`)
* `scan_session_id` ليست بصيغة UUID صحيحة
* `conversion_value.currency` ليست رمزًا من ثلاثة أحرف وفق ISO
* حجم الكائن `properties` يتجاوز 10 كيلوبايت
* وجود بريد إلكتروني صريح في `properties` (استخدم `user_identifiers.email_hash` بدلًا منه)

### `429` — تجاوز حد المعدل

أنت ترسل أكثر من 1000 حدث في الدقيقة لكل مفتاح API. تمهّل ثم أعد المحاولة:

* راجع ترويسة `Retry-After` في الرد
* استخدم نقطة وصول الدفعات (`POST /server-events/batch`) لتجميع عدة أحداث في طلبات أقل

### الحدث وصل لكنه لا يظهر في التقارير

* انتظر 60 ثانية — فهناك تأخير بسيط في المعالجة
* تحقق من أن `site_id` في محتوى طلبك يطابق موقع التتبع الذي تعرضه في لوحة التحكم
* تأكد من أن `scan_session_id` معرّف UUID صحيح — فالصيغة غير الصحيحة تُرفض بالرد `422`
* تأكد من أن `scan_session_id` الذي أرسلته يخص جلسة مسح حقيقية من رمز QR وليس معرّفًا تجريبيًا — فالأحداث التي يتعذر ربط جلستها لا تُنسب وقد لا تظهر في التقارير