Scarnox · Blog

API солвера капчі: як він працює і як його викликати

API солвера капчі — це веб-сервіс, який ви викликаєте через HTTP. Ви надсилаєте деталі капчі: тип завдання, sitekey сторінки та URL сторінки. У відповідь сервіс повертає токен, який сайт приймає як доказ, що виклик пройдено. Ендпоінт Scarnox працює саме так, і він синхронний, тож один запит дає готову відповідь.

Цей посібник охоплює запит, відповідь, формат помилок і деталі, які визначають, чи інтеграція витримає продакшн. Якщо спершу потрібен робочий скрипт, почніть з розв'язання PopularCaptcha на Python.

Що робить API, а чого не робить

Ваш код знаходить капчу на сторінці, читає її sitekey і надсилає солверу. Солвер повертає токен. Ваш код записує цей токен у поле форми, яке очікує сайт, і відправляє форму.

Солвер не завантажує вашу сторінку, нічого не натискає і не відправляє вашу форму. Він лише створює токен. Дотримання цієї межі спрощує решту інтеграції: сесія, cookie і час запитів залишаються у вашому коді.

Сьогодні єдиний чинний тип завдання — PopularCaptcha, proxyless, тобто PopularCaptchaTaskProxyless. Інші типи капчі у плані. Посібник про типи капчі показує, який є який.

Ендпоінт

Надішліть POST-запит на:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Тіло запиту описує завдання:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Три обов'язкові поля:

Існують три необов'язкові поля. proxy приймає значення у форматі http://user:pass@host:port і використовується з типами завдань із проксі. rqdata і is_invisible — для окремих варіантів віджетів. Повний список типів завдань і деталей полів є в довіднику API.

Синхронність означає відсутність опитування

Виклик блокується, доки токен не буде готовий. Опитувати не треба, і в цьому потоці немає другого запиту «отримати результат». Встановіть таймаут HTTP-клієнта близько 185 секунд, щоб повільне розв'язання не виглядало як мережева помилка.

У Python з бібліотекою requests це виглядає так:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Зчитуйте ключ із змінної середовища, а не записуйте його в скрипт. Той, хто може прочитати код, не повинен мати змогу використати ваш баланс.

Читання відповіді

Успішне розв'язання повертає errorId зі значенням 0, токен усередині solution і поле cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Невдале розв'язання повертає errorId зі значенням, відмінним від 0, а також машиночитабельний errorCode і зрозумілий людині errorDescription:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Перевіряйте errorId у тілі відповіді при кожному виклику. Не вважайте, що завершений HTTP-запит означає, що ви маєте токен. Найважливіше правило: з вас беруть плату лише тоді, коли errorId дорівнює 0. Невдалі розв'язання безкоштовні. Актуальні тарифи — на сторінці цін.

Термін дії токена

Токени PopularCaptcha спливають приблизно за дві хвилини. Відправте токен одразу після отримання. Не кешуйте токени для подальшого використання і не розв'язуйте наперед до відправки форми. Якщо ваш код виконує кілька кроків між отриманням токена і відправкою форми, перенесіть розв'язання на останній момент.

Як покласти токен у форму

Більшість сайтів читають відповідь PopularCaptcha з поля форми h-captcha-response. Багато з них також приймають g-recaptcha-response з тим самим значенням, тож надсилати обидва поля — поширений безпечний вибір:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Якщо форма не приймає токен, причина зазвичай у sitekey або URL сторінки, які не збігаються зі сторінкою, де був віджет. Перед тим як звинувачувати солвер, перевірте ці значення ще раз.

Обробка помилок

Для продакшн-інтеграції потрібен короткий список звичок:

Посібник з повторів і обробки помилок детальніше розглядає кожен із цих пунктів.

Початок роботи

Створіть обліковий запис і почніть з безкоштовного пробного кредиту, картка не потрібна. Потім виконайте наведений вище запит на тестовій сторінці, якою володієте, і переконайтеся, що форма приймає токен, перш ніж підключати його до чогось важливого.

Наступні кроки