Справочник API
Все взаимодействия с сервисом. Базовый адрес: http://jkcaptcha.we4.online. Публичный ключ виджета (jcv4w_…) — на клиенте, секретный API-ключ (jcv4_…) — только на вашем сервере.
Жизненный цикл капчи
1. POST /api/v1/challenge?k=КЛЮЧ_ВИДЖЕТА → { id, width, height }
2. GET /api/v1/frame/{id}?v=N → WebP | 204 (X-Solved: 0|1, X-Version)
3. POST /api/v1/input/{id} → { solved } (перетаскивания)
4. GET /api/v1/status/{id} → { solved, token }
5. GET /api/v1/verify?token=… → { valid } (ваш сервер + X-Api-Key)
Браузеру передаются только кадры и булевы ответы: ни формы фигуры, ни ориентаций, ни камеры. Таймер считает сервер.
POST /api/v1/challenge
Создаёт сессию капчи с настройками виджета. Без параметра k используются настройки по умолчанию (демо).
| Параметр | Где | Описание |
|---|---|---|
k | query | публичный ключ виджета; необязателен |
p | query | метка страницы; пока капча не решена, та же страница получает ту же сессию |
f | query | 1 — принудительно создать новую капчу |
Ответ: { "id": "…", "width": 256, "height": 256 } · лимит: 1/сек · 404, если виджет не найден или выключен.
GET /api/v1/frame/{id}
Текущий кадр сцены в WebP. При v, равном текущей версии, возвращается 204 — это основной режим экономии трафика.
| Параметр | Где | Описание |
|---|---|---|
id | path | идентификатор сессии |
v | query | версия кадра у клиента (из заголовка X-Version) |
Заголовки: X-Version — номер кадра, X-Solved — 1, если капча решена. лимит: 40/сек · 404, если сессия истекла (капча = сессия: 30–60 секунд) · 410, если истекло время ожидания страницы (300 секунд — сессии закрыты, соединение принудительно оборвано).
POST /api/v1/input/{id}
Ввод пользователя: дельты перетаскивания и поведенческие агрегаты. Проверка решения запускается сервером при done: true.
{ "part": "ball" | "figure",
"dx": 12.5, "dy": -4.0, // дельты за батч
"done": false, // true — пользователь отпустил
"ts": 1760000000000, // часы клиента (только телеметрия)
"moves": 24, "activeMs": 380, // агрегаты поведения
"reversals": 3, "jitter": 88.2, "pauses": 1 }
Ответ: { "solved": false } · лимит: 40/сек; попытка решения — 1/сек (429 + Retry-After). Машинные решения отклоняются: капча не засчитывается, в кадре красная вспышка.
GET /api/v1/status/{id}
Статус сессии и подписанный токен (HMAC) после решения.
Ответ: { "solved": true, "token": "…" } · токен действителен 300 секунд · лимит: 5/сек. Остаток времени не передаётся.
GET /api/v1/verify
Серверная проверка токена. Обязателен заголовок X-Api-Key с секретным ключом вашего аккаунта.
Ответ: { "valid": true } · 401 — ключ неверен или аккаунт выключен.
POST /api/v1/beacon/{id} & POST /api/v1/risk
beacon — пассивные сигналы страницы для сессии (webdriver, железо, экран, язык, видимость). risk — проверка без капчи.
POST /api/v1/risk X-Api-Key: jcv4_…
{ "webDriver": false, "hw": 8, "tz": -180, "screenW": 1920, "screenH": 1080,
"touch": false, "lang": "ru", "vis": 0, "elapsedMs": 5200,
"moves": 140, "keys": 6, "clicks": 2, "scrolls": 1 }
→ { "score": 0, "verdict": "human", "flags": [] }
Вердикты: human (< 30), suspicious (30–59), bot (≥ 60). Сессия отклоняется при риске ≥ 60.
GET /api/v1/config
Публичные параметры отображения: текст после решения. С параметром k — текст виджета.
Ответ: { "solvedText": "Проверка пройдена" } · лимит: 1/сек.
Ошибки
| Код | Когда |
|---|---|
401 | неверный X-Api-Key (verify, risk) |
404 | сессия истекла/удалена, виджет не найден |
410 | истекло время ожидания страницы (300 секунд: её сессии закрыты, новые кадры и ввод не принимаются) |
429 | превышен лимит; заголовок Retry-After: 1 |