---
type: how-to
title: التكامل على جانب الخادم
summary: خذ الرمز caputchin-token من إرسالية وأكّده بـ /siteverify قبل أن تثق بالطلب.
---

تسلّم الأداة المتصفّح رمزًا للاستخدام مرة واحدة. لا يثبت ذلك الرمز شيئًا حتى يؤكّده خادمك مع Caputchin. هذه الخطوة هي التي تحوّل تحديًا مرئيًّا إلى حماية حقيقية، وهي نداء HTTPS واحد.

تحتاج إلى خادم خلفي قادر على إجراء طلب صادر، وسرّ مفتاح موقعك (`cpt_sec_...`) متاحًا هناك، لا في المتصفّح أبدًا.

## 1. اقرأ الرمز

حين يرسل النموذج، يستقبل معالِجك حقلًا إضافيًّا واحدًا إلى جانب حقولك: `caputchin-token`. حقنته الأداة في النموذج حين اجتاز الزائر التحدّي.

## 2. أكّده بـ /siteverify

أرسِل POST بالرمز وسرّك. الطلب والاستجابة مصاغان على هيئة `siteverify` الخاص بـ reCAPTCHA، فينتقل تكامل قائم بقليل من التغيير:

```http
POST https://verify.caputchin.com/v1/siteverify
Content-Type: application/json

{ "secret": "cpt_sec_...", "response": "<caputchin-token>" }
```

```js
// Node 18+
const verdict = await fetch("https://verify.caputchin.com/v1/siteverify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    secret: process.env.CAPUTCHIN_SECRET,
    response: token,
  }),
}).then((r) => r.json());

if (!verdict.success) {
  // reject the submission
}
```

النداء نفسه بلغات أخرى موجود في [أمثلة تكامل الخادم الخلفي](/docs/integration-guides/backend-examples).

## 3. اقرأ الاستجابة

```json
{
  "success": true,
  "error-codes": [],
  "platform": { "game_id": "caputchin/games/leaf-memory", "score": 847, "duration_ms": 4200 }
}
```

- **`success`** هو الشيء الوحيد الذي تتفرّع عليه. `true` تعني أن زائرًا حقيقيًّا اجتاز التحدّي؛ ثِق بالطلب. `false` تعني أسقطه.
- **`error-codes`** تظهر حين تكون `success` بقيمة `false`، مسمّيةً ما الذي أخفق (رمز مفقود، أو منتهٍ، أو مستخدَم بالفعل، وهكذا).
- **`platform`** بيانات وصفية يدّعيها العميل (أيّ لعبة، والنتيجة، والمدة). قابلة لأن تكون فارغة و**ليست إشارة أمان**. سجّلها للتحليلات إن شئت، لكن لا تحكّم الثقة بالنتيجة أبدًا.

## القواعد التي تحميك

- **الاستخدام لمرة واحدة.** يتحقّق الرمز مرة. إرسال الرمز نفسه ثانيةً يعيد `success: false`، فلا حاجة لأن تتتبّع إعادات التشغيل بنفسك.
- **قصير العمر.** ينتهي الرمز بعد عشر دقائق من إصداره، فتحقّق منه أثناء معالجة الإرسالية، لا في مهمة مؤجَّلة.
- **السرّ يبقى على الخادم.** لا يذهب إلى المتصفّح أبدًا، وهو ما يصادق على النداء.

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

- **التحقّق على جانب العميل.** حدث `pass` ووجود الرمز للتجربة فقط. كل قرار ثقة يحدث هنا، على جانب الخادم، بسرّك.
- **التحكيم بـ `score`.** إنه بيانات وصفية، لا قيمة ثقة.

## أسئلة شائعة

### كم تبقى صلاحية الرمز؟

عشر دقائق بعد إصداره. تحقّق منه أثناء معالجتك للإرسالية، لا من مهمة مؤجَّلة أو طابور قد يعمل لاحقًا.

### هل أستطيع التحقّق من الرمز نفسه مرّتين؟

لا. الرمز للاستخدام مرة واحدة. إرسال الرمز نفسه ثانيةً يعيد `success: false`، فلا حاجة لأن تتتبّع إعادات التشغيل بنفسك.

### هل ينبغي أن أثق بـ `score` أو `game_id`؟

لا. كتلة `platform` (اللعبة، والنتيجة، والمدة) بيانات وصفية يدّعيها العميل وقابلة لأن تكون فارغة. فرّع على `success` وحده، ولا تحكّم الثقة بالنتيجة أبدًا.

### هل أحتاج إلى SDK لهذا؟

لا. الفحص نداء HTTPS واحد من نوع POST إلى `/v1/siteverify`. النداء نفسه في Node وPython وPHP وGo وRuby و.NET وcurl موجود في [أمثلة تكامل الخادم الخلفي](/docs/integration-guides/backend-examples).

## انظر أيضًا

- [أمثلة تكامل الخادم الخلفي](/docs/integration-guides/backend-examples) لهذا النداء بلغتك.
- [التحقّق المُستضاف](/docs/hosted-verification/overview) لتخطّي الخادم الخلفي كليًّا.