reCAPTCHA 해결 API는 siteverify와 다릅니다

Google의 reCAPTCHA v3 흐름에서는 클라이언트 SDK가 응답 토큰을 생성하고 사이트 소유자의 백엔드가 siteverify로 검증합니다. Enterprise 흐름에서는 클라이언트 SDK가 토큰을 생성하고 백엔드가 평가를 생성합니다.

소유한 사이트에 검증 기능을 추가하려면 적절한 Google 흐름을 사용하세요. 지원되는 대상에 대한 풀이 서비스가 필요하다면 solvethree의 작업 API를 사용하세요. 솔버는 대상이 평가할 토큰을 제공하며, 대상의 검증을 대체하지는 않습니다.

먼저 워크스페이스에서 사용할 수 있는 대상 사이트의 활성 프로필이 있는지 확인하세요. 호스트 이름과 작업을 전송하는 것만으로는 프로필이 생성되지 않습니다. 이 사전 요구 사항을 충족하지 않았다면 사이트 프로필 설정을 참고하세요.

solvethree API의 POST /v1/tasks로 작업을 생성하고, Authorization: Bearer 뒤에 워크스페이스 API 키를 넣으세요. 이 키는 서버에 보관하세요.

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

예제의 호스트 이름, 작업, 프록시를 대상 요청에 맞는 값으로 바꾸세요. site는 전체 URL이 아니라 호스트 이름입니다. reCAPTCHA 요청에는 proxy 또는 proxyCandidates 중 정확히 하나가 필요하며, type이나 url을 추가하면 안 됩니다. 이 예제는 기본 recaptchaType인 enterprise-v3를 사용하며, 게이트웨이는 v3도 허용합니다.

GET /v1/tasks/:id로 작업을 조회하세요. 상태가 pending 또는 solving인 동안 계속 폴링하세요. 사용 가능한 풀이 결과는 ready 상태에만 포함됩니다. failed가 되면 폴링을 중단하고 errorCode와 error를 확인하세요.

Google 문서에 따르면 Enterprise 웹사이트 응답 토큰은 2분 후 만료되며 한 번만 평가할 수 있습니다. 보호된 요청을 보내기 직전에 풀이를 요청하세요. 토큰이 작동하는지 확인하려고 평가를 생성하면 의도한 대상이 사용하기 전에 토큰이 소모될 수 있습니다.

작업 ID가 아닌 solution.token을 의도한 대상에 제출하세요. 반환된 userAgent와 secChUa 브라우저 식별 정보를 풀이에 성공한 프록시와 함께 사용하세요. 프록시를 바꾸거나 관련 없는 브라우저 헤더를 섞으면 후속 요청이 실패할 수 있습니다.

ready 작업은 풀이 결과를 사용할 수 있다는 뜻이지, 대상이 애플리케이션 요청을 수락했다는 뜻은 아닙니다. 수락 여부는 작업 생성이나 준비 상태가 아니라 대상의 응답으로 판단하세요.