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

​

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

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 }
  }'

{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}

​

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

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

​

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

# 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"
  }'

​

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

​

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

# 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 — مفتاح غير صالح أو موقع غير مصرّح له

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

​

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

{
  "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 — تجاوز حد المعدل

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

​

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

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