Документация СВАЙПЕР — API, интеграция, примеры кода
Возможности Как подключить Сравнение Тарифы Документация Начать бесплатно
Быстрый старт Widget.js Формы и заявки Конфигурация API Endpoints POST /challenge POST /verify POST /check Примеры кода PHP Python Node.js Коды ошибок FAQ

Быстрый старт

Подключение СВАЙПЕРА занимает три шага. Вам нужен только email для регистрации — телефон и привязка карты не требуются.

Шаг 1: Регистрация

Перейдите на страницу регистрации и введите email. В кабинете создайте сайт — получите site-key и готовый код вставки.

Шаг 2: Вставьте скрипт

Добавьте одну строку в <body> вашего сайта, перед закрывающим </body>:

<script src="https://verifsite.ru/widget.js"
    data-site-key="ваш_ключ_с_сайта"
    data-mode="hard"
    data-lang="ru"></script>

Шаг 3: Верификация на сервере

После успешного свайпа widget отправляет событие slider-captcha:passed с токеном в event.detail.token. Проверьте токен через introspect (рекомендуется) или check:

// PHP — introspect (нужен site-secret, только на сервере)
$ch = curl_init('https://verifsite.ru/api/v1/introspect');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'siteKey' => 'ваш_ключ',
  'token' => $token
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'X-Site-Secret: ваш_секрет'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
if (!empty($result['valid'])) { /* человек */ }

Widget.js

Самодостаточный скрипт без jQuery и фреймворков. При загрузке показывает оверлей со слайдером. После успеха — событие slider-captcha:passed и сохранение токена в localStorage.

Как это работает

1. Пользователь открывает страницу → widget запрашивает challenge. 2. Тянет слайдер → verify на сервере. 3. При успехе — токен в window.__sliderCaptcha и событие для вашего JS/аналитики.

Событие для интеграции

window.addEventListener('slider-captcha:passed', function (e) {
  console.log('token', e.detail.token);
  // передайте токен на сервер или разблокируйте форму
});

Интеграция с формой

Для заявок, обратной связи и регистрации удобнее показывать капчу при отправке формы, а не при загрузке всей страницы. В кабинете: сайт → настройки → «Только при отправке формы (form-gate)».

Шаг 1: Виджет с режимом form-gate

Вставьте перед </body>. Атрибуты data-trigger="form" и data-form-selector подставляются автоматически, если вы настроили это в личном кабинете.

<script src="https://verifsite.ru/widget.js"
    data-site-key="ваш_ключ"
    data-api="https://verifsite.ru"
    data-mode="soft"
    data-trigger="form"
    data-form-selector="#order-form"
    data-lang="ru"></script>

data-mode="soft" рекомендуется для страниц с формами — не блокирует всю страницу до свайпа. data-form-selector необязателен: без него защищаются все <form> на странице.

Шаг 2: Скрытое поле в форме

Токен не попадает в POST автоматически — добавьте скрытое поле и заполните его после свайпа.

<form id="order-form" action="/send.php" method="post">
  <input type="hidden" name="captcha_token" id="captcha_token">
  <input type="tel" name="phone" required>
  <button type="submit">Отправить</button>
</form>

Шаг 3: Передача токена (JS)

<script>
window.addEventListener('slider-captcha:passed', function (e) {
  var field = document.getElementById('captcha_token');
  if (field) field.value = e.detail.token;
});
</script>

После успешного свайпа виджет повторно отправит форму. Токен также доступен в window.__sliderCaptcha.token.

Шаг 4: Проверка на сервере

Без серверной проверки бот может отправить POST напрямую, минуя капчу. Используйте POST /api/v1/introspect с X-Site-Secret (только на бэкенде):

<?php
$token = $_POST['captcha_token'] ?? '';

$ch = curl_init('https://verifsite.ru/api/v1/introspect');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-Site-Secret: ' . $siteSecret
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'siteKey' => $siteKey,
    'token' => $token
  ])
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($result['valid'])) {
  http_response_code(403);
  exit('Капча не пройдена');
}
// обработка заявки

AJAX-форма

document.getElementById('order-form').addEventListener('submit', async function (e) {
  e.preventDefault();
  var token = window.__sliderCaptcha && window.__sliderCaptcha.token;
  if (!token) { alert('Пройдите капчу'); return; }
  await fetch('/api/submit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone: e.target.phone.value, token: token })
  });
});

Как это работает (form-gate)

  1. Пользователь заполняет форму и нажимает «Отправить».
  2. Виджет перехватывает submit и показывает капчу (если токена ещё нет).
  3. После свайпа форма отправляется повторно автоматически.
  4. Сервер проверяет captcha_token через introspect.

Конфигурация

Все параметры задаются через data-атрибуты или объект config в ручном режиме.

Параметр Тип Описание
data-site-key string Обязательный. Ваш site-key из личного кабинета.
data-mode string soft — оверлей без блокировки скролла. hard — страница заблокирована до прохождения. По умолчанию hard.
data-lang string ru / en. Язык интерфейса капчи. По умолчанию ru.
data-api string URL API для верификации. По умолчанию https://verifsite.ru.
data-fail-open boolean Если 1 — при ошибке API страница не блокируется. По умолчанию 0 (fail-closed).
data-url-param string Имя GET-параметра в URL после успеха (например captcha_solved=1). Необязательно.
data-trigger string page — капча при загрузке (по умолчанию). form — только при отправке формы. См. интеграцию с формой.
data-form-selector string CSS-селектор формы при data-trigger="form". Пример: #order-form, .callback-form. Пусто — все формы.
data-token-storage string local (по умолчанию) или session — где хранить токен после свайпа.

API Endpoints

REST API для серверной верификации токенов. Все запросы — HTTPS, JSON, авторизация по site-key.

POST /api/v1/challenge
POST /api/v1/verify
POST /api/v1/check
POST /api/v1/introspect
POST /api/v1/widget-config

POST /api/v1/challenge

Создаёт новый вызов капчи. Вызывается автоматически widget.js при загрузке страницы.

Request

POST /api/v1/challenge
Content-Type: application/json

{
  "siteKey": "ваш_ключ"
}

Response

{
  "ok": true,
  "challengeId": "uuid...",
  "expiresInMs": 120000
}

POST /api/v1/verify

Отправляет траекторию свайпа. Вызывается widget.js после жеста пользователя. Возвращает подписанный токен.

Request

POST /api/v1/verify
Content-Type: application/json

{
  "siteKey": "ваш_ключ",
  "challengeId": "uuid...",
  "finalRatio": 0.98,
  "points": [[0, 0, 0], ...]
}

Response

{
  "ok": true,
  "token": "signed.jwt...",
  "expiresAt": 1730000000
}

POST /api/v1/check

Проверка токена (без site-secret). Подходит для быстрой валидации с фронтенда или бэкенда.

Request

POST /api/v1/check
Content-Type: application/json

{
  "siteKey": "ваш_ключ",
  "token": "токен_от_widget"
}

Response

{
  "ok": true,
  "expiresAt": 1730000000
}

Примеры кода

Готовые примеры интеграции для популярных языков и платформ.

PHP

<?php

$ch = curl_init('https://verifsite.ru/api/v1/introspect');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'siteKey' => $siteKey,
  'token' => $token
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'X-Site-Secret: ' . $siteSecret
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($response['valid'])) {
  process_form($_POST);
} else {
  http_response_code(403);
}

Python

# Flask пример
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
SITE_KEY = 'ваш_ключ'
SITE_SECRET = 'ваш_секрет'

@app.route('/submit', methods=['POST'])
def submit():
  token = request.form.get('token') or request.json.get('token')

  resp = requests.post('https://verifsite.ru/api/v1/introspect', json={
    'siteKey': SITE_KEY,
    'token': token
  }, headers={'X-Site-Secret': SITE_SECRET})

  result = resp.json()

  if result.get('valid'):
    return jsonify({'status': 'ok'})
  return jsonify({'status': 'blocked'}), 403

Node.js / Express

// Express пример
const express = require('express');
const fetch = require('node-fetch');
const app = express();
app.use(express.urlencoded({ extended: true }));

const SITE_KEY = 'ваш_ключ';
const SITE_SECRET = 'ваш_секрет';

app.post('/submit', async (req, res) => {
  try {
    const check = await fetch('https://verifsite.ru/api/v1/introspect', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Site-Secret': SITE_SECRET
      },
      body: JSON.stringify({
        siteKey: SITE_KEY,
        token: req.body.token
      })
    });

    const result = await check.json();

    if (result.valid) {
      res.json({ status: 'ok' });
    } else {
      res.status(403).json({ status: 'blocked' });
    }
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

Коды ошибок

КодHTTPОписание
missing_site_key400Не передан siteKey
unknown_site_key400Ключ не найден
origin_not_allowed403Домен не в списке origins
quota_exceeded403Исчерпан месячный лимит проверок
challenge_not_found400Challenge истёк или уже использован
invalid_site_secret401Неверный site-secret (introspect)

Технический FAQ

Компактный скрипт (~15 KB без сжатия). С gzip — около 5 KB.

Нет. widget.js требует JavaScript. Параметр data-fail-open="1" пропускает пользователя при ошибке API.

В кабинете укажите все нужные домены в поле origins (например https://example.com и https://www.example.com). Один site-key может обслуживать несколько origins.

Токен живёт 24 часа (настраивается на сервере). Повторный визит с валидным токеном не показывает капчу снова.

Режим data-fail-open="1": если API СВАЙПЕРА недоступен, страница не блокируется. Используйте только если отказ капчи хуже пропуска ботов.