2Captcha reCAPTCHA 연동을 solvethree로 이전하기

이 마이그레이션은 2Captcha API v2를 통한 reCAPTCHA v3 Enterprise를 다룹니다. 레거시 in.php/res.php API는 설명하지 않습니다. 또한 2Captcha의 API 버전은 CAPTCHA 버전이 아닙니다. solvethree는 reCAPTCHA v2를 지원하지 않습니다.

기존 요청은 2Captcha createTask에 문서화된 래퍼 구조를 사용하며, 자격 증명은 제공업체 고유의 작업 객체 외부에 있습니다.

{
  "clientKey": "TWO_CAPTCHA_API_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "minScore": 0.7,
    "pageAction": "login",
    "isEnterprise": true
  }
}

이 객체를 변경 없이 새 API에 그대로 사용하지 마세요. 특히 프록시 없는 작업 유형과 minScore는 아래 solvethree 요청에 포함하면 안 됩니다.

먼저 solvethree 콘솔에서 대상 사이트를 설정하세요. 해당 호스트 이름의 요청을 처리하려면 워크스페이스에 활성 사이트 프로필이 있어야 합니다. 호스트 이름과 action을 전송하는 것만으로는 프로필이 생성되지 않습니다.

https://api.solvethree.com의 POST /v1/tasks로 새 작업을 생성하고, Authorization: Bearer에 워크스페이스 API 키를 사용하세요. 키는 서버에 보관하세요. 작업 생성 규약은 중첩된 task 객체 대신 평면 JSON 본문을 사용합니다.

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

예제의 호스트 이름, action, proxy를 대상에 맞는 값으로 바꾸세요. 요청을 보내기 전에 requestId를 정하고 시간 초과 시 복구할 수 있도록 보관하세요. 새로운 논리적 작업마다 새 값을 사용하세요.

예제는 프록시 하나를 사용합니다. 대신 proxyCandidates에 경로, 쿼리, 프래그먼트가 없는 서로 다른 HTTP 또는 HTTPS 프록시 URL을 최대 열두 개까지 제공할 수 있습니다. 두 필드 중 하나만 전송하고 둘 다 전송하지 마세요. 후보를 제공하면 서비스가 다른 송신 경로를 시도할 수 있지만, 작동하는 프록시를 보장하지는 않습니다.

진행 중인 2Captcha 작업은 2Captcha의 인증 정보, 작업 ID, 문서화된 폴링 정책을 사용해 기존 getTaskResult 흐름으로 계속 처리하세요. 다른 서비스의 작업 ID는 solvethree 작업 핸들이 아닙니다.

1. 1.

   생성 응답 처리

   성공 페이로드를 읽기 전에 HTTP 응답이 성공인지 확인하세요. reCAPTCHA 생성은 기본적으로 최대 15초 동안 대기하지만, 종료되지 않은 작업을 반환할 수 있습니다. 이미 ready 상태라면 폴링 루프를 시작하지 말고 솔루션을 사용하세요.

2. 2.

   미완료 작업만 폴링

   GET /v1/tasks/:id로 solvethree 작업을 조회하세요. 기존 processing 검사를 pending과 solving 검사로 바꾸세요. 두 상태 모두 작업이 아직 완료되지 않았음을 뜻합니다. 사용 가능한 솔루션은 ready 상태에만 있습니다.

3. 3.

   URL에서 대기 시간 설정

   GET 폴링은 기본적으로 대기하지 않습니다. 롱 폴링을 사용하려면 JSON 필드가 아닌 URL 쿼리 매개변수 waitMs를 최대 15000으로 설정하세요. HTTP 클라이언트의 시간 초과는 요청한 대기 시간에 네트워크 오버헤드를 더한 시간으로 설정하세요.

4. 4.

   failed 상태에서 중단

   errorCode와 error를 읽고 해당 작업의 폴링을 중단하세요. 해결에 실패한 작업은 환불됩니다. site-unreachable 같은 오류는 원인을 조사해야 합니다. 모든 실패를 크레딧 문제로 단정하거나 잘못된 입력을 그대로 반복 제출하지 마세요.

연결 시간 초과가 발생했다고 해서 생성에 실패한 것은 아닙니다. 작업 ID를 받았다면 해당 작업을 조회하세요. 받지 못했다면 동일한 requestId로 동일한 요청을 다시 보내 새 작업을 생성하는 대신 기존 작업을 복구하세요. requestId를 재사용하면서 작업 입력을 변경하면 충돌이 발생합니다.

어댑터에서 HTTP 오류와 작업의 최종 실패를 구분하세요. 폴링 규약과 실패 처리에 두 처리 경로가 설명되어 있습니다. 2Captcha의 오류 페이로드 파서를 재사용하지 마세요.

기존 어댑터의 토큰 조회를 ready 상태인 solvethree 작업의 solution.token으로 바꾸세요. 대상이 reCAPTCHA 값을 받는 위치에 이 토큰을 제출하세요. 작업 ID나 solution 객체 전체를 제출하면 안 됩니다.

토큰을 제출할 때 반환된 userAgent 및 secChUa 브라우저 식별 정보를 성공한 프록시와 함께 사용하세요. proxyCandidates를 제공했다면 제출 시 다른 후보를 선택하지 말고 성공한 프록시를 사용하세요.

ready 상태는 솔루션이 생성되었다는 뜻이지, 웹사이트가 애플리케이션 요청을 수락했다는 뜻은 아닙니다. 대상이 요청을 거부하면 다른 작업에 비용을 지불하기 전에 전송한 토큰, action, 대상 URL, 프록시, 브라우저 식별 정보를 확인하세요.