CapSolver reCAPTCHA 연동을 solvethree로 이전하기

solvethree는 기본적으로 reCAPTCHA v3 Enterprise를 사용하며 표준 v3도 지원합니다. 그 외 공개 제품으로는 Kasada와 Ticketmaster TMPT가 있습니다. reCAPTCHA v2, hCaptcha, Turnstile, 브라우저 확장 프로그램을 통한 해결은 지원하지 않으므로 모든 CapSolver 연동을 대체할 수 있는 것은 아닙니다.

reCAPTCHA 작업을 보내기 전에 콘솔에서 대상 사이트를 설정하고 워크스페이스에서 활성 프로필을 사용할 수 있는지 확인하세요. 호스트 이름과 액션을 보내도 해당 프로필이 생성되지는 않습니다. CapSolver의 websiteKey 필드를 제거한 뒤 나머지 요청만으로 충분하다고 생각하지 마세요.

기존 요청은 CapSolver의 clientKey와 제공업체 고유의 작업 래퍼 구조를 사용합니다.

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

solvethree에서는 아래의 평면 구조 본문을 POST https://api.solvethree.com/v1/tasks로 보내세요. Authorization 헤더를 Bearer 뒤에 워크스페이스 API 키를 붙인 값으로 설정하세요. 키는 서버에 보관하고, 새 JSON 본문에 clientKey를 포함하지 마세요.

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

이 예제는 recaptchaType을 기본값으로 두므로 Enterprise 요청입니다. 대상에서 표준 v3를 사용한다면 명시적으로 선택하세요. 모든 CapSolver 작업 유형을 Enterprise 기본값으로 변환하지 마세요.

CapSolver ProxyLess 작업에 직접 대응하는 프록시 없는 방식은 여기에 없습니다. solvethree는 호출자가 제공한 프록시 입력을 요구합니다. 현재 연동에서 프록시를 관리하지 않는다면 이는 필드 이름 변경이 아닌 연동 방식의 변경입니다. SOCKS 프록시 구성도 새 요청에 복사하지 마세요. solvethree는 HTTP 및 HTTPS 프록시 URL을 지원합니다.

해결과 제출에 사용하는 경로를 명확히 할 수 있도록 프록시 하나로 시작하세요. 대신 proxyCandidates를 사용한다면 경로, 쿼리, 프래그먼트가 없는 서로 다른 HTTP 또는 HTTPS 프록시 URL을 최대 12개 제공하세요. 후보를 제공하면 서비스가 다른 외부 연결 경로를 시도할 수 있지만, 프록시나 대상이 정상 작동한다고 보장하지는 않습니다.

CapSolver는 clientKey와 taskId를 사용한 getTaskResult로 비동기 결과를 조회합니다. solvethree는 Bearer 인증을 사용하는 GET /v1/tasks/:id로 조회합니다. HTTP 호출뿐 아니라 결과 파서도 업데이트하세요. CapSolver의 상태 및 오류 필드는 다른 API 규약을 따릅니다.

1. 1.

   먼저 HTTP 응답 확인

   성공 페이로드를 읽기 전에 성공이 아닌 HTTP 응답을 처리하세요. HTTP 요청 오류와 해결 작업 실패는 별도로 처리해야 합니다.

2. 2.

   생성 시 반환된 작업 확인

   reCAPTCHA 생성은 기본적으로 최대 15초 동안 대기하므로 응답이 이미 최종 상태일 수 있습니다. ready에만 사용 가능한 솔루션이 들어 있습니다. 작업이 pending 또는 solving 상태라면 반환된 solvethree 작업 ID로 조회하세요.

3. 3.

   ready 또는 failed 상태에서 폴링 중지

   ready 상태라면 솔루션을 제출 코드에 전달하세요. failed 상태라면 errorCode와 error를 확인하고 해당 작업의 폴링을 중지하세요. 해결에 실패한 작업은 환불됩니다. 유효하지 않은 입력을 바꾸지 않고 무작정 재시도하거나 모든 실패가 크레딧 부족을 의미한다고 단정하지 마세요.

단계적으로 마이그레이션하는 동안 각 작업 ID에 제공업체를 표시해 두세요. 기존 CapSolver 작업은 CapSolver를 통해 완료하고 새 solvethree 작업은 solvethree로 처리하세요. 기존 제공업체의 작업 ID를 새 API로 보내는 대신 어댑터에서 각 결과를 정규화하세요.

reCAPTCHA 결과를 의도한 대상에 제출할 때는 solution.token을 사용하세요. 반환된 userAgent와 secChUa도 보관하고, 제출에는 성공한 프록시를 사용하세요. 기존 어댑터가 토큰 문자열만 반환한다면 이 정보가 제출 클라이언트까지 전달되도록 변경하세요.

ready 상태의 토큰이 거부되면 다른 해결 작업에 비용을 지불하기 전에 전송되는 애플리케이션 요청을 확인하세요. 작업 ID나 이전 토큰이 아닌 새 토큰이 포함되어 있는지, 제출 시 반환된 브라우저 식별 정보, 성공한 프록시, 의도한 대상 URL을 사용하는지 확인하세요. ready 상태의 작업은 솔루션이 생성되었다는 뜻이지, 대상이 이후 요청을 수락했다는 뜻은 아닙니다.

변경 후 예제에는 복구를 위한 requestId가 포함되어 있습니다. 새 논리적 작업마다 하나씩 생성하고 정확한 요청 입력과 함께 보관하세요. ASCII 문자, 숫자, 밑줄 또는 하이픈으로 구성된 1–64자여야 합니다. 동일한 작업 요청에 재사용하면 기존 작업을 반환하고, 다른 입력에 사용하면 충돌이 발생합니다.

생성 요청이 시간 초과되면 ID가 있는 경우 해당 작업을 조회하고, 없다면 동일한 requestId로 동일한 본문을 다시 제출하세요. 응답이 유실되었다고 해서 생성이 실패한 것은 아닙니다. 클라이언트가 대기를 중단했다는 이유만으로 새 ID를 생성하지 마세요.

클라이언트 시간 제한에는 reCAPTCHA의 기본 생성 대기 시간인 최대 15초와 네트워크 오버헤드를 반영하세요. GET 폴링은 기본적으로 대기 없이 반환되며 최대 15000의 waitMs를 허용합니다. waitMs는 작업 JSON이 아닌 URL 쿼리에 넣고, 폴링 시간 제한에도 해당 대기 시간을 반영하세요.