Документация API

DevShield API v1 — антиспам, антибот и защита админки для любого сайта.

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

1. Зарегистрируйтесь и добавьте сайт в дашборде.
2. Скопируйте API-ключ (ds_...).
3. Вставьте виджет на сайт:

<script async src="https://devshield.ru/widget.js" data-key="ds_ваш_ключ"></script>

Готово. Все формы на сайте теперь защищены.

Аутентификация

API-ключ (для /api/check и /api/admin-check)

Передаётся в теле запроса как api_key:

{
  "api_key": "ds_ваш_ключ",
  ...
}

JWT (для дашборда и /api/billing, /api/ip-lists)

Cookie access_token (httpOnly, 15 мин) + refresh_token. Токен выдаётся при логине через POST /api/auth/login.

POST /api/check

Основной эндпоинт проверки форм.

Параметры запроса

Ответ

{
  "verdict": "ham",     // "ham" | "challenge" | "spam"
  "score": 15,          // 0-100
  "checks": [
    { "name": "honeypot", "passed": true, "score": 0 },
    { "name": "time_check", "passed": true, "score": 0 },
    { "name": "ip_reputation", "passed": true, "score": 0, "detail": "IP чист" }
  ],
  "challenge": { ... }  // только при verdict=challenge
}

POST /api/admin-check

Защита страницы входа от брутфорса.

Параметры

Ответ

// Разрешено
{ "verdict": "allow", "remaining_attempts": 3 }

// Заблокировано
{ "verdict": "block", "reason": "Превышен лимит попыток входа" }

IP-списки

Белый и чёрный список IP-адресов. Поддержка CIDR (например, 192.168.0.0/24).

GET /api/ip-lists

Получить все записи тенанта. Требует JWT.

POST /api/ip-lists

{
  "ip": "1.2.3.4",           // или "10.0.0.0/24"
  "type": "whitelist",       // "whitelist" | "blacklist"
  "site_id": null,           // null = все сайты
  "note": "Офисный IP"
}

DELETE /api/ip-lists?id=UUID

Удалить запись по ID.

Логика проверки

Whitelist — мгновенный ham (score 0). Blacklist — мгновенный spam (score 100). Проверка происходит до всех остальных scoring-чеков.

Биллинг

POST /api/billing/subscribe

Создать подписку. Требует JWT.

{ "plan": "business" }  // "start" | "business" | "agency"

// Ответ:
{ "redirect_url": "https://yoomoney.ru/checkout/...", "payment_id": "..." }

POST /api/billing/webhook

Webhook от ЮKassa. Публичный (без авторизации). Обрабатывает payment.succeeded и payment.canceled.

POST /api/billing/cancel

Отмена подписки. Требует JWT.

GET /api/billing/history

История платежей и текущая подписка. Требует JWT.

Тарифы

Скоринг и вердикты

Баллы проверок

Вердикты

Коды ошибок

JS-виджет

Автоматически защищает все формы на странице.

Установка

<script async src="https://devshield.ru/widget.js" data-key="ds_ваш_ключ"></script>

Что делает

• Добавляет скрытое honeypot-поле в каждую форму
• Замеряет время заполнения формы
• Собирает поведенческие данные (mouse, keys, clicks, scroll, touch)
• Запускает BotD-детекцию
• Генерирует fingerprint хеш
• Отправляет данные на /api/check при submit
• Блокирует отправку при вердикте spam
• Прозрачно решает PoW-challenge при challenge

Настройки

<script async
  src="https://devshield.ru/widget.js"
  data-key="ds_ваш_ключ"
  data-mode="passive"         <!-- "active" (блокирует) | "passive" (только логирует) -->
></script>

WordPress-плагин

Официальный плагин для WordPress. Устанавливается через wp-admin.

Установка

1. Скачайте zip с devshield.ru/downloads/
2. WordPress → Плагины → Добавить → Загрузить
3. Активируйте, введите API-ключ в настройках

Возможности

• Защита комментариев, Contact Form 7, WPForms
• Защита wp-login.php от брутфорса
• Автоматическая вставка виджета
• Настройки в WP-admin → Настройки → DevShield

PHP SDK

Composer-пакет для vanilla PHP, WordPress и 1С-Битрикс.

composer require devorra/devshield-php

Проверка формы

$ds = new \Devorra\DevShield\DevShield('ds_ваш_ключ');

$result = $ds->checkForm([
    'form_data' => [
        'name'  => $_POST['name'],
        'email' => $_POST['email'],
    ],
    'honeypot'   => $_POST['__ds_hp'] ?? '',
    'time_spent' => $_POST['__ds_ts'] ?? 0,
]);

if ($result['verdict'] === 'spam') {
    http_response_code(403);
    die('Спам');
}

Защита входа

$ds = new \Devorra\DevShield\DevShield('ds_ваш_ключ');

$ip = \Devorra\DevShield\DevShield::getClientIp();
$result = $ds->checkLogin($ip, $_POST['login'] ?? null);

if ($result['verdict'] === 'block') {
    die('Заблокировано: ' . $result['reason']);
}

1С-Битрикс

// /local/php_interface/init.php
AddEventHandler('main', 'OnBeforeEventSend', function (&$arFields) {
    $ds = new \Devorra\DevShield\DevShield('ds_ваш_ключ');
    $result = $ds->checkForm(['form_data' => $arFields]);
    if ($result['verdict'] === 'spam') return false;
});

FAQ

Где хранятся данные?

В России (Timeweb). Соответствие 152-ФЗ.

Нужна ли CAPTCHA?

Нет. DevShield работает без CAPTCHA — невидимо для пользователя.

Что происходит при вердикте challenge?

Виджет автоматически решает Proof-of-Work задачу (0.5-2 сек). Пользователь ничего не делает.

Как работает без JavaScript?

Используйте PHP SDK или прямые API-вызовы из бэкенда. Виджет не обязателен.

Как отключить проверку одноразовых email?

В дашборде → настройки тенанта. Или через API: поле disposableEmailBlock в tenant.

Поддерживается ли IPv6?

IP-репутация работает с IPv4. IPv6 поддерживается в белых/чёрных списках.

Как связаться с поддержкой?

Email: info@devorra.ru, Telegram: поддержка через бот.