Checkify
مستندات المطور

التحقق على الواجهة الخلفية لديك

بعد اكتمال تضمين المتصفح، يجب على الخادم الخاص بك التحقق من النتيجة باستخدام مفتاح الموقع API قبل السماح بالتسجيل أو الخروج أو أي إجراء محمي.

التحقق من الخادم خلال 5 دقائق

  1. أضف تضمين المتصفح Checkify إلى صفحتك.
  2. يقوم التضمين ببدء جلسة Checkify وكتابة مرجع التحقق في النموذج الخاص بك.
  3. يقوم نظامك الخلفي بقراءة قيمة الحقل المخفي.
  4. يقوم نظامك الخلفي بإرسال تلك القيمة إلى POST /v1/qr/results/verify كـ request_id.
  5. إذا تمت الموافقة على المطالبات المطلوبة، فاسمح بالإجراء المحمي.
  6. لا تثق أبدًا بحالة الواجهة الأمامية وحدها.

قد يُسمى حقل النموذج المخفي checkify_token، لكن قيمته هي request_id Checkify.

التدفق من البداية إلى النهاية

1. قم بإنشاء موقع API مفتاح

في لوحة معلومات عملك، افتح مطور وقم بإنشاء مفتاح موقع API للموقع الذي تقوم بدمجه. قم بتخزينه في متغيرات بيئة الخادم فقط — لا تقم أبدًا بشحنه إلى المتصفح.

استخدام الواجهة الأمامية SDK؟

لستَ بحاجةٍ إلى استدعاء GET /v1/qr/pass/{PASS_ID}/start يدويًا. يقوم تضمين Checkify JavaScript ببدء الجلسة، واستلام request_id، وكتابته في النموذج الخاص بك تلقائيًا.

كل ما يحتاجه نظامك الخلفي هو:

2. استلم معرف الطلب على خادمك

يقوم برنامج SDK في واجهة المستخدم بكتابة مُعرّف الطلب Checkify في حقل نموذج مخفي بعد إتمام المستخدم لعملية التحقق. اسم الحقل الافتراضي هو checkify_token، وهو اسم الحقل وليس نوعًا منفصلاً من الرموز المميزة. يتم إرسال قيمة الحقل إلى نقطة نهاية التحقق كمعرّف الطلب.

قد تُعيد عملية تسليم تطبيق الهاتف المحمول قيمة checkify_request_id في عنوان URL للصفحة. يقرأها SDK عند التحميل؛ ويظل خادمك يتحقق من قيمة request_id نفسها.

إرسال النموذج من واجهة المستخدم الخاصة بك

{
  "email": "user@example.com",
  "checkify_token": "56a57761-ff5b-42f0-9c97-6c13e223e017"
}

تحقق من الطلب من الواجهة الخلفية الخاصة بك

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "required_fields": [],
  "consume": true
}

التكامل اليدوي للواجهة الأمامية فقط

3. الاختبار اليدوي باستخدام cURL

لا يستخدم مطورو الواجهة الخلفية عادةً الأمر /start. استخدم هذا القسم فقط عند إنشاء واجهة أمامية مخصصة أو عند الاختبار بدون تضمين المحتوى. ضع علامات اقتباس حول عناوين URL في zsh/bash حتى لا يتم التعامل مع علامة الاستفهام (؟) كنمط عام.

يلزم وجود رأس Origin لـ /start

لا يعمل خيار "Pass Start" إلا من نطاق موقع ويب مسجل. تُرسل المتصفحات عنوان Origin تلقائيًا، بينما لا يفعل cURL ذلك. أرسل Origin (أو X-Checkify-Site-Url) مع اسم مضيف مُدرج ضمن "المواقع" ← "النطاقات المسموح بها". يجب أن يتطابق اسم المضيف تمامًا - فـ checkify.me و www.checkify.me مختلفان.

أكثر مشاكل الاختبار شيوعاً

إذا أعاد الأمر /start رمز HTTP 403، فقد يكون مُعرّف كلمة المرور الخاص بك لا يزال صالحًا. والسبب المعتاد هو أن نطاق الطلب غير مُدرج في النطاقات المسموح بها، أو أن www.example.com مُسجّل ولكن تم استخدام example.com (أو العكس).

استخدم موقع اختبار مخصصًا وقم بتمرير لوحة تحكم Checkify لاختبار التكامل. تستخدم مفاتيح موقع API البادئة csk_؛ لا يوجد تنسيق مفتاح اختبار منفصل. لا تختبر على عملية التحقق من الإنتاج حتى تتأكد من نجاح العملية ورفضها.

# Step A — start a session (replace PASS_ID and YOUR_REGISTERED_DOMAIN)
curl -sS \
  -H "Accept: application/json" \
  -H "Origin: https://YOUR_REGISTERED_DOMAIN" \
  "https://checkify.me/v1/qr/pass/chk_live_YOUR_PASS_ID/start?request_type=human"

# Response includes request_id and qr_url — open qr_url and complete verification

# Step B — verify on your server (after the user completes verification)
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "PASTE_request_id_FROM_STEP_A",
    "required_claims": ["human_verified"],
    "consume": true
  }'

استخدم مفتاح موقعك API فقط عند إجراء عملية التحقق. أكمل عملية التحقق في التطبيق قبل إجراء عملية التحقق، وإلا ستظهر لك حالة "معلق".

المطالبات المطلوبة حسب حالة الاستخدام

قم بتعيين required_claims لتتوافق مع الإثبات المطلوب لإجراءك المحمي. يجب أن تتطابق أسماء المطالبات مع ما وافق عليه Checkify لجلسة التحقق تلك. تستخدم عمليات التحقق من العمر age_over_{N} (على سبيل المثال age_over_18). يتم دعم العتبات الديناميكية من 10 إلى 110 عندما يطلب التطبيق المضمن نوع الطلب المطابق.

حالة الاستخدام المطالبات المطلوبة المقترحة ملحوظات
استبدال البوت / CAPTCHA ["human_verified"] يؤكد أن مستخدمًا حقيقيًا أكمل عملية Checkify.
محتوى مخصص لمن هم فوق سن 13 عامًا أو منتجات موجهة للشباب ["age_over_13"] استخدم هذا عندما يطلب تصريحك العمر فوق 13 عامًا.
محتوى لمن هم فوق 16 عامًا أو قواعد السن الإقليمية ["age_over_16"] استخدم هذا عندما يطلب تصريحك العمر فوق 16 عامًا.
السجائر الإلكترونية، أو الكحول، أو من هم فوق سن 18 عامًا. ["age_over_18"] قم بمطابقة الفئة العمرية مع منتجك وسوقك.
المنتجات المخصصة لمن هم فوق سن 21 عامًا (إن وجدت) ["age_over_21"] استخدم هذا عندما يطلب تصريحك العمر فوق 21 عامًا.
تحدي سن 25 أو سياسة بيع بالتجزئة أكثر صرامة ["age_over_25"] استخدم هذا عندما يطلب تصريحك العمر فوق 25 عامًا.
عتبة عمرية مخصصة ["age_over_N"] استخدم age_over_N حيث N هي 10–110، بما يتوافق مع نوع طلب التضمين الخاص بك.

نوع طلب التضمين ← مطالبة الخادم

يجب أن يتطابق نوع طلب المتصفح مع الادعاء الذي تتحقق منه من جانب الخادم.

نوع طلب التضمينالمطالبات المطلوبة
human["human_verified"]
age_over_13["age_over_13"]
age_over_16["age_over_16"]
age_over_18["age_over_18"]
age_over_21["age_over_21"]
age_over_25["age_over_25"]
age_over_N["age_over_N"] (N = 10–110)

الحقول المطلوبة الاختيارية

إلى جانب required_claims، يمكنك طلب حقول هوية معتمدة محددة (مثل البلد أو شريحة العمر) عندما يجمعها تكاملك. مرّر الأسماء في required_fields — إن نقصت من النتيجة المعتمدة يعيد verify رمز missing_required_fields مع missing_fields في error.details.

4. تحقق من الاتصال على خادمك

قم بإجراء طلب POST إلى /v1/qr/results/verify باستخدام مفتاح API الخاص بموقعك قبل منح الوصول. تعامل مع مرجع المتصفح (request_id أو رمز الاستطلاع القديم) على أنه غير موثوق به حتى يؤكد Checkify النتيجة.

POST https://checkify.me/v1/qr/results/verify
Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "consume": true
}

يمكنك أيضًا إرسال token بدلاً من request_id. يتم تحديد نطاق مفتاح API لموقع Checkify الخاص بك — لا ترسل site_id في نص الطلب.

أمثلة على التنفيذ

# checkify_token from your form POST is sent as request_id
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
    "required_claims": ["human_verified"],
    "consume": true
  }'

متى يُستخدم مصطلح "استهلاك"؟

استخدم خاصية consume: true للإجراءات المحمية النهائية — إتمام عملية الشراء، التسجيل، إعادة تعيين كلمة المرور، الشراء المقيد بالعمر، الوصول إلى المحتوى المحمي

استخدم consume: false فقط لـ — الاختبار، أو تصحيح الأخطاء، أو عمليات التحقق غير النهائية حيث يجب التحقق من النتيجة مرة أخرى لاحقًا

بالنسبة للإجراءات المنظمة أو عالية المخاطر، يُفضل استخدام consume: true حتى لا يمكن إعادة استخدام نتيجة التحقق نفسها لقرارات محمية متعددة.

تم إغلاق الملف بسبب الإجراءات المنظمة

إذا لم يتمكن نظامك الخلفي من الوصول إلى Checkify، فلا تسمح بالدفع المقيد بالعمر، أو الوصول إلى المقامرة، أو الوصول إلى المحتوى المخصص للبالغين، أو شراء السجائر الإلكترونية أو الكحول، أو غيرها من الإجراءات المحمية دون نتيجة مؤكدة من جانب الخادم.

استخدم مهلات HTTP قصيرة (مثلاً 10 ثوانٍ). أعد المحاولة مرة أو مرتين في حالة حدوث أخطاء 5xx عابرة أو أخطاء في الشبكة، ثم امنع الوصول. سجّل الحوادث على الخادم واعرض رسائل آمنة للمستخدم. لا تكشف تفاصيل أخطاء Checkify الداخلية للعملاء.

try {
  const verdict = await verifyCheckifyResult(requestId);

  if (!verdict.allow) {
    return res.status(403).json({ error: "Verification required" });
  }

  // Continue protected action
} catch (err) {
  console.error("Checkify verification unavailable", err);

  return res.status(403).json({
    error: "Verification is temporarily unavailable. Please try again.",
  });
}

خادم SDKs وأدواته

The Checkify monorepo includes @checkify/server (Node.js) and checkify-server (Python) packages for server-side verify calls. There is no published OpenAPI spec or Postman collection yet — use the examples on this page and POST /v1/qr/results/verify directly.

تم نشر الإصدار 1.0.0 من @checkify/server على منصة npm. تأتي حزمة checkify-server الخاصة بلغة Python ضمن مستودع Checkify SDK الأحادي.

نافذة انتهاء صلاحية النتائج

تنتهي صلاحية عمليات التحقق المكتملة بعد QR_RESULT_MAX_AGE_SECONDS (القيمة الافتراضية 900 ثانية / 15 دقيقة). بعد انتهاء الصلاحية، تُرجع عملية التحقق result_expired، مما يستدعي من المستخدم إعادة التحقق.

نقاط نهاية استطلاع الحالة (واجهات أمامية مخصصة)

تتولى الدالتان JavaScript و SDK إدارة حالة الجلسة للتطبيقات المضمنة القياسية. استخدم هاتين الدالتين فقط عند إنشاء واجهة أمامية مخصصة تستدعي الأمر GET /v1/qr/pass/{pass_id}/start يدويًا.

معالجة الاستجابة

عند نجاح العملية، يُعيد Checkify رمز HTTP 200 مع قيمة النجاح: true والحالة: مكتمل. يُسمح بالوصول فقط عند وجود البيانات المطلوبة (على سبيل المثال، human_verified: true).

{
  "success": true,
  "status": "completed",
  "message": "Verification result confirmed",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "site_id": "YOUR_SITE_ID",
  "business_id": "YOUR_BUSINESS_ID",
  "approved_claims": {
    "human_verified": true
  },
  "approved_fields": [],
  "signed_result": {
    "payload": { "...": "..." },
    "signature": "...",
    "signature_algorithm": "EdDSA",
    "key_id": "checkify:default"
  }
}

النتيجة الموقعة

يتيح كائن signed_result لخادمك الاحتفاظ بسجل تدقيق مقاوم للتلاعب بأن Checkify وافق على المطالبة المطلوبة وقت التحقق. معظم التكاملات تحتاج فقط إلى approved_claims. قد تخزّن الشركات الخاضعة للتنظيم أو عالية المخاطر signed_result أيضًا. قد يتضمن proof_metadata المتداخل أدلة تشفيرية أو تشغيلية (مثل بيانات assurance وأنواع الأدلة أو تجزئات الموافقة) — وليس وثائق الهوية أو تاريخ الميلاد الخام. لا تعامل حقول assurance المتداخلة كشهادة أو ضمان ثقة؛ راجع certification_status وسياستك. لا تخزّن معلومات شخصية أكثر مما يلزم.

إذا لم يُنهِ العميل استخدام التطبيق بعد، فإنّ Checkify يُعيد رمز HTTP 200 مع رسالة النجاح: خطأ والحالة: معلق. امنع الإجراءات المحمية واطلب من المستخدم إكمال عملية التحقق.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
الحقلالمعنى
successtrue عند اكتمال التحقق ومطابقة المتطلبات
statuscompleted أو pending
approved_claimsالمطالبات Checkify المعتمدة، على سبيل المثال. human_verified: true
signed_resultالحمولة الموقعة الاختيارية لمسارات التدقيق

حمولات أخطاء JSON

عند تعذر إتمام عملية التحقق، يُعيد Checkify رمز HTTP 4xx/5xx مع نص JSON مُهيكل. تحقق من رمز الخطأ (error.code) وسجل تفاصيل الخطأ (error.details) على الخادم. أرسل رسائل عامة إلى المستخدمين النهائيين.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
شفرة HTTP معنى الإجراء الموصى به
missing_authorization401لم يتم إرسال أي ترويسة تفويض.إرسال التفويض: Bearer YOUR_SITE_API_KEY من كود جانب الخادم فقط.
invalid_token401رمز الحامل مفقود أو مشوه أو ليس مفتاح موقع صالح API.تحقق من المفتاح في لوحة معلومات أعمالك وقم بتخزينه في متغيرات البيئة.
expired_token401تم إلغاء مفتاح الموقع API.قم بإنشاء مفتاح موقع جديد API وقم بتدويره على خوادمك.
missing_required_field400 / 422معرف الطلب أو الرمز المميز مفقود من نص JSON.قم بتمرير request_id من حقل النموذج المخفي، أو رمز الاستطلاع إذا كان التكامل الخاص بك لا يزال يستخدمه.
invalid_request_id400تعذر تحليل المرجع أو أنه فارغ بعد التطبيع.تأكد من أن واجهة المستخدم الخاصة بك ترسل طلب Checkify request_id دون تغيير.
result_not_found404لا يوجد طلب تحقق لهذا المرجع.ارفض الإجراء. ربما يكون المستخدم قد عبث بالحقل المخفي أو أرسل جلسة قديمة.
result_expired410لقد تم التحقق منذ فترة طويلة جدًا بحيث لا يمكن الوثوق به في هذا الإجراء.اطلب من المستخدم إجراء المسح مرة أخرى واستدعاء التحقق باستخدام معرف الطلب الجديد.
verification_failed403 / 409عدم تطابق الموقع/النشاط، أو نتيجة مستهلكة مسبقًا (HTTP 409)، أو فشل تحقق عام.ارفض الوصول. افحص error.details. لفجوات المطالبات/الحقول راجع missing_required_claims و missing_required_fields.
missing_required_claims403developers_server.err_missing_required_claims_meaningdevelopers_server.err_missing_required_claims_action
missing_required_fields403developers_server.err_missing_required_fields_meaningdevelopers_server.err_missing_required_fields_action
unknown_required_attributes400developers_server.err_unknown_required_attributes_meaningdevelopers_server.err_unknown_required_attributes_action
business_not_operational403الحساب التجاري مغلق أو مؤرشف أو غير فعال.تواصل مع صاحب العمل أو مع دعم Checkify. لا تسمح بالإجراءات المحمية حتى يتم تفعيل الحساب.
validation_errors422فشل التحقق من صحة مخطط JSON body (HTTP 422).افحص ملف error.details.validation_errors بحثًا عن رسائل على مستوى الحقول. أصلح أنواع request_id و required_claims و required_fields قبل إعادة المحاولة.
rate_limited429عدد كبير جدًا من طلبات التحقق في فترة زمنية قصيرة.أعد المحاولة مع التراجع الأسي. تحقق فقط عند الإجراءات المحمية، وليس في كل عرض للصفحة.
server_error500+لم يتمكن برنامج Checkify من إكمال عملية التحقق بسبب مشكلة مؤقتة في الخادم.أعد المحاولة مرة أو مرتين، ثم أغلق العملية في حالة الفشل وقم بتسجيل الحادثة.

روابط الويب والتحقق غير المتزامن

اليوم، تتم عملية التحقق من الخادم بشكل متزامن: حيث يتحقق نظامك الخلفي من مُعرّف الطلب (request_id) عندما يُرسل المستخدم الإجراء المحمي. يُعد هذا النهج هو المُوصى به لعمليات الدفع والتسجيل والتحكم في الوصول. لا تتطلب عمليات التكامل القياسية استخدام روابط الويب العامة للتحقق. قد تستخدم GoHighLevel وعمليات التكامل مع الشركاء الآخرين إعدادات منفصلة لروابط الويب الصادرة في لوحة تحكم الأعمال.

الأخطاء الشائعة

تذكير الأمان

تعامل مع الحقل المخفي كمرجع غير موثوق به، وليس كدليل. تحقق دائمًا باستخدام مفتاح موقعك API الموجود على الخادم قبل منح الوصول. استخدم consume: true لإجراءات لمرة واحدة مثل الاشتراك أو إعادة تعيين كلمة المرور.

الخطوات التالية