Bounty API Капча

Служебный модульверсия 26.10.18

Документация · Bounty Captcha

Собственная капча сервиса: ползунок-пазл во всех формах (Р-481), мозаика 3×3 — запасной вид. Задание показывается только по подозрению (Р-277, Р-466).

3 эндпоинта1 разделhttps://captcha.mybounty.org/v1

OpenAPI JSON Попробовать в Swagger
Разделы и поиск · 1

Как пользоваться

Как подключить

  1. Задание. Форма с подозрением просит GET /v1/new — по умолчанию ползунок. В ответе кадр, фрагмент и его высота; место паза по горизонтали не отдаётся.
  2. Человек решает. Ответ — доля хода ручки от 0 до 1000 целым числом. Браузер отдаёт его POST /v1/solve: верно — «Капча пройдена», промах — задание удалено, сразу просите новое.
  3. Сервер сверяет. Форма уходит в ваш API вместе с captcha_id и captcha_answer; API зовёт POST /v1/verify с заголовком X-Captcha-Secret. Засчитывается задание один раз — второй verify вернёт ok: false.

Правила

  • Задание живёт 10 минут и засчитывается один раз; неверный ответ в /v1/solve удаляет его сразу.
  • Допуск ползунка — 40 из 1000 (около 4 % хода ручки) в обе стороны.
  • Выдача — 120 заданий в час на адрес; проверка — 600 в час.
  • Сервис капчи недоступен — форма отклоняется с понятной ошибкой: пропускать всех на время сбоя значит открыть регистрацию ботам ровно на этот срок.
  • Демонстрация — /visual, только вне релиза.

Капча

3 эндпоинта

Выдать задание (GET /v1/new), проверить решение в браузере (POST /v1/solve) и засчитать его на сервере формы (POST /v1/verify, общий секрет). Вход не нужен.

GET/v1/new Выдаёт новое задание: ползунок-пазл, по запросу — мозаику 3×3 Без входа

Кадр пазла (768×432) клиент вписывает в сцену той же пропорции 16:9: положение фрагмента задаётся долями, поэтому кадр не растягивается и фрагмент совпадает с пазом на любой ширине. Место паза по горизонтали не отдаётся — его и надо найти.

Нечитаемое задание клиент меняет повторным вызовом этого же эндпоинта, а не перезагрузкой формы: перезагрузка стирает уже введённые почту и пароль. Язык задания мозаики — lang, иначе Accept-Language, иначе английский (Р-062).

Параметры

kind запрос · slider | mosaic

Вид задания: ползунок (по умолчанию) или мозаика

lang запрос · string или null

Язык задания мозаики

Ответы

200Успешный ответ · NewResponse

Поля ответа · 11

id string обязательно

Идентификатор задания — уходит вместе с ответом

kind string обязательно

Вид задания: slider или mosaic

ttl integer обязательно

Сколько секунд задание действительно

image string или null

Кадр пазла в виде data-URI (768 × 432)

piece string или null

Фрагмент пазла в виде data-URI

piece_top integer или null

Y фрагмента; X паза не отдаётся

piece_width integer или null

Сторона фрагмента в пикселях

canvas_width integer или null

Ширина кадра пазла

canvas_height integer или null

Высота кадра пазла

images массив string или null

Девять плиток мозаики

prompt string или null

Задание мозаики на языке человека

400Неверные параметры или тело запроса — validation_error; в details.fields — какие поля

429Слишком часто — rate_limited. Подождите столько секунд, сколько в заголовке Retry-After

500Сбой на стороне сервиса — internal_error; request_id — для поддержки

Пример

curl -X GET 'https://captcha.mybounty.org/v1/new'
POST/v1/solve Проверяет решение для браузера: верно ли решено задание Без входа

Ответ нужен, чтобы человек сразу увидел «Капча пройдена» или новое задание, а не узнал о промахе, отправив всю форму. Попытка одна: неверный ответ удаляет задание, верный помечает его решённым — и засчитать его по-прежнему может только сервер формы (/v1/verify) с тем же ответом. Сказать «пройдено» за сервер браузер так не может.

Тело запросаAnswerRequest · application/json

id string обязательно

Идентификатор задания из /v1/new

answer string обязательно

Ползунок — доля хода ручки 0…1000 целым числом; мозаика — номера плиток через запятую

Ответы

200Успешный ответ · VerifyResponse

Поля ответа · 1

ok boolean обязательно

Решено ли задание

400Неверные параметры или тело запроса — validation_error; в details.fields — какие поля

429Слишком часто — rate_limited. Подождите столько секунд, сколько в заголовке Retry-After

500Сбой на стороне сервиса — internal_error; request_id — для поддержки

Пример

curl -X POST 'https://captcha.mybounty.org/v1/solve' \
  -H 'Content-Type: application/json' \
  -d '{"id": "…", "answer": "…"}'
POST/v1/verify Засчитывает решение — только сервер формы, по общему секрету Без входа

Задание удаляется при первом вызове, каким бы ни был ответ. Решённое в браузере (/v1/solve) засчитывается только с тем же ответом; не решённое там — проверяется здесь. Без секрета — 403: иначе браузер мог бы сам сказать «капча пройдена».

Параметры

x-captcha-secret заголовок · string

Общий секрет из .env (CAPTCHA_SHARED_SECRET)

Тело запросаAnswerRequest · application/json

id string обязательно

Идентификатор задания из /v1/new

answer string обязательно

Ползунок — доля хода ручки 0…1000 целым числом; мозаика — номера плиток через запятую

Ответы

200Успешный ответ · VerifyResponse

Поля ответа · 1

ok boolean обязательно

Решено ли задание

400Неверные параметры или тело запроса — validation_error; в details.fields — какие поля

429Слишком часто — rate_limited. Подождите столько секунд, сколько в заголовке Retry-After

500Сбой на стороне сервиса — internal_error; request_id — для поддержки

Пример

curl -X POST 'https://captcha.mybounty.org/v1/verify' \
  -H 'Content-Type: application/json' \
  -d '{"id": "…", "answer": "…"}'