Scarnox · Blog

캡차 솔버 API: 작동 방식과 호출 방법

캡차 솔버 API는 HTTP로 호출하는 웹 서비스입니다. 캡차의 세부 정보, 즉 작업 유형, 페이지의 sitekey, 페이지 URL을 보내면, 대상 사이트가 챌린지를 통과했다는 증거로 받아들이는 토큰을 돌려줍니다. Scarnox 엔드포인트도 이 방식으로 동작하며 동기식이므로, 요청 한 번으로 답을 받습니다.

이 가이드는 요청, 응답, 오류 형식, 그리고 운영 환경에서 연동이 안정적으로 유지되는지를 가르는 세부 사항을 다룹니다. 먼저 실행 가능한 스크립트가 필요하다면 Python으로 PopularCaptcha 풀기부터 시작하세요.

API가 하는 일과 하지 않는 일

코드가 페이지에서 캡차를 찾고 sitekey를 읽어 솔버에 보냅니다. 솔버는 토큰을 돌려줍니다. 코드는 그 토큰을 사이트가 기대하는 폼 필드에 넣고 폼을 제출합니다.

솔버는 페이지를 불러오지 않고, 아무것도 클릭하지 않으며, 폼을 제출하지도 않습니다. 토큰만 만듭니다. 이 경계를 기억하면 연동 전체가 이해하기 쉬워집니다. 세션, 쿠키, 요청 타이밍은 모두 여러분의 코드가 담당합니다.

현재 실시간으로 쓸 수 있는 작업 유형은 PopularCaptchaTaskProxyless인 PopularCaptcha(프록시 없음)뿐입니다. 다른 캡차 유형은 로드맵에 있습니다. 어떤 유형이 무엇인지는 캡차 유형 가이드에서 확인하세요.

엔드포인트

다음 주소로 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"
}

필수 필드는 세 가지입니다.

• captcha_type: 작업 유형. 현재 실시간 풀이에는 PopularCaptchaTaskProxyless를 사용합니다.
• site_key: 페이지에서 읽은 sitekey. PopularCaptcha의 sitekey는 UUID입니다.
• site_url: 캡차가 나타나는 페이지의 URL. 홈페이지가 아니라 실제 페이지를 쓰세요. 토큰은 위젯을 표시한 페이지에 묶여 있기 때문입니다.

선택 필드도 세 가지 있습니다. 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 토큰은 약 2분 안에 만료됩니다. 받자마자 토큰을 제출하세요. 토큰을 나중에 쓰려고 캐싱하지 마세요. 폼을 제출하기 전에 미리 풀지도 마세요. 토큰을 받은 시점과 폼을 제출하는 시점 사이에 여러 단계가 있다면, 풀이를 가장 마지막 순간으로 옮기세요.

토큰을 폼에 넣기

대부분의 사이트는 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이 위젯이 실제로 있던 페이지와 맞지 않기 때문입니다. 솔버를 탓하기 전에 값을 다시 확인하세요.

오류 처리

운영 환경의 연동에는 몇 가지 습관이 필요합니다.

• 모든 호출에서 errorId를 확인하고 errorCode를 기록하세요. 지원팀이 가장 먼저 요청하는 값입니다.
• 실패한 풀이는 짧은 백오프로 재시도하세요. 실패한 풀이는 무료이므로 재시도해도 풀이 비용은 들지 않지만, 빡빡한 루프는 시간을 낭비하고 자체 요청 제한에 걸릴 수 있습니다.
• 클라이언트 타임아웃은 약 185초로 설정하고, 타임아웃은 성공이 아니라 재시도해야 할 오류로 취급하세요.
• 토큰과 폼 제출은 시간상 가깝게 유지하세요. 토큰이 빨리 만료되기 때문입니다.

자세한 내용은 캡차 솔버 오류 처리 가이드에서 다룹니다.

시작하기

계정을 만들면 무료 체험 크레딧으로 시작할 수 있으며 카드 등록은 필요 없습니다. 그다음 직접 관리하는 테스트 페이지에 위의 요청을 실행하고, 무엇인가 중요한 것에 연결하기 전에 폼이 토큰을 받아들이는지 확인하세요.

다음 단계

• Python으로 PopularCaptcha 풀기
• 운영 환경을 견디는 재시도와 오류 처리
• 사이트키 찾기
• 캡차 유형 설명