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

Справочник по доступным endpoints, форматам запросов, параметрам и примерам ответов для интеграции API в ваши приложения.

Графическая капча

reCAPTCHA V2

reCAPTCHA V2 Callback

reCAPTCHA V2 Invisible

reCAPTCHA V3

reCAPTCHA Enterprise

Cloudflare Turnstile

Geetest V3

ALTCHA

CaptchaFox

Capy Puzzle

Friendly Captcha

Использование прокси

Коды ошибок

Эта документация предназначена для разработчиков, которые хотят интегрировать CapSkip напрямую в собственные скрипты, приложения или системы автоматизации. Пользователям стороннего ПО следует обращаться к разделу «Учебники» за инструкциями по настройке.

CapSkip эмулирует API популярных сервисов распознавания капчи, что позволяет ему подключаться к совместимому стороннему ПО без каких-либо модификаций. Для интеграции обычно достаточно просто запустить CapSkip.

В документации описано, как отправлять запросы и получать результаты. CapSkip поддерживает несколько семейств API, включая API в стиле 2Captcha (in.php / res.php), JSON-API createTask / getTaskResult, используемый в AntiCaptcha, CapMonster и CapSolver, а также REST API DeathByCaptcha. Сервисы одного семейства используют одни и те же endpoints, формат запроса и ответа. Различается только базовый URL (хост и порт) для каждого сервиса.

Семейство API	Сервисы
в стиле 2captcha	2captcha.com, rucaptcha.com, solvecaptcha.com, captchas.io
JSON (createTask / getTaskResult)	anti-captcha.com, capmonster.cloud, capsolver.com
DeathByCaptcha	deathbycaptcha.com

Графическая капча

Обычная капча представляет собой изображение с искажённым, но читаемым для человека текстом. Чтобы решить её, пользователь должен ввести текст, показанный на изображении.

Чтобы решить обычную капчу, отправьте изображение HTTP POST-запросом на endpoint API. Отправляйте запрос напрямую в ваш экземпляр CapSkip, используя настроенный локальный адрес и порт, например: http://127.0.0.1:PORT/in.php

CapSkip принимает изображения в формате multipart/form-data или в кодировке Base64.

Пример multipart-формы

<form method="post" action="http://127.0.0.1:PORT/in.php" enctype="multipart/form-data">
<input type="hidden" name="method" value="post">
Your key:
<input type="text" name="key" value="YOUR_APIKEY">
The CAPTCHA file:
<input type="file" name="file">
<input type="submit" value="Upload and get the ID">
</form>

YOUR_APIKEY представляет ваш API-ключ, если в CapSkip включена проверка API-ключа. Если проверка API-ключа отключена, будет принято любое строковое значение.

Пример формы с Base64

<form method="post" action="http://127.0.0.1:PORT/in.php">
<input type="hidden" name="method" value="base64">
Your key:
<input type="text" name="key" value="YOUR_APIKEY">
The CAPTCHA file body in base64 format:
<textarea name="body">BASE64_FILE</textarea>
<input type="submit" value="Upload and get the ID">
</form>

BASE64_FILE содержит данные изображения в кодировке Base64.

Список параметров POST-запроса

Параметр POST	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
method	Строка	Да	post: отправить изображение с помощью multipart/form-data base64: отправьте изображение в виде строки в кодировке Base64
file	Файл	Да*	Файл изображения капчи. * Обязательно, когда method=post.
body	Строка	Да*	Данные изображения капчи в кодировке Base64. * Обязательно, когда method=base64.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста 1: ответ возвращается в формате JSON

Отправка капчи (multipart-загрузка файла):

curl -X POST -F "key=YOUR_API_KEY" -F "method=post" -F "[email protected]" http://127.0.0.1:8080/in.php

Отправить капчу (в кодировке base64):

curl -X POST -d "key=YOUR_API_KEY&method=base64&body=BASE64_IMAGE_DATA" http://127.0.0.1:8080/in.php

После отправки запроса, если всё верно, CapSkip вернёт CAPTCHA ID в виде обычного текста: OK|12345

Если json=1 параметр используется, ответ будет возвращён в формате JSON:

{
"status":1,
"request":"12345"
}

Подождите 1 секунду, затем отправьте HTTP GET-запрос на эндпоинт результата (/res.php) с полученным ID капчи.

Если капча решена, CapSkip вернёт результат в виде обычного текста: OK|TEXT

Если json=1 был указан, ответ будет:

{
"status":1,
"request":"TEXT"
}

Если капча ещё не решена, CapSkip вернёт: CAPCHA_NOT_READY

В этом случае подождите 1 секунду и повторяйте запрос, пока не будет получен окончательный результат. Если CapSkip возвращает пустое тело ответа, значит результат уже был получен или ID не существует. Каждый результат можно прочитать только один раз.

Список параметров GET-запроса

Параметр GET	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
action	Строка	Да	get: получить ответ для отправленной капчи.
id	Целое число	Да	Идентификатор CAPTCHA, возвращаемый `in.php`.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста 1: ответ возвращается в формате JSON

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=CAPTCHA_ID"

reCAPTCHA V2

reCAPTCHA v2, также известная как reCAPTCHA “Я не робот”, представляет собой широко используемый тип капчи. Посетитель ставит галочку, и Google либо сразу пропускает его, либо просит выбрать подходящие изображения, прежде чем форму можно будет отправить.

Чтобы решить reCAPTCHA v2, отправьте googlekey и pageurl параметры вместе с method=userrecaptcha и ваш ключ API CapSkip.

Вы можете получить googlekey одним из следующих способов:

Щёлкните правой кнопкой мыши по виджету reCAPTCHA и выберите Проверить. Найдите URL, который начинается с:

www.google.com/recaptcha/api2/anchor

Скопируйте значение k параметр из этого URL. Либо найдите data-sitekey атрибут в исходном коде страницы и скопируйте его значение.

Получив site key, отправьте HTTP-запрос GET или POST на http://127.0.0.1:PORT/in.php

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
method	Строка	Да	userrecaptcha: указывает на запрос reCAPTCHA v2.
googlekey	Строка	Да	Значение k или data-sitekey параметр, найденный на целевой странице.
pageurl	Строка	Да	Полный URL страницы, на которой расположена reCAPTCHA.
enterprise	Целое число По умолчанию: 0	Нет	1: указывает на reCAPTCHA Enterprise v2. 0: стандартная reCAPTCHA v2.
invisible	Целое число По умолчанию: 0	Нет	1: означает Invisible reCAPTCHA. 0: стандартная reCAPTCHA с флажком.
data-s	Строка	Нет	Значение data-s параметр, найденный на странице. Применимо к Google Search и некоторым сервисам Google.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста. 1: ответ возвращается в формате JSON.
proxy	Строка	Нет	Адрес прокси. Формат для аутентификации по IP: `IP:PORT` (пример: `123.123.123.123:3128`). Формат для аутентификации по логину/паролю: `login:password@IP:PORT`
proxytype	Строка	Нет	Тип прокси. Поддерживаемые значения: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. По умолчанию: `HTTP` когда `proxy` предоставлен, но `proxytype` опущен.

Отправка reCAPTCHA v2 (стандартная):

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com" http://127.0.0.1:8080/in.php

Отправка reCAPTCHA v2 (Invisible):

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&invisible=1" http://127.0.0.1:8080/in.php

Отправка Enterprise reCAPTCHA v2:

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&enterprise=1" http://127.0.0.1:8080/in.php

Отправка Enterprise reCAPTCHA v2 (Invisible):

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&enterprise=1&invisible=1" http://127.0.0.1:8080/in.php

Если запрос успешен, CapSkip вернёт ID капчи в виде простого текста: OK|12345

Если json=1 параметр был использован, ответ будет возвращён в формате JSON:

{
"status":1,
"request":"12345"
}

Если запрос не удался, CapSkip вернёт код ошибки.

Подождите от 15 до 20 секунд, затем отправьте HTTP GET-запрос на endpoint результата, чтобы получить решение: http://127.0.0.1:PORT/res.php

Список параметров GET-запроса

Параметр GET	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
action	Строка	Да	get: получить ответ для отправленной капчи.
id	Целое число	Да	Идентификатор CAPTCHA, возвращаемый `in.php`.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста 1: ответ возвращается в формате JSON

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=CAPTCHA_ID"

Если капча решена, CapSkip ответит в виде обычного текста или JSON и вернёт токен-ответ. Токен будет выглядеть примерно так:

03AHJ_Vuve5Asa4koK3KSMyUkCq0vUFCR5Im4CwB7PzO3dCxIo11i53epEraq-uBO5mVm2XRikL8iKOWr0aG50sCuej9bXx5qcviUGSm4iK4NC_Q88flavWhaTXSh0VxoihBwBjXxwXuJZ-WGN5Sy4dtUl2wbpMqAj8Zwup1vyCaQJWFvRjYGWJ_TQBKTXNB5CCOgncqLetmJ6B6Cos7qoQyaB8ZzBOTGf5KSP6e-K9niYs772f53Oof6aJeSUDNjiKG9gN3FTrdwKwdnAwEYX-F37sI_vLB1Zs8NQo0PObHYy0b0sf7WSLkzzcIgW9GR0FwcCCm1P8lB-50GQHPEBJUHNnhJyDzwRoRAkVzrf7UkV8wKCdTwrrWqiYDgbrzURfHc2ESsp020MicJTasSiXmNRgryt-gf50q5BMkiRH7osm4DoUgsjc_XyQiEmQmxl5sqZP7aKsaE-EM00x59XsPzD3m3YI6SRCFRUevSyumBd7KmXE8VuzIO9lgnnbka4-eZynZa6vbB9cO3QjLH0xSG3-egcplD1uLGh79wC34RF49Ui3eHwua4S9XHpH6YBe7gXzz6_mv-o-fxrOuphwfrtwvvi2FGfpTexWvxhqWICMFTTjFBCEGEgj7_IFWEKirXW2RTZCVF0Gid7EtIsoEeZkPbrcUISGmgtiJkJ_KojuKwImF0G0CsTlxYTOU2sPsd5o1JDt65wGniQR2IZufnPbbK76Yh_KI2DY4cUxMfcb2fAXcFMc9dcpHg6f9wBXhUtFYTu6pi5LhhGuhpkiGcv6vWYNxMrpWJW_pV7q8mPilwkAP-zw5MJxkgijl2wDMpM-UUQ_k37FVtf-ndbQAIPG7S469doZMmb5IZYgvcB4ojqCW3Vz6Q

Если капча ещё не решена, CapSkip вернёт CAPCHA_NOT_READY. В этом случае подождите 5 секунд и повторите запрос. Если CapSkip возвращает пустое тело ответа, результат уже был получен или ID не существует. Каждый результат можно прочитать только один раз.

Найдите элемент с ID g-recaptcha-response и сделайте его видимым, удалив display: none стиль.

Обратите внимание: В некоторых случаях содержимое страницы генерируется динамически, и g-recaptcha-response element may not appear in the static HTML source. In such situations, inspect the page structure using your browser’s developer tools to locate the dynamically generated element.

В качестве альтернативы вы можете использовать JavaScript, чтобы задать значение g-recaptcha-response поле напрямую:

document.getElementById("g-recaptcha-response").innerHTML="TOKEN";

На странице появится поле ввода. Вставьте токен-ответ в это поле и отправьте форму.

reCAPTCHA V2 Callback

В некоторых случаях кнопки отправки нет, и вместо неё используется функция callback. Функция callback выполняется автоматически, когда reCAPTCHA решена.

Список параметров POST- и GET-запросов доступен здесь: Параметры POST- и GET-запросов reCAPTCHA V2

Функция callback обычно определяется в data-callback атрибут виджета reCAPTCHA, например:

data-callback="myCallbackFunction"

В других случаях функция обратного вызова задаётся как callback параметр grecaptcha.render() функция, например:

grecaptcha.render('example', {
'sitekey' : 'someSitekey',
'callback' : myCallbackFunction,
'theme' : 'dark'
});

Ещё один способ найти функцию callback состоит в том, чтобы открыть JavaScript-консоль браузера и изучить объект конфигурации reCAPTCHA:

___grecaptcha_cfg.clients[0].aa.l.callback

Обратите внимание, что aa.l свойство может отличаться, и на странице может быть несколько клиентов reCAPTCHA. В таких случаях вам также следует проверить clients[1], clients[2], и другие записи, чтобы найти нужный объект конфигурации.

Как вариант, вы можете использовать следующий скрипт для автоматического извлечения параметров reCAPTCHA:

function findRecaptchaClients() {
if (typeof (___grecaptcha_cfg) !== 'undefined') {
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([_, value]) => value && typeof value === 'object');objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(([_, value]) => (
value && typeof value === 'object' && 'sitekey' in value && 'size' in value
));
if (typeof toplevel === 'object' && toplevel instanceof HTMLElement && toplevel['tagName'] === 'DIV'){
data.pageurl = toplevel.baseURI;
}
if (found) {
const [sublevelKey, sublevel] = found;data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
return [];
}

Наконец, вызовите функцию callback:

myCallbackFunction();

Или как вариант:

___grecaptcha_cfg.clients[0].aa.l.callback();

В некоторых случаях функция callback требует аргумент. В большинстве ситуаций в качестве этого аргумента следует передавать решённый токен. Например:

myCallbackFunction('TOKEN');

reCAPTCHA V2 Invisible

У reCAPTCHA v2 также есть режим Invisible. Пример можно посмотреть здесь:

https://www.google.com/recaptcha/api2/demo?invisible=true

Invisible reCAPTCHA не отображает чекбокс “Я не робот”. Вместо этого она обычно привязана к кнопке или срабатывает автоматически при загрузке страницы или действии пользователя, например при нажатии кнопки или отправке формы.

Внутри виджет Invisible reCAPTCHA отображается внутри скрытого <div> элемент, расположенный за пределами видимой области, что делает его невидимым для пользователя.

В зависимости от cookie пользователя и оценки риска reCAPTCHA может пройти автоматически, не показывая задание. В противном случае появится стандартное задание с картинками.

В большинстве случаев после завершения задания выполняется функция callback. Подробнее см. в разделе о callback выше.

Список параметров POST- и GET-запросов доступен здесь: Параметры POST- и GET-запросов reCAPTCHA V2

Как определить, что reCAPTCHA является Invisible?

Вы можете определить Invisible reCAPTCHA по одному из следующих признаков:

Галочка «Я не робот» не видна, но задание появляется после взаимодействия пользователя.
URL iframe reCAPTCHA содержит параметр size=invisible.
Объект конфигурации reCAPTCHA включает size свойство, установленное в invisible, например:
___grecaptcha_cfg.clients[0].aa.l.size === "invisible"

При решении невидимой reCAPTCHA через API добавьте параметр: invisible=1

Как обработать невидимую reCAPTCHA в браузере?

Способ 1: с помощью JavaScript

Установите значение g-recaptcha-response поля значение токена, возвращённого CapSkip:

document.getElementById("g-recaptcha-response").innerHTML="TOKEN";

После установки токена выполните действие, которое обычно происходит после успешной проверки.

В большинстве случаев это означает отправку формы. Вам нужно определить нужную форму по её id, name, или другой атрибут, а затем запустите отправку. Вот несколько примеров:

document.getElementById("recaptcha-demo-form").submit(); //by id "recaptcha-demo-form"
document.getElementsByName("myFormName")[0].submit(); //by element name "myFormName"
document.getElementsByClassName("example").submit(); //by class name "example"

В некоторых случаях callback-функция выполняется автоматически, когда reCAPTCHA решена.

Функция callback обычно определяется в data-callback атрибут виджета reCAPTCHA, например:

data-callback="myCallbackFunction"

В других случаях функция обратного вызова задаётся как callback параметр grecaptcha.render() функция, например:

grecaptcha.render('example', {
'sitekey' : 'someSitekey',
'callback' : myCallbackFunction,
'theme' : 'dark'
});

Вам нужно лишь вызвать эту функцию:

myCallbackFunction();

Способ 2: изменение HTML

Удалите <div> элемент, содержащий виджет reCAPTCHA, из тела страницы.

<div style="visibility: hidden; position: absolute; width:100%; top: -10000px; left: 0px; right: 0px; transition: visibility 0s linear 0.3s, opacity 0.3s linear; opacity: 0;">
<div style="width: 100%; height: 100%; position: fixed; top: 0px; left: 0px; z-index: 2000000000; background-color: #fff; opacity: 0.5;  filter: alpha(opacity=50)"></div>
<div style="margin: 0 auto; top: 0px; left: 0px; right: 0px; position: absolute; border: 1px solid #ccc; z-index: 2000000000; background-color: #fff; overflow: hidden;">
<iframe src="https://www.google.com/recaptcha/api2/bframe?hl=en&v=r20170213115309&k=6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs#zglq3yifgkmj"
title="recaptcha challenge"
style="width: 100%; height: 100%;"
scrolling="no"
name="zglq3yifgkmj"
frameborder="0"></iframe>
</div>
</div>

Удалите весь блок reCAPTCHA со страницы.

<div class="">
<!-- BEGIN: ReCAPTCHA implementation example. -->
<div
id="recaptcha-demo"
class="g-recaptcha"
data-sitekey="6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs"
data-callback="onSuccess"
data-bind="recaptcha-demo-submit"
>
<div
class="grecaptcha-badge"
style="width: 256px; height: 60px; transition: right 0.3s ease 0s; position: fixed; bottom: 14px; right: -186px; box-shadow: 0px 0px 5px gray;"
>
<div class="grecaptcha-logo">
<iframe
src="https://www.google.com/recaptcha/api2/anchor?k=6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs&co=aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbTo0NDM.&hl=en&v=r20170213115309&size=invisible&cb=uror1hlow5a"
title="recaptcha widget"
scrolling="no"
name="undefined"
width="256"
height="60"
frameborder="0"
></iframe>
</div>
<div class="grecaptcha-error"></div>
<textarea
id="g-recaptcha-response"
name="g-recaptcha-response"
class="g-recaptcha-response"
style="width: 250px; height: 40px; border: 1px solid #c1c1c1; margin: 10px 25px; padding: 0px; resize: none;  display: none; "
></textarea>
</div>
</div>
<script>
var onSuccess = function (response) {
var errorDivs = document.getElementsByClassName('recaptcha-error');
if (errorDivs.length) {
errorDivs[0].className = '';
}
var errorMsgs = document.getElementsByClassName('recaptcha-error-message');
if (errorMsgs.length) {
errorMsgs[0].parentNode.removeChild(errorMsgs[0]);
}
document.getElementById('recaptcha-demo-form').submit();
};
</script>
<!-- Optional noscript fallback. --><!-- END: ReCAPTCHA implementation example. -->
</div>

Вставьте следующий код на место удалённого блока:

<input type="submit" /> <textarea name="g-recaptcha-response">%g-recaptcha-response%</textarea>

%g-recaptcha-response% представляет токен-ответ, полученный от CapSkip.

После замены блока появится кнопка “Submit query”. Нажмите её, чтобы отправить форму вместе с g-recaptcha-response значение и все остальные необходимые данные формы на сайт.

reCAPTCHA V3

reCAPTCHA v3 представляет собой современный механизм капчи, разработанный Google. Он не показывает видимую проверку и не требует действий пользователя. Вместо этого он присваивает оценку на основе вероятности того, что взаимодействие исходит от человека.

Технически reCAPTCHA v3 похожа на reCAPTCHA v2. Сайт получает токен от reCAPTCHA API, который затем отправляется в POST-запросе на целевой сервер и проверяется через reCAPTCHA API.

Ключевое отличие в том, что reCAPTCHA v3 не показывает видимой капчи. Вместо этого она возвращает оценку, которая определяет, человек перед нами или бот. Эта оценка называется score и варьируется от 0,0 до 1,0. Оценка отправляется на сайт, который затем решает, как обработать запрос на основе этого значения.

Также есть дополнительный параметр под названием action, что позволяет сайту различать разные взаимодействия пользователя. После проверки токена API reCAPTCHA возвращает имя действия, связанное с запросом.

Как решить reCAPTCHA v3 с помощью CapSkip?

Сначала убедитесь, что целевой сайт использует reCAPTCHA v3.

Признаки reCAPTCHA v3 включают:

Без видимой капчи или графических проверок
The api.js скрипт загружается с render=SITEKEY параметр, например:
https://www.google.com/recaptcha/api.js?render=SITEKEY
The ___grecaptcha_cfg.clients массив содержит запись с большим числовым индексом, например clients[100000]

Чтобы решить reCAPTCHA v3, определите следующие параметры:

sitekey
Это можно найти в render параметр api.js URL скрипта. Он также может встречаться в URL iframe, внутри JavaScript-кода, который вызывает grecaptcha.execute(), или внутри ___grecaptcha_cfg объект конфигурации.
action
Найдите это, изучив JavaScript-код на предмет вызовов grecaptcha.execute(), например:
grecaptcha.execute('SITEKEY', {action: 'do_something'})В некоторых случаях для поиска action требуется просмотреть несколько файлов JavaScript, загружаемых страницей. Если вы не можете определить значение action, вы можете использовать значение по умолчанию "verify".
pageurl
Полный URL страницы, где реализован reCAPTCHA v3.

Разбираемся с оценкой

Допустимый порог оценки различается на разных сайтах и может быть определён только опытным путём. Оценки варьируются от:

0.0 → вероятно, бот
1.0 → скорее всего человек

Большинство сайтов используют пороги от 0,3 до 0,7, поскольку даже легитимные пользователи могут получать более низкие оценки.

Вы можете передать нужный порог с помощью min_score параметр, но итоговый score всегда определяется Google в момент проверки и не может быть гарантирован решателем.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
method	Строка	Да	userrecaptcha: указывает на запрос reCAPTCHA.
version	Строка	Да	v3: указывает, что запрос относится к reCAPTCHA v3.
googlekey	Строка	Да	Значение data-sitekey параметр, найденный на целевой странице.
pageurl	Строка	Да	Полный URL страницы, на которой расположена reCAPTCHA.
enterprise	Целое число По умолчанию: 0	Нет	1: указывает на reCAPTCHA Enterprise v3. 0: стандартная reCAPTCHA v3.
action	Строка По умолчанию: verify	Нет	Значение action параметр, заданный на странице.
min_score	Float	Нет	Запрашиваемый минимальный score для токена. Google присваивает итоговый score, когда ваш сервер проверяет токен, поэтому это значение служит лишь подсказкой, а не гарантией. CapSkip возвращает полученный токен независимо от score, который Google присвоит позже.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста. 1: ответ возвращается в формате JSON.
proxy	Строка	Нет	Адрес прокси. Формат для аутентификации по IP: `IP:PORT` (пример: `123.123.123.123:3128`). Формат для аутентификации по логину/паролю: `login:password@IP:PORT`
proxytype	Строка	Нет	Тип прокси. Поддерживаемые значения: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. По умолчанию: `HTTP` когда `proxy` предоставлен, но `proxytype` опущен.

Отправка reCAPTCHA v3:

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&version=v3&action=submit&min_score=0.7&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com" http://127.0.0.1:8080/in.php

Отправка Enterprise reCAPTCHA v3:

curl -X POST -d "key=YOUR_API_KEY&method=userrecaptcha&version=v3&action=submit&min_score=0.7&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&enterprise=1" http://127.0.0.1:8080/in.php

Если запрос успешен, CapSkip вернёт ID капчи в виде простого текста: OK|12345

Если json=1 параметр указан, ответ будет возвращён в формате JSON:

{
"status":1,
"request":"12345"
}

Если возникает ошибка, CapSkip вернёт код ошибки.

Подождите от 10 до 15 секунд, затем отправьте HTTP GET-запрос на эндпоинт результата: http://127.0.0.1:PORT/res.php

Укажите возвращённый CAPTCHA ID в своём запросе. Полный список доступных параметров приведён в таблице ниже.

Если капча решена успешно, CapSkip вернёт результат в виде обычного текста или в формате JSON. Возвращаемое значение представляет собой токен проверки, похожий на следующий:

03AHJ_Vuve5Asa4koK3KSMyUkCq0vUFCR5Im4CwB7PzO3dCxIo11i53epEraq-uBO5mVm2XRikL8iKOWr0aG50sCuej9bXx5qcviUGSm4iK4NC_Q88flavWhaTXSh0VxoihBwBjXxwXuJZ-WGN5Sy4dtUl2wbpMqAj8Zwup1vyCaQJWFvRjYGWJ_TQBKTXNB5CCOgncqLetmJ6B6Cos7qoQyaB8ZzBOTGf5KSP6e-K9niYs772f53Oof6aJeSUDNjiKG9gN3FTrdwKwdnAwEYX-F37sI_vLB1Zs8NQo0PObHYy0b0sf7WSLkzzcIgW9GR0FwcCCm1P8lB--gf50q5BMkiRH7osm4DoUgsjc_XyQiEmQmxl5sqZP7aKsaE-EM00x59XsPzD3m3YI6SRCFRUevSyumBd7KmXE8VuzIO9lgnnbka4-eZynZa6vbB9cO3QjLH0xSG3--o-fxrOuphwfrtwvvi2FGfpTexWvxhqWICMFTTjFBCEGEgj7_IFWEKirXW2RTZCVF0Gid7EtIsoEeZkPbrcUISGmgtiJkJ_KojuKwImF0G0CsTlxYTOU2sPsd5o1JDt65wGniQR2IZufnPbbK76Yh_KI2DY4cUxMfcb2fAXcFMc9dcpHg6f9wBXhUtFYTu6pi5LhhGuhpkiGcv6vWYNxMrpWJW_pV7q8mPilwkAP-zw5MJxkgijl2wDMpM-UUQ_k37FVtf-ndbQAIPG7S469doZMmb5IZYgvcB4ojqCW3Vz6Q

Если капча ещё не решена, CapSkip вернёт CAPCHA_NOT_READY. Подождите 5 секунд и повторите запрос. Если CapSkip возвращает пустое тело ответа, значит, результат уже получен или ID не существует. Каждый результат можно прочитать только один раз.

Список параметров GET-запроса

Параметр GET	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
action	Строка	Да	get: получить ответ для отправленной капчи.
id	Целое число	Да	Идентификатор CAPTCHA, возвращаемый `in.php`.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста 1: ответ возвращается в формате JSON

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=CAPTCHA_ID"

После получения токена от CapSkip вы должны правильно отправить его на целевой сайт. Чтобы понять, как это работает, лучше всего понаблюдать за запросами, отправляемыми при прохождении проверки как обычный пользователь. Большинство браузеров предоставляют инструменты разработчика с Network вкладка, которая позволяет проверять исходящие запросы.

В большинстве случаев токен отправляется через POST-запрос. Имя параметра может быть g-recaptcha-response, похоже на reCAPTCHA v2, или что-то вроде g-recaptcha-response-100000. В некоторых реализациях может использоваться другое имя параметра.

Вам следует изучить сетевые запросы, чтобы определить, как передаётся токен, и затем соответствующим образом построить свой запрос.

reCAPTCHA Enterprise

reCAPTCHA Enterprise представляет собой продвинутую версию системы reCAPTCHA от Google. Она может работать в режимах v2 и v3 и предоставляет администраторам сайтов дополнительный контроль, включая возможность оценивать и сообщать, было ли взаимодействие человеческим или автоматизированным.

Как решать reCAPTCHA Enterprise?

Первым шагом нужно определить, использует ли сайт версию reCAPTCHA Enterprise.

Ключевые признаки reCAPTCHA Enterprise включают:

Страница загружается enterprise.js вместо api.js, например:

<script src="https://recaptcha.net/recaptcha/enterprise.js" async defer></script>

JavaScript-код сайта вызывает grecaptcha.enterprise.METHOD вместо grecaptcha.METHOD

Затем определите, какая реализация используется: v2, Invisible v2 или v3. Обычно это можно выяснить, проанализировав, как отрисовывается виджет и как он ведёт себя на странице.

Следуйте приведённой ниже блок-схеме, чтобы определить правильную реализацию. Она применима в подавляющем большинстве случаев.

Определите параметры капчи так же, как описано для reCAPTCHA v2 или v3.

Для реализаций v2 Enterprise могут быть дополнительные необязательные данные. В большинстве случаев это пользовательская строка, заданная в s или data-s параметр. Если он присутствует, включите это значение в свой запрос, используя data-s параметр.

Список параметров POST- и GET-запросов доступен здесь: Параметры POST- и GET-запросов reCAPTCHA V2

Для реализаций v3 Enterprise вам также может понадобиться action значение. Чтобы найти его, изучите JavaScript-код сайта и найдите grecaptcha.enterprise.execute() вызов. action параметр обычно передаётся внутри этой функции. Имейте в виду, что action необязателен и в некоторых случаях может быть undefined.

Список параметров POST- и GET-запросов доступен здесь: Параметры POST- и GET-запросов reCAPTCHA V3

При отправке вашего запроса в /in.php эндпоинт, включите дополнительный параметр: enterprise=1

После этого работайте с API CapSkip так же, как при решении reCAPTCHA v2 или v3. Как только токен получен, отправьте его на целевой сайт в соответствии с его реализацией.

Cloudflare Turnstile

Cloudflare Turnstile представляет собой современную альтернативу капче, разработанную Cloudflare. Она проверяет, является ли посетитель человеком, не полагаясь на традиционные визуальные проверки. Turnstile может отображаться как отдельный виджет или как часть страницы-проверки и работает при минимальном участии пользователя или вовсе без него.

Существуют две распространённые реализации Turnstile:

1. Отдельный виджет Turnstile

Отдельный виджет Turnstile встраивается прямо на страницу сайта и обычно защищает форму от автоматических отправок. В этом случае:

Извлеките sitekey from the page.
Отправьте его в CapSkip API вместе с полным pageurl.
После получения токена вставьте его в cf-turnstile-response поле.
В некоторых реализациях токен также может потребоваться поместить в g-recaptcha-response поле.
Если callback определён в turnstile.render() конфигурацию, выполните её с возвращённым токеном.

Затем отправьте форму как обычно.

2. Turnstile на странице проверки Cloudflare

Это происходит, когда сайт проксируется через Cloudflare и показывает страницу проверки Turnstile перед предоставлением доступа. В этом случае необходимо извлечь следующие параметры:

cData
chlPageData
action

Эти значения должны быть включены в ваш запрос к API. Кроме того, вы должны использовать User-Agent значение, возвращаемое API CapSkip при отправке токена.

Как извлечь необходимые параметры?

Чтобы извлечь необходимые параметры, вы можете переопределить turnstile.render метод и перехватите аргументы, передаваемые при его вызове. Например, внедрите на страницу следующий JavaScript-код. Скрипт должен быть выполнен до загрузки виджета Turnstile, чтобы успешно захватить параметры.

const i = setInterval(()=>{
if (window.turnstile) {
clearInterval(i)
window.turnstile.render = (a,b) => {
let p = {
method: "turnstile",
key: "YOUR_API_KEY",
sitekey: b.sitekey,
pageurl: window.location.href,
data: b.cData,
pagedata: b.chlPageData,
action: b.action,
userAgent: navigator.userAgent,
json: 1
}
console.log(JSON.stringify(p))
window.tsCallback = b.callback
return 'foo'
}
}
},50)

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
method	Строка	Да	turnstile: указывает на запрос Cloudflare Turnstile.
sitekey	Строка	Да	Значение data-sitekey параметр, найденный на целевой странице.
pageurl	Строка	Да	Полный URL страницы, на которой расположено задание Turnstile.
action	Строка	Нет	Необязательное значение action, заданное в `data-action` атрибут или передаётся в `turnstile.render()`.
data	Строка	Нет	Значение `cData` переданный в `turnstile.render()` или задан в `data-cdata` атрибут.
pagedata	Строка	Нет	Значение `chlPageData` переданный в `turnstile.render()`.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде обычного текста. 1: ответ возвращается в формате JSON.
proxy	Строка	Нет	Адрес прокси. Формат для аутентификации по IP: `IP:PORT` (пример: `123.123.123.123:3128`). Формат для аутентификации по логину/паролю: `login:password@IP:PORT`
proxytype	Строка	Нет	Тип прокси. Поддерживаемые значения: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. По умолчанию: `HTTP` когда `proxy` предоставлен, но `proxytype` опущен.

Отправка Turnstile (отдельно):

curl -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=0x4AAAAAAABUYP0XeMJF0xoy&pageurl=https://example.com" http://127.0.0.1:8080/in.php

Отправка Turnstile (challenge с опциональными action, data, pagedata):

curl -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=0x4AAAAAAABUYP0XeMJF0xoy&pageurl=https://example.com&action=managed&data=...&pagedata=..." http://127.0.0.1:8080/in.php

Если запрос успешен, CapSkip вернёт ID капчи в виде простого текста: OK|12345

Если json=1 параметр указан, ответ будет возвращён в формате JSON:

{
"status":1,
"request":"12345"
}

Если возникает ошибка, CapSkip вернёт код ошибки.

Используйте возвращённый ID, чтобы получить результат из /res.php эндпоинт API.

Список параметров GET-запроса

Параметр GET	Тип	Обязательно	Описание
key	Строка	Да	Ваш API-ключ CapSkip.
action	Строка	Да	get: получить ответ для отправленной капчи.
id	Целое число	Да	Идентификатор CAPTCHA, возвращаемый `in.php`.
json	Целое число По умолчанию: 0	Нет	0: ответ возвращается в виде простого текста. 1: ответ возвращается в формате JSON, включая `userAgent` значение.

Для Cloudflare Turnstile сервис распознавания использует определённый User-Agent браузера, и вы должны отправлять тот же самый User-Agent при передаче токена. С json=1 ответ включает userAgent поле. В режиме простого текста считайте то же значение из X-Turnstile-User-Agent заголовок ответа.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=CAPTCHA_ID"

GeeTest v3

GeeTest v3 Slider представляет собой интерактивную капчу, разработанную GeeTest. Она проверяет пользователей с помощью задачи с ползунком, чтобы отличить людей от ботов, обеспечивая быструю и удобную верификацию.

Чтобы решить капчу GeeTest v3 с помощью CapSkip, вы должны сначала получить необходимые параметры капчи с целевого сайта. Необходимые параметры:

gt: публичный ключ сайта (статичный)
challenge: динамическое значение challenge
api_server: домен API-сервера GeeTest (необязательно)

Эти значения обычно доступны, когда сайт инициализирует GeeTest.

Важно: Новый challenge значение необходимо получать для каждого запроса на решение. После того как капча загружена на странице, предыдущее challenge становится недействительным. Вам следует изучить сетевые запросы сайта’, чтобы определить запрос, который генерирует новый challenge значение и выполните этот запрос, прежде чем отправлять каждый запрос на решение в CapSkip.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
method	Строка	Да	Должно быть `geetest`. Указывает, что вы отправляете капчу GeeTest v3.
gt	Строка	Да	The `gt` значение, полученное с целевого сайта.
challenge	Строка	Да	The `challenge` значение, полученное с целевого сайта. Для каждого запроса на решение необходимо получать новое значение.
pageurl	Строка	Да	Полный URL страницы, содержащей капчу GeeTest.
api_server	Строка	Нет	Домен сервера API GeeTest, используемый целевым сайтом (например `api.geetest.com` или `api-na.geetest.com`).
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.
proxy	Строка	Нет	Адрес прокси. Формат для аутентификации по IP: `IP:PORT` (пример: `123.123.123.123:3128`). Формат для аутентификации по логину/паролю: `login:password@IP:PORT`.
proxytype	Строка	Нет	Тип прокси. Поддерживаемые значения: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. По умолчанию: `HTTP` когда `proxy` предоставлен, но `proxytype` опущен.

Отправьте HTTP-запрос GET или POST на ваш CapSkip API endpoint (/in.php) с method=geetest. Включите необходимые параметры GeeTest, полученные на предыдущем шаге, вместе с полным URL страницы, содержащей капчу.

curl -X POST \
-d "key=YOUR_API_KEY" \
-d "method=geetest" \
-d "gt=f1ab2cdefa3456789012345b6c78d90e" \
-d "challenge=12345678abc90123d45678ef90123a456b" \
-d "pageurl=https://www.example.com/" \
-d "api_server=api-na.geetest.com" \
http://127.0.0.1:8080/in.php

Если всё прошло успешно, CapSkip вернёт ID капчи в виде простого текста: OK|212

Если json=1 параметр указан, ответ будет возвращён в формате JSON:

{
"status": 1,
"request": "212"
}

В противном случае CapSkip вернёт соответствующий код ошибки.

Подождите примерно 5 секунд, затем отправьте HTTP GET-запрос на res.php эндпоинт, чтобы получить результат.

Список параметров GET-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
action	Строка	Да	Укажите `get` чтобы получить решение капчи.
id	Целое число	Да	CAPTCHA ID, возвращённый `in.php` запрос.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=212&json=1"

Если капча успешно решена, CapSkip вернёт решение в формате JSON:

{
"status": 1,
"request": "{\"geetest_challenge\":\"1a2b3456cd67890e12345fab678901c2de\",\"geetest_validate\":\"09fe8d7c6ba54f32e1dcb0a9fedc8765\",\"geetest_seccode\":\"12fe3d4c56789ba01f2e345d6789c012|jordan\"}"
}

Если капча ещё не решена, CapSkip вернёт: CAPCHA_NOT_READY

Подождите 5 секунд и повторите запрос. Если произойдёт ошибка, CapSkip вернёт соответствующий код ошибки. Используйте значения, возвращённые CapSkip, при отправке запроса на целевой сайт, применяя следующие поля:

geetest_challenge
geetest_validate
geetest_seccode

ALTCHA

ALTCHA представляет собой капчу на основе доказательства работы (proof of work). Здесь нет картинки, которую нужно распознать, и нет аудио, которое нужно прослушать. Целевой сайт выдаёт challenge, а клиент обязан перебором найти число, которое ему удовлетворяет. CapSkip вычисляет это число и возвращает payload, который сформировал бы сам виджет.

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

Защита здесь строится на вычислительных затратах CPU, а не на распознавании. Сервер задаёт цель и диапазон перебора (maxnumber), а клиент хеширует кандидатов, пока один из них не совпадёт. Отсюда следуют два вывода, необычных для капчи.

Во-первых, решение детерминировано. Здесь нет ни модели, ни показателя точности: ответ либо существует внутри заданного диапазона, либо challenge составлен некорректно. Ничего нельзя распознать неверно.

Во-вторых, время решения задаёт целевой сайт, а не CapSkip. Эталонный виджет по умолчанию берёт диапазон 1 000 000, то есть несколько миллисекунд работы. Сайты вправе поднять это значение, и некоторые ставят 999 999 999, а это примерно 500 миллионов хешей на средний challenge. Если сайт решается медленно, сначала проверьте у него maxnumber и только потом ищите другие причины.

Полный цикл состоит из четырёх шагов:

Получите challenge с того эндпоинта, откуда его читает виджет.
Отправьте его на /in.php с помощью method=altcha.
Опрашивайте /res.php до получения токена.
Отправьте токен обратно в форму целевого сайта, в поле altcha поле.

Что нужно подготовить перед решением

Сам challenge в одном из двух видов. Принимаются оба, поэтому отправляйте тот, который уже есть у вашего парсера.

Параметр	Когда использовать
challenge_json	У вас уже есть документ challenge. CapSkip решает его локально и вообще не делает сетевых запросов: это самый быстрый путь.
challenge_url	У вас есть только эндпоинт, который отдаёт challenge. CapSkip сам загружает его, через ваш прокси, если вы его передали, и затем решает.

Где найти challenge

Откройте инструменты разработчика в браузере, перейдите на вкладку Network на целевой странице и найдите запрос, который элемент <altcha-widget> отправляет за своим challenge. Часто это путь вида /altcha/challenge. URL этого запроса и есть ваш challenge_url, а JSON, который приходит в ответ, и есть ваш challenge_json.

Атрибут виджета, в котором указан этот эндпоинт, менялся от версии к версии, поэтому смотрите исходный код страницы, а не полагайтесь на догадки. Виджеты v1 и v2 используют challengeurl="...", а v3 и новее используют challenge="..." и для URL, и для встроенных данных. В некоторых установках challenge генерируется прямо на странице и никакой запрос не отправляется.

Документ challenge выглядит так:

{
"algorithm": "SHA-256",
"challenge": "3dd28253be6cc0c54d95f7f98c517e68a1b2c3d4e5f60718293a4b5c6d7e8f90",
"salt": "46d5b1c8871e5152d902ee3f?expires=1893456000",
"signature": "4b1cf0e0be0f4e5247e50b0f9a4498301234567890abcdef1234567890abcdef",
"maxnumber": 1000000
}

Срок действия challenge истекает, и окно очень короткое

У каждого challenge собственный срок действия. Он указан в query-строке внутри salt или в поле parameters.expiresAt. Как только он проходит, целевой сайт отклоняет решение с сухой ошибкой проверки, которая выглядит ровно так же, как неверный ответ. Окна всего в две минуты встречаются часто.

Загружайте challenge непосредственно перед созданием задачи и сразу же отправляйте токен. Не собирайте challenge про запас и не держите токен, пока пользователь заполняет форму. Если вы передаёте challenge_url а не challenge_json, CapSkip автоматически запрашивает его заново, когда срок действия challenge истекает, а задача ещё стоит в очереди.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
method	Строка	Да	Должно быть `altcha`. Указывает, что вы отправляете challenge ALTCHA.
pageurl	Строка	Да	Полный URL страницы, с которой получен challenge.
challenge_url	Строка	Да*	Эндпоинт, с которого CapSkip должен загрузить challenge. Обязателен, если не передан `challenge_json` в запросе.
challenge_json	Строка	Да*	Сам документ challenge в виде JSON-строки. Обязателен, если не передан `challenge_url` в запросе.
proxy	Строка	Нет	Адрес прокси. Принимаются форматы `IP:PORT`, `LOGIN:PASSWORD@IP:PORT` или `IP:PORT:LOGIN:PASSWORD`. Используется только при загрузке по адресу из `challenge_url` и больше нигде.
proxytype	Строка	Нет	Тип прокси: `HTTP`, `HTTPS`, `SOCKS5` или `SOCKS5H`.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

Отправьте один из двух параметров: challenge_url или challenge_json. Отправить оба тоже можно: приоритет получает встроенный документ, потому что загрузка лишь повторно получила бы то, что у вас уже есть.

Отправьте HTTP-запрос GET или POST на ваш CapSkip API endpoint (/in.php) с method=altcha. Принимаются как поля формы, так и JSON-тело с одинаковыми именами полей, а GET тоже работает, потому что у ALTCHA нет изображения для загрузки.

Отправка ALTCHA (поля формы):

curl -X POST \
-d "key=YOUR_API_KEY" \
-d "method=altcha" \
-d "pageurl=https://www.example.com/signup" \
--data-urlencode "challenge_url=https://www.example.com/captcha/api/altcha/challenge" \
-d "json=1" \
http://127.0.0.1:8080/in.php

Отправка ALTCHA (JSON-тело):

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"key": "YOUR_API_KEY",
"method": "altcha",
"pageurl": "https://www.example.com/signup",
"challenge_url": "https://www.example.com/captcha/api/altcha/challenge",
"json": 1
}' \
http://127.0.0.1:8080/in.php

JSON-тело позволяет три вещи, недоступные при кодировании формой. Флаги могут быть настоящими булевыми значениями ("json": true), challenge_json может быть вложенным документом, а не экранированной строкой, а поле со значением null считается непереданным.

Если всё указано верно, CapSkip возвращает ID капчи обычным текстом: OK|2122988149. При отправленном параметре json=1 ответ вместо этого приходит в виде JSON-конверта. В любом случае возвращённое значение и есть ID капчи, по которому вы запрашиваете результат.

{
"status": 1,
"request": "2122988149"
}

Иначе CapSkip возвращает подходящий код ошибки. Некорректный встроенный challenge отклоняется прямо на запросе отправки, а не после опроса результата, поэтому вы узнаёте об ошибке на том самом запросе, в котором она допущена.

Подождите примерно 5 секунд, затем отправьте HTTP GET-запрос на эндпоинт результата (/res.php) с полученным ID капчи.

Список параметров GET-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
action	Строка	Да	Укажите `get` чтобы получить решение капчи.
id	Целое число	Да	CAPTCHA ID, возвращённый `in.php` запрос.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=2122988149&json=1"

Если капча решена, CapSkip возвращает решение в формате JSON:

{
"status": 1,
"request": "eyJhbGdvcml0aG0iOiJTSEEtMjU2IiwiY2hhbGxlbmdlIjoiM2RkMi...",
"solution": {
"token": "eyJhbGdvcml0aG0iOiJTSEEtMjU2IiwiY2hhbGxlbmdlIjoiM2RkMi...",
"number": 9661
},
"cost": "0.0020",
"createTime": 1788863246,
"endTime": 1788863246,
"errorId": 0,
"solveCount": 1
}

request и solution.token всегда содержат одну и ту же строку, поэтому читайте то поле, которое ожидает ваш клиент. number содержит счётчик, на котором был решён challenge, и возвращается для полноты картины. Если не передавать json=1, ответ будет просто OK|<token>.

Если капча ещё не решена, CapSkip возвращает CAPCHA_NOT_READY, именно в таком написании, как и во всех остальных методах. Подождите 5 секунд и повторите запрос.

Стройте цикл опроса на errorId, а не на status. status всегда равен целому числу 1 в соответствии с давним контрактом. res.php контракт возвращал всегда, и именно это значение читает любой совместимый SDK. Если вы писали свой клиент по странице документации, где показано "status": "ready", проверяйте errorId === 0 или наличие solution.token , а не первое.

Отправка токена

Виджет ALTCHA кладёт свой payload в поле формы с именем altcha. Отправьте токен в этом поле дословно, ровно так, как это сделал бы сам виджет:

POST https://www.example.com/signup
Content-Type: application/x-www-form-urlencodedemail=someone%40example.com&altcha=eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi...

Внутренняя структура payload повторяет тот challenge, из которого он получен. Устаревший challenge даёт плоский документ с полями number, а challenge PoW v2 даёт документ, где исходный challenge лежит в поле challenge и ответ лежит в поле solution. Считайте токен непрозрачным значением и передавайте его без изменений: целевой сайт и так знает, какую структуру ожидать.

Некоторые интеграции вместо этого читают payload из поля JSON-тела, поэтому посмотрите, что отправляет собственная форма страницы, и повторите это. Не перекодируйте токен, не обрезайте его и не меняйте порядок полей. Это base64 от JSON-документа, поля которого покрыты HMAC-подписью сервера, поэтому любое изменение делает его недействительным.

Поддерживаемые алгоритмы

Вам не нужно выяснять, какую схему использует сайт. CapSkip читает challenge и сам подбирает алгоритм.

Схема	Поколение	Поддерживается	Описание
Legacy PoW	v1	Да	Перебор `n` до совпадения `SHA(salt + n)` с challenge. Поддерживаются SHA-1, SHA-256, SHA-384 и SHA-512. Именно так работает большинство установок.
PBKDF2	PoW v2	Да	Подбор счётчика, у которого производный ключ начинается с нужного префикса. Поддерживаются SHA-256, SHA-384 и SHA-512. Это вариант по умолчанию, который рекомендует сама ALTCHA.
SHA	PoW v2	Да	Итеративный хеш-вариант той же схемы.
Argon2id	PoW v2	Нет	Функция формирования ключа, требовательная к памяти. Отклоняется, а не берётся в работу.
scrypt	PoW v2	Нет	Функция формирования ключа, требовательная к памяти. Отклоняется, а не берётся в работу.

Оба режима нагрузки работают и ничего не требуют от вас. В детерминированном режиме сервер заранее вычисляет цель, поэтому время решения предсказуемо, а в вероятностном режиме время решения меняется от одного challenge к другому. Все три типа виджета (native, checkbox и switch) поддерживаются, потому что тип задаёт только внешний вид элемента и до API не доходит.

Argon2id и scrypt отклоняются, а не берутся в работу. Задача с любым из них возвращает ERROR_CAPTCHA_UNSOLVABLE примерно за треть секунды и никогда не повторяется, поэтому она никогда не решается неверно втихую. Поскольку ALTCHA рекомендует PBKDF2 как вариант по умолчанию, это затрагивает лишь небольшую долю сайтов.

CaptchaFox

CaptchaFox представляет собой капчу с упором на приватность: она оценивает сам браузер, а не просит посетителя что-либо прочитать. Большинство посетителей вообще никогда не видят головоломку. CapSkip решает её, запуская настоящий виджет в настоящем браузере, и возвращает тот проверочный токен, который выдал бы сам виджет.

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

CaptchaFox принимает решение в три слоя, и виден только последний. Виджет выполняет короткое доказательство работы, собирает большой набор браузерных сигналов и отправляет и то и другое в свой API. Если этих данных сервису достаточно, токен выдаётся сразу и никакая головоломка не рисуется. Интерактивное задание появляется только тогда, когда собранных данных не хватает.

У такой схемы есть одно практическое следствие, о котором стоит знать до интеграции. Токен создаётся настоящей браузерной сессией, а не вычислением по переданным вами параметрам, поэтому CapSkip загружает виджет на указанном вами URL страницы и даёт ему отработать. Вы передаёте CapSkip ключ сайта и страницу, а CapSkip возвращает токен.

Полный цикл состоит из четырёх шагов:

Возьмите ключ сайта с целевой страницы.
Отправьте его на /in.php с помощью method=captchafox.
Опрашивайте /res.php до получения токена.
Отправьте токен обратно в форму целевого сайта, в поле cf-captcha-response поле.

Что нужно подготовить перед решением

Всего два значения, и оба читаются прямо с целевой страницы. Никакой документ задания захватывать не нужно, и ничто не истекает, пока задача стоит в очереди.

Параметр	Откуда он берётся
sitekey	Публичный ключ, с которым отрисовывается виджет. Он не секретный, одинаков для всех посетителей и по традиции начинается с `sk_`.
pageurl	Полный URL страницы, на которой находится виджет. CaptchaFox сверяет его со списком доменов, для которых зарегистрирован ключ, поэтому это должна быть настоящая страница.

Где найти ключ сайта

Откройте на целевой странице инструменты разработчика браузера и найдите контейнер CaptchaFox. Сайты отрисовывают виджет одним из двух способов, и ключ виден в обоих.

<!-- Automatic rendering: the key is an attribute -->
<div class="captchafox" data-sitekey="sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G"></div><!-- Explicit rendering: the key is in the render call -->
<script>
captchafox.render("#container", {
sitekey: "sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G",
onVerify: function (token) { /* ... */ }
});
</script>

Если ни того ни другого в отданном HTML нет, потому что страница собирает виджет во время работы, откройте вкладку Network и найдите запрос к api.captchafox.com. Ключом служит сегмент пути после /captcha/.

URL страницы должен соответствовать ключу

Ключи CaptchaFox регистрируются на список разрешённых доменов, и сервис проверяет хост, прежде чем что-либо выдать. Верный ключ, использованный на странице вне этого списка, отклоняется постоянно, а не время от времени.

CapSkip сообщает о таком случае, а не повторяет попытку, потому что повтор здесь не поможет. Если ключ сайта стабильно и сразу даёт ошибку, проверьте, что pageurl указывает на страницу, где виджет действительно работает, а не на страницу поиска, редирект или сокращённую ссылку, которая ведёт в другое место.

Типы заданий

Вы не выбираете, какое задание появится. Решает CaptchaFox, а CapSkip обрабатывает то, что ему досталось.

Challenge	Когда появляется	Поддерживается	Описание
Invisible	Обычно	Да	Собранных данных о браузере сервису достаточно, и токен выдаётся без отрисовки чего-либо на экране. Это самый частый и самый быстрый путь.
Слайдер	Иногда	Да	Задание с ползунком, где фрагмент нужно перетащить в вырез. CapSkip находит цель и выполняет перетаскивание.
Выбор изображений	Редко	Нет	Сетка изображений, из которых нужно выбрать подходящие. CapSkip помечает такое задание как нерешаемое, чтобы ваш клиент сразу запросил новое, а не ждал истечения таймаута.
Аудио	Редко	Нет	Запасной вариант для доступности. Помечается как нерешаемое по той же причине.

Два неподдерживаемых задания встречаются нечасто, и при повторной попытке обычно выпадает другое. Воспринимайте ответ «нерешаемо» как сигнал отправить задачу заново, а не как постоянный отказ ключа.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
method	Строка	Да	Должно быть `captchafox`. Указывает, что вы отправляете капчу CaptchaFox.
sitekey	Строка	Да	Ключ сайта, считанный с целевой страницы, обычно с префиксом `sk_`.
pageurl	Строка	Да	Полный URL страницы, на которой находится виджет.
api_server	Строка	Нет	Точка входа виджета, которую нужно загрузить. По умолчанию `https://cdn.captchafox.com/`. См. Выбор источника виджета ниже.
useragent	Строка	Нет	Принимается для совместимости с другими сервисами, но не применяется. CapSkip решает капчу в настоящем браузере и использует его собственный постоянный отпечаток.
proxy	Строка	Нет	Адрес прокси. Принимаются форматы `IP:PORT`, `LOGIN:PASSWORD@IP:PORT` или `IP:PORT:LOGIN:PASSWORD`.
proxytype	Строка	Нет	Тип прокси: `HTTP`, `HTTPS`, `SOCKS5` или `SOCKS5H`.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

В отличие от большинства сервисов, CapSkip не требует прокси для этого метода в обязательном порядке. Но как только вы начнёте решать в заметных объёмах, прокси вам понадобятся: CaptchaFox оценивает не только браузер, но и сеть, в которой работает виджет, поэтому многократные решения с одного адреса толкают этот адрес к интерактивным испытаниям, а затем и к отказам. Для тестов и редких решений хватит одного адреса. Дальше настройте пул прокси в CapSkip и дайте ему распределять нагрузку или передавайте прокси в каждом запросе, когда токен должен приходить из определённой сети.

Отправьте HTTP-запрос GET или POST на ваш CapSkip API endpoint (/in.php) с method=captchafox. Принимаются как поля формы, так и JSON-тело с одинаковыми именами полей, а GET тоже работает, так как CaptchaFox не содержит изображения для загрузки.

Отправка CaptchaFox (поля формы):

curl -X POST \
-d "key=YOUR_API_KEY" \
-d "method=captchafox" \
-d "sitekey=sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G" \
-d "pageurl=https://www.example.com/signup" \
-d "json=1" \
http://127.0.0.1:8080/in.php

Отправка CaptchaFox (тело JSON):

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"key": "YOUR_API_KEY",
"method": "captchafox",
"sitekey": "sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G",
"pageurl": "https://www.example.com/signup",
"json": 1
}' \
http://127.0.0.1:8080/in.php

{
"status": 1,
"request": "2122988149"
}

В противном случае CapSkip возвращает подходящий код ошибки. Отсутствующий ключ сайта или непригодный URL страницы отклоняется прямо в запросе на отправку, а не после опроса, поэтому вы узнаёте об ошибке на том самом запросе, в котором она допущена.

Подождите примерно 5 секунд, затем отправьте HTTP GET-запрос на эндпоинт результата (/res.php) с полученным ID капчи. Решение CaptchaFox запускает настоящую браузерную сессию, поэтому оно займёт больше времени, чем вычислительные методы вроде ALTCHA, и ещё больше, когда выпадает интерактивное задание.

Список параметров GET-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
action	Строка	Да	Укажите `get` чтобы получить решение капчи.
id	Целое число	Да	CAPTCHA ID, возвращённый `in.php` запрос.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=2122988149&json=1"

Если капча решена, CapSkip возвращает решение в формате JSON:

{
"status": 1,
"request": "177f50c25b845601e5c779cdb51b040d523e8ab69efb4d5b343e28df07d05076",
"solution": {
"token": "177f50c25b845601e5c779cdb51b040d523e8ab69efb4d5b343e28df07d05076"
},
"cost": "0.00145",
"createTime": 1788863246,
"endTime": 1788863262,
"errorId": 0,
"solveCount": 1
}

request и solution.token всегда содержат одну и ту же строку, поэтому читайте то поле, которое ожидает ваш клиент. Без json=1, ответ будет просто OK|<token>.

Отправка токена

Виджет CaptchaFox помещает свой токен в поле формы с именем cf-captcha-response. Отправьте токен в этом поле дословно, ровно так, как это сделал бы сам виджет:

POST https://www.example.com/signup
Content-Type: application/x-www-form-urlencodedemail=someone%40example.com&cf-captcha-response=177f50c25b845601e5c779cdb51b040d...

Некоторые интеграции вместо этого читают токен из поля JSON-тела, поэтому посмотрите, что отправляет собственная форма страницы, и повторите это. Считайте токен непрозрачным значением и передавайте его без изменений. Он проверяется на стороне сервера по той сессии, которая его создала, поэтому любая правка делает его недействительным.

Токены живут недолго. Отправляйте токен сразу, а не держите его, пока пользователь заполняет форму, и решайте капчу заново, если форму бросили и вернулись к ней позже.

Выбор источника виджета

CaptchaFox публикует свой виджет в двух местах, и от того, какой из них загружает сайт, зависит формат ожидаемого в ответ токена. Передавайте api_server только тогда, когда целевая страница использует не вариант по умолчанию.

api_server	Token	По умолчанию	Описание
https://cdn.captchafox.com/	Обычный	Да	Стандартный виджет, который использует подавляющее большинство сайтов. Именно его CapSkip загружает, если вы ничего не передали.
https://s.uicdn.com/mampkg/	С префиксом MAM_	Нет	Упакованная сборка, которую встраивают некоторые платформы. Она возвращает токен с префиксом `MAM_`. Передавайте полный путь к пакету ровно в том виде, в каком он указан в теге script на странице.

Возьмите значение из тега <script> на целевой странице, который загружает виджет. Если вы передадите не тот источник, решение всё равно будет успешным, но токен вернётся в формате, который целевой сайт не примет, и это будет выглядеть как молчаливый сбой проверки, а не как ошибка.

Capy Puzzle

Capy Puzzle представляет собой капчу с перетаскиванием: из фотографии вырезают фрагмент, а посетитель перетаскивает его обратно в оставшийся от него вырез. CapSkip возвращает три значения, которые виджет вписал бы в страницу сам, готовые к отправке вместе с вашей формой.

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

Среди капч на этой странице Capy выделяется тем, что ни одна часть задания не выдаётся сервером. Виджет сам генерирует ключ задания, запрашивает у Capy API головоломку, которая принадлежит этому ключу, и посетитель перетаскивает фрагмент на место. Нет ни токена, который нужно получить заранее, ни рукопожатия, которое нужно воспроизвести.

Ответом служит не координата. Виджет записывает траекторию, по которой перетаскивали фрагмент, и кодирует её в строку, поэтому целевому сайту вы отправляете правдоподобное перетаскивание, а не точку назначения. CapSkip строит эту траекторию за вас.

Полный цикл состоит из четырёх шагов:

Возьмите ключ капчи с целевой страницы.
Отправьте его на /in.php с помощью method=capy.
Опрашивайте /res.php до готовности решения.
Отправьте три полученных значения обратно в форму целевого сайта.

Что нужно подготовить перед решением

Всего два значения, и оба читаются прямо с целевой страницы.

Параметр	Откуда он берётся
captchakey	Публичный ключ Capy этого сайта, по традиции с префиксом `PUZZLE_`. В исходном коде страницы он встречается как `capy_captchakey`, а в URL скрипта виджета указывается как параметр `k` в строке запроса.
pageurl	Полный URL страницы, на которой находится виджет. Capy никогда не видит это значение, но ключи регистрируются за конкретными сайтами, поэтому передавайте настоящую страницу.

Есть и третье значение, которое стоит проверить: api_server. Это корень Capy API, за которым закреплён ключ. Прочитайте его из того же тега script. По умолчанию CapSkip использует https://jp.api.capy.me, где и работает действующий сервис, и менять это значение нужно только тогда, когда целевая страница указывает на другой адрес.

Некоторые сервисы распознавания капчи до сих пор указывают в документации api.capy.me без регионального префикса. Этот хост больше не разрешается в DNS. Если вы скопировали его откуда-то ещё, уберите его и позвольте CapSkip использовать значение по умолчанию.

Где найти ключ капчи

Откройте на целевой странице инструменты разработчика браузера и найдите виджет Capy. Ключ виден в обоих способах, которыми сайты его загружают.

<!-- In the page source, as the widget configuration -->
<div id="capy"></div>
<script>
window.capyOptions = {
captchakey: "PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v",
puzzle_div: "capy"
};
</script><!-- Or in the script URL itself, as the k parameter -->
<script src="https://jp.api.capy.me/puzzle/get_js/?k=PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v"></script>

Корень этого URL скрипта, https://jp.api.capy.me/ в примере выше, и есть значение api_server , если вам нужно его передать.

Ответ состоит из трёх значений, а не из токена

Это единственное структурное отличие от всех остальных методов на этой странице, и его стоит прочитать до того, как вы напишете клиент. reCAPTCHA, Turnstile и CaptchaFox возвращаются в виде одной непрозрачной строки. Решение Capy состоит из трёх отдельных значений, которые работают только вместе.

Возвращаемое значение	Подставляется в поле формы целевого сайта
captchakey	`capy_captchakey`
challengekey	`capy_challengekey`
answer	`capy_answer`

Поскольку в обычном OK|<token> есть место только для одного значения, а не для трёх, /res.php возвращает для этого метода объект решения целиком. Его содержит ответ обычным текстом, а также поле request в ответе JSON. Четвёртое поле, respKey, возвращается пустой строкой для совместимости с клиентами, написанными под другие сервисы. Для решения головоломки оно ничего не несёт, и его можно игнорировать.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
method	Строка	Да	Должно быть `capy`. Указывает, что вы отправляете капчу Capy Puzzle.
captchakey	Строка	Да	Ключ капчи, считанный с целевой страницы, обычно с префиксом `PUZZLE_`. `sitekey` и `websiteKey` принимаются как псевдонимы.
pageurl	Строка	Да	Полный URL страницы, на которой находится виджет.
api_server	Строка	Нет	Корень Capy API, за которым закреплён ключ. По умолчанию `https://jp.api.capy.me`.
version	Строка По умолчанию: puzzle	Нет	Семейство заданий. Решается только `puzzle` . См. Puzzle и Avatar ниже.
userAgent	Строка	Нет	Значение User-Agent, отправляемое вместе с запросом головоломки. Необязательный параметр, нужен редко.
proxy	Строка	Нет	Адрес прокси. Принимаются форматы `IP:PORT`, `LOGIN:PASSWORD@IP:PORT` или `IP:PORT:LOGIN:PASSWORD`.
proxytype	Строка	Нет	Тип прокси: `HTTP`, `HTTPS`, `SOCKS5` или `SOCKS5H`.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

CapSkip не требует прокси для этого метода в обязательном порядке, но как только вы начнёте решать в заметных объёмах, прокси вам понадобятся. Каждое решение запрашивает свежую головоломку у Capy API живым запросом, а ровный поток таких запросов с одного адреса и есть тот шаблон, ради которого существует ограничение частоты. Для тестов и редких решений хватит одного адреса. Дальше настройте пул прокси в CapSkip и дайте ему распределять нагрузку или передавайте прокси в каждом запросе, когда решение должно приходить из определённой сети.

Отправьте HTTP-запрос GET или POST на ваш CapSkip API endpoint (/in.php) с method=capy. Поля формы, строка запроса и тело JSON принимаются одинаково и под теми же именами полей, потому что в Capy нет изображения для загрузки.

Отправка Capy Puzzle (поля формы):

curl -X POST \
-d "key=YOUR_API_KEY" \
-d "method=capy" \
-d "captchakey=PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v" \
-d "pageurl=https://www.example.com/login" \
-d "json=1" \
http://127.0.0.1:8080/in.php

Отправка Capy Puzzle (тело JSON):

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"key": "YOUR_API_KEY",
"method": "capy",
"captchakey": "PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v",
"api_server": "https://jp.api.capy.me/",
"pageurl": "https://www.example.com/login",
"json": 1
}' \
http://127.0.0.1:8080/in.php

{
"status": 1,
"request": "2122988149"
}

В противном случае CapSkip возвращает подходящий код ошибки. Отсутствующий ключ капчи, непригодный URL страницы или значение api_server , не являющееся URL, отклоняется прямо в запросе на отправку, а не после опроса, поэтому вы узнаёте об ошибке на том самом запросе, в котором она допущена.

Подождите примерно 3 секунды, затем отправьте HTTP GET-запрос к точке получения результата (/res.php) с полученным ID капчи. Перед выдачей решение намеренно задерживается на правдоподобное для человека время по причине, описанной в разделе Тайминг ниже.

Список параметров GET-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
action	Строка	Да	Укажите `get` чтобы получить решение капчи.
id	Целое число	Да	CAPTCHA ID, возвращённый `in.php` запрос.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=2122988149&json=1"

Если капча решена, CapSkip возвращает решение в формате JSON:

{
"status": 1,
"request": {
"captchakey": "PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v",
"challengekey": "BalY2gJaI8uA2SGVOZhqBQ3V0CYSNNGP",
"answer": "0xax8ex0xax84x0xkx7qx0x18x76x0x1ix6sx0x26x68x0x2gx5kx0x34x50x",
"respKey": ""
},
"solution": {
"captchakey": "PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v",
"challengekey": "BalY2gJaI8uA2SGVOZhqBQ3V0CYSNNGP",
"answer": "0xax8ex0xax84x0xkx7qx0x18x76x0x1ix6sx0x26x68x0x2gx5kx0x34x50x",
"respKey": ""
},
"cost": "0.00299",
"createTime": 1788863246,
"endTime": 1788863250,
"errorId": 0,
"solveCount": 1
}

request и solution содержат один и тот же объект, поэтому читайте то поле, которое ожидает ваш клиент. Без json=1, тот же объект идёт после префикса OK| одной строкой JSON. Именно это вернёт клиент, который читает res.php как обычный текст:

OK|{"captchakey":"PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v","challengekey":"BalY2gJaI8uA2SGVOZhqBQ3V0CYSNNGP","answer":"0xax8ex0xax84x0xkx7qx","respKey":""}

Если капча ещё не решена, CapSkip возвращает CAPCHA_NOT_READY, именно в таком написании, как и во всех остальных методах. Подождите 3 секунды и повторите запрос.

Каждый результат выдаётся один раз. Первый успешный опрос возвращает решение и удаляет его, а любой последующий опрос по тому же ID возвращает пустое тело, поэтому сохраняйте значения из того ответа, который их принёс.

Отправка решения

Три значения подставляются в те поля формы, которые виджет Capy заполнил бы сам. Отправляйте их без изменений:

<input type="hidden" name="capy_captchakey"   value="PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v">
<input type="hidden" name="capy_challengekey" value="BalY2gJaI8uA2SGVOZhqBQ3V0CYSNNGP">
<input type="hidden" name="capy_answer"       value="0xax8ex0xax84x0xkx7qx0x18x76x0x1ix6sx">

Не обрезайте, не перекодируйте и не «очищайте» иным образом строку answer . Это траектория перетаскивания, которую записал бы виджет, и бэкенд целевого сайта сверяет её с выданным заданием, поэтому любая правка делает её недействительной.

Ключ задания одноразовый и живёт недолго. CapSkip создаёт новый ключ для каждого решения, и головоломка привязана именно к нему, поэтому отправляйте три значения сразу, а не кэшируйте их, и никогда не используйте повторно один и тот же challengekey для второй отправки.

Тайминг: Capy отклоняет слишком быстрые ответы

Это та часть Capy, которая будет стоить вам целого дня, если вы возьмётесь за интеграцию самостоятельно. Capy измеряет реальный промежуток времени между выдачей головоломки и получением ответа и отклоняет всё, что выглядит быстрее человеческих возможностей. Отклоняет тем же сообщением, что и неверный ответ, поэтому идеально верное решение, отданное за 200 миллисекунд, неотличимо от сломанного решателя.

Замеры на собственной странице входа Capy при неизменно верном ответе:

Время от выдачи головоломки до проверки	Результат
0.48 seconds	Refused
1.03 секунды и выше, проверено до 4 секунд	Accepted

Поэтому CapSkip придерживает каждый результат, пока с момента отрисовки головоломки не пройдёт достаточно времени, примерно вдвое больше замеренного порога, потому что порог принадлежит Capy и может измениться. Удержание применяется автоматически к каждому решению, и настраивать ничего не нужно. Оно стоит задержки, но не пропускной способности, и при опросе результата оно незаметно: задача просто занимает около двух секунд.

Puzzle и Avatar

Capy публикует два семейства заданий. Это разные задания за разными конечными точками, и CapSkip решает одно из них.

version	Challenge	Поддерживается	Описание
puzzle	Assemble a puzzle	Да	Вариант по умолчанию, который используется почти в каждом внедрении. Фрагмент перетаскивают обратно в оставшийся от него вырез.
avatar	Drag an object	Нет	Отдельный тип задания. Отклоняется прямо при отправке с кодом `ERROR_BAD_PARAMETERS` , а не решается.

Если не передавать version , подразумевается puzzle, поэтому большинство интеграций его вообще не задают. Запрос с avatar отклоняется, а не выполняется, и это сделано намеренно: ответ на него как на puzzle вернул бы решение, которое целевой сайт не примет, а это хуже понятной ошибки, потому что выглядит как неисправный решатель, а не как неподдерживаемое задание.

Friendly Captcha

Friendly Captcha просит выполнить небольшой расчёт браузер посетителя, а не самого посетителя. Здесь нет изображения, по которому надо кликать, нет ползунка и нет аудиоварианта, поэтому на экране нечего сделать неправильно. CapSkip возвращает токен, который выдал бы виджет, готовый к отправке вместе с вашей формой.

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

Friendly Captcha относится к капчам типа proof of work. Виджет получает параметр сложности, ищет значения, хеш которых оказывается ниже неё, и записывает результат в скрытое поле вашей формы. Посетителю не показывается ничего, и в этом весь смысл продукта: страница с ним выглядит как страница вообще без капчи.

Под одним этим названием выпускаются два совершенно разных протокола, и по sitekey нельзя понять, какой из них использует сайт. У них общие только бренд и пространство имён sitekey, больше ничего. Правильный выбор между ними становится первой задачей интеграции, поэтому ему отведён отдельный раздел ниже.

Полный цикл состоит из четырёх шагов:

Считайте sitekey с целевой страницы, а вместе с ним и URL скрипта виджета.
Отправьте оба значения в /in.php с помощью method=friendly_captcha.
Опрашивайте /res.php до получения токена.
Поместите токен в поле формы, которое заполнил бы виджет, и отправьте форму.

Время решения для этого метода не является постоянным. Сервис решает, сколько работы стоит запрос, в момент его поступления, поэтому один и тот же sitekey в одном случае может обойтись заметно дороже, чем в другом. Закладывайте это в свой опрос результата, а не рассчитывайте на фиксированную длительность.

Что нужно подготовить перед решением

Два значения обязательны, а третье стоит отправлять всегда, когда его удаётся получить.

Параметр	Откуда он берётся
sitekey	The `data-sitekey` атрибут элемента виджета, то есть элемента с `class="frc-captcha"`.
pageurl	Полный URL страницы, на которой находится виджет.
module_script	The `src` тега скрипта виджета, у которого указан атрибут `type="module"`. Не обязателен, но именно он сообщает CapSkip, какую версию протокола использует сайт, поэтому отправляйте его, если он есть на странице.

Версия 1 и версия 2

Именно на этом можно потерять полдня, если пропустить этот раздел. Обе версии действующие, обе используются, и sitekey, зарегистрированный для одной из них, отвечает и на эндпоинте другой. Решите не ту версию, и вы получите корректно сформированный токен, который целевой сайт отклонит, причём нигде не будет и намёка на то, что дело было в версии.

version	Пакет виджета	Поддерживается	Описание
v1	friendly-challenge	Да	Исходный виджет с открытым кодом. Его скрипт называется `widget.module.min.js` или `widget.min.js`. Вариант по умолчанию, когда ничто не указывает на обратное.
v2	@friendlycaptcha/sdk	Да	Актуальный SDK. Его скрипт называется `site.min.js`. Страница, загружающая именно его, работает на v2, как бы она ни выглядела в остальном.

CapSkip определяет версию в таком порядке и останавливается на первом же ответе:

The version параметр, если вы его передали. v1 и v2 являются допустимыми написаниями; одиночное 1 или 2 тоже принимается.
URL скрипта виджета, из module_script или nomodule_script. Это самый надёжный признак из всех, потому что это именно та сборка, которую сайт действительно загружает.
Если нет ни того, ни другого, v1.

CapSkip не спрашивает у сервиса, к какой версии относится sitekey, потому что сервис ответит для любой из них. Передайте параметр version, либо передайте URL скрипта, и вопрос вообще не возникает.

Где найти sitekey

Откройте инструменты разработчика браузера на целевой странице и найдите элемент виджета. Sitekey и скрипт расположены в исходном коде страницы рядом, и вместе они дают всё, что нужно этому методу.

<!-- Version 1: the friendly-challenge widget -->
<div class="frc-captcha" data-sitekey="FCMEXAMPLE1234AB"></div>
<script type="module" src="https://cdn.example.com/[email protected]/widget.module.min.js"></script>
<script nomodule src="https://cdn.example.com/[email protected]/widget.min.js"></script><!-- Version 2: the @friendlycaptcha/sdk widget -->
<div class="frc-captcha" data-sitekey="FCMEXAMPLE1234AB"></div>
<script type="module" src="https://cdn.example.com/@friendlycaptcha/[email protected]/site.min.js"></script>

Некоторые установки отдают скрипт со своего собственного домена, а не с CDN. Значение имеет имя файла, а не хост, с которого он приходит.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
method	Строка	Да	Должно быть `friendly_captcha`. Указывает, что вы отправляете Friendly Captcha.
sitekey	Строка	Да	The `data-sitekey` значение, считанное с элемента виджета на целевой странице.
pageurl	Строка	Да	Полный URL страницы, на которой находится виджет.
version	Строка По умолчанию: v1	Нет	Версия протокола, `v1` или `v2`. См. Версия 1 и версия 2 выше.
module_script	Строка	Нет	The `src` тега скрипта виджета с атрибутом `type="module"`. Используется для определения версии, если параметр `version` не был передан.
nomodule_script	Строка	Нет	The `src` тега скрипта виджета с атрибутом `nomodule`. Считывается по той же причине.
api_server	Строка	Нет	Только в CapSkip. Эндпоинт региона размещения данных, к которому относится sitekey. Принимает `global` (по умолчанию), `eu`, либо полный URL. См. Размещение данных по регионам ниже.
useragent	Строка	Нет	User-Agent, который нужно отправить с запросом. Необязательный и нужен редко.
proxy	Строка	Нет	Адрес прокси. Принимаются форматы `IP:PORT`, `LOGIN:PASSWORD@IP:PORT` или `IP:PORT:LOGIN:PASSWORD`.
proxytype	Строка	Нет	Тип прокси: `HTTP`, `HTTPS`, `SOCKS5` или `SOCKS5H`.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

CapSkip не навязывает прокси для этого метода, но здесь он понадобится вам раньше, чем почти везде на этой странице. Сервис сам решает, сколько работы стоит каждый запрос, и повышает эту величину для адресов, которые он уже часто видел: при замерах по одному sitekey с одного адреса параметр сложности стабильно рос на протяжении сессии тестирования, а заявленный разброс между свежим адресом и сильно использованным составляет почти тридцатикратную разницу в объёме работы ради одного и того же токена. Одного адреса достаточно для тестов и редких решений. Дальше настройте в CapSkip пул прокси и дайте ему распределять нагрузку либо передавайте прокси в самом запросе, когда решение должно приходить из конкретной сети.

Отправьте HTTP-запрос GET или POST на ваш CapSkip API endpoint (/in.php) с method=friendly_captcha. Поля формы, строка запроса и JSON-тело принимаются одинаково, под одними и теми же именами полей, потому что этот метод не несёт изображения для загрузки.

Отправка Friendly Captcha (поля формы):

curl -X POST \
-d "key=YOUR_API_KEY" \
-d "method=friendly_captcha" \
-d "sitekey=FCMEXAMPLE1234AB" \
-d "pageurl=https://www.example.com/signup" \
-d "version=v2" \
-d "json=1" \
http://127.0.0.1:8080/in.php

Отправка Friendly Captcha (JSON-тело, с URL скриптов вместо явно указанной версии):

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"key": "YOUR_API_KEY",
"method": "friendly_captcha",
"sitekey": "FCMEXAMPLE1234AB",
"pageurl": "https://www.example.com/signup",
"module_script": "https://cdn.example.com/@friendlycaptcha/[email protected]/site.min.js",
"nomodule_script": "https://cdn.example.com/@friendlycaptcha/[email protected]/site.compat.js",
"json": 1
}' \
http://127.0.0.1:8080/in.php

{
"status": 1,
"request": "2122988149"
}

В противном случае CapSkip возвращает подходящий код ошибки. Отсутствующий sitekey или непригодный URL страницы отклоняются прямо на запросе отправки, а не после опроса, поэтому вы узнаёте об ошибке на том самом запросе, который был неверным.

Подождите примерно 5 секунд, затем отправьте HTTP GET-запрос на эндпоинт результата (/res.php) с полученным ID капчи.

Список параметров GET-запроса

Параметр	Тип	Обязательно	Описание
key	Строка	Да*	Ваш API-ключ CapSkip. Требуется только когда Проверка API-ключа включён.
action	Строка	Да	Укажите `get` чтобы получить решение капчи.
id	Целое число	Да	CAPTCHA ID, возвращённый `in.php` запрос.
json	Целое число По умолчанию: 0	Нет	`0` возвращает ответ в виде обычного текста. `1` возвращает ответ в формате JSON.

curl "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=2122988149&json=1"

Если капча решена, CapSkip возвращает токен в формате JSON. Токен находится в request, и solution.token содержит ту же строку для клиентов, которые ожидают её именно там:

{
"status": 1,
"request": "c62c4da36bbaf7f253873035832709ef.aqwpWwdbzRWKY/UQAQwwpgAAAAAAAAAAM7hBvJOzqjc=.AAAAAArcCQABAAAAxv8QAAIAAACKYRgA.AgAB",
"solution": {
"token": "c62c4da36bbaf7f253873035832709ef.aqwpWwdbzRWKY/UQAQwwpgAAAAAAAAAAM7hBvJOzqjc=.AAAAAArcCQABAAAAxv8QAAIAAACKYRgA.AgAB"
},
"cost": "0.00299",
"createTime": 1789667786,
"endTime": 1789667807,
"errorId": 0,
"solveCount": 1
}

Без json=1, тот же токен идёт после префикса OK| обычным текстом, и именно это вернёт клиент, который читает res.php как текст:

OK|c62c4da36bbaf7f253873035832709ef.aqwpWwdbzRWKY/UQAQwwpgAAAAAAAAAAM7hBvJOzqjc=.AAAAAArcCQABAAAAxv8QAAIAAACKYRgA.AgAB

Каждый результат выдаётся один раз. Первый успешный опрос возвращает токен и удаляет его, а любой последующий опрос по тому же ID возвращает пустое тело, поэтому сохраняйте токен из того ответа, в котором он пришёл.

Две версии выдают токены совершенно разной формы и размера. Токен v1 состоит из четырёх частей, разделённых точками, и занимает несколько сотен символов, как выше. Токен v2 представляет собой одну непрозрачную строку, которая начинается с AQQA. и имеет длину около шести килобайт, поэтому убедитесь, что всё, что его переносит, скрытое поле, колонка базы данных или проксируемый запрос, рассчитано на такой размер.

Отправка токена

Токен помещается в скрытое поле, которое виджет заполнил бы сам, и у двух версий имена этого поля не совпадают. На этом спотыкаются те, кто переносит рабочую интеграцию v1 на сайт с v2.

version	Поле формы, в которое попадает токен
v1	`frc-captcha-solution`
v2	`frc-captcha-response`

<!-- Версия 1 -->
<input type="hidden" name="frc-captcha-solution" value="c62c4da3...AgAB"><!-- Версия 2 -->
<input type="hidden" name="frc-captcha-response" value="AQQA.vW7kd3CujKT8PaQgEcW18QaH...">

Отправляйте токен дословно. Не обрезайте его, не перекодируйте и не удаляйте то, что выглядит как символы заполнения: каждая его часть проверяется относительно того задания, для которого он был выдан, поэтому любая правка делает его недействительным.

Сайт вправе переименовать это поле, и некоторые так и делают. Если страница, с которой вы интегрируетесь, использует другое имя, считайте имя с элемента виджета и используйте его. Если страница задаёт для виджета callback, его вызов с токеном в качестве единственного аргумента даёт тот же результат.

Размещение данных по регионам

Friendly Captcha держит отдельные эндпоинты для разных регионов размещения данных, и sitekey относится к одному из них. Токен для одного и того же sitekey выдадут оба, поэтому запрос к неверному эндпоинту даёт токен, который здесь выглядит совершенно корректным, а целевым сайтом отклоняется без каких-либо подробностей, кроме неудачной проверки.

Свой регион виджет указывает в атрибуте data-api-endpoint на странице. Если целевая страница его содержит, передайте то же значение в api_server. Этот параметр есть только в CapSkip и не имеет аналогов в других сервисах, поэтому клиент, написанный под другой сервис, его не отправляет: добавьте его сами, когда целевая страница работает на региональном эндпоинте.

api_server	Что выбирает
global	Значение по умолчанию. Используется, когда атрибут отсутствует, а это обычный случай.
eu	Европейский эндпоинт, который выбирается значением `data-api-endpoint="eu"`.
A full URL	Самостоятельно размещённая или иная нестандартная установка. Передавайте эндпоинт ровно в том виде, в каком его даёт страница.

Использование прокси

Для reCAPTCHA v2, v3, Invisible, Enterprise и Cloudflare вы можете отправлять прокси с каждой задачей. CapSkip решит капчу через этот прокси вместо пула прокси, настроенного в приложении CapSkip.

Это полезно, когда целевой сайт проверяет, что токен капчи был сгенерирован с того же IP-адреса, что и ваши собственные запросы, например, для сайтов за Cloudflare, при строгой оценке reCAPTCHA или на страницах с гео-ограничениями.

Список параметров POST-запроса

Параметр	Тип	Обязательно	Описание
proxy	Строка	Нет	Адрес прокси. Формат для аутентификации по IP: `IP:PORT` (пример: `123.123.123.123:3128`). Формат для аутентификации по логину/паролю: `login:password@IP:PORT`
proxytype	Строка	Нет	Тип прокси. Поддерживаемые значения: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. По умолчанию: `HTTP` когда `proxy` предоставлен, но `proxytype` опущен.

Коды ошибок

Код	Значение
`ERROR_KEY_DOES_NOT_EXIST`	Неверный ключ API.
`ERROR_WRONG_USER_KEY`	API-ключ отсутствует или пуст.
`ERROR_WRONG_METHOD`	Недопустимый метод HTTP или `action` параметр.
`ERROR_WRONG_ID_FORMAT`	Неверный формат ID капчи.
`ERROR_BAD_PARAMETERS`	Отсутствуют или недействительны обязательные параметры.
`ERROR_UPLOAD`	Данные изображения не предоставлены или загрузка не удалась.
`ERROR_INVALID_IMAGE`	Недопустимый формат изображения или повреждённые данные изображения.
`ERROR_INVALID_BASE64`	Некорректная кодировка base64.
`ERROR_TOO_BIG_CAPTCHA_FILESIZE`	Размер изображения превышает 600 КБ или размеры превышают 1000px.
`ERROR_CAPTCHA_UNSOLVABLE`	Не удалось решить капчу. Отправьте новую задачу и повторите попытку.
`ERROR_GOOGLEKEY`	Некорректно `googlekey` параметр.
`ERROR_PAGEURL`	Некорректно `pageurl` параметр.
`ERROR_ZERO_BALANCE`	На API-ключе не осталось средств для этого метода.
`ERROR_PROXY_FORMAT`	The `proxy` не удалось разобрать.
`CAPCHA_NOT_READY`	Капча всё ещё обрабатывается. Продолжайте опрос.
(пустой ответ)	Результат уже был получен, или ID не существует.