CAPTCHA 솔루션과 함께 Playwright APIRequestContext 사용

1. 1.

   의존성 설치

   Node.js 22+를 사용하고 playwright 패키지를 설치하세요. solvethree.com의 /downloads/에 있는 solvethree 버전 0.1.0 tarball인 solvethree-sdk-0.1.0.tgz에서 공식 JavaScript SDK를 설치하세요. 가져올 때는 @solvethree/sdk를 사용하며, 레지스트리에 릴리스가 있다고 가정하지 마세요.

2. 2.

   환경 변수 설정

   Node.js 프로세스에 SOLVETHREE_API_KEY, SOLVETHREE_PROXY, TARGET_URL을 제공하세요. 워크스페이스 API 키는 서버 측에만 보관하세요. TARGET_URL은 단순히 CAPTCHA가 표시되는 페이지가 아니라 실제 애플리케이션 POST 엔드포인트여야 합니다. 경로, 쿼리 또는 프래그먼트가 없는 HTTP 또는 HTTPS 프록시 URL을 사용하세요.

3. 3.

   사이트 프로필과 액션 확인

   대상 호스트 이름에는 워크스페이스에서 사용할 수 있는 활성 프로필이 필요합니다. CAPTCHA를 해결하기 전에 콘솔에서 설정하세요. 호스트 이름을 전달하는 것만으로는 프로필이 생성되지 않습니다. 예제에서는 login 액션을 사용합니다. 대상에서 다른 액션을 요구하면 변경하세요. 요청의 기본값은 reCAPTCHA Enterprise v3입니다.

예제를 실행하기 전에 애플리케이션에 필요한 폼 필드와 세션 요건을 준비하세요. 이 예제는 CAPTCHA 응답 필드만 전송합니다. 호스트 이름이 아직 구성되지 않았다면 사이트 프로필 설정을 참고하세요.

import { request } from 'playwright';
import { Solvethree } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const target = new URL(process.env.TARGET_URL);
const proxy = new URL(process.env.SOLVETHREE_PROXY);
const result = await client.solve({ site: target.hostname, action: 'login', proxy: process.env.SOLVETHREE_PROXY });
const proxyConfig = { server: `${proxy.protocol}//${proxy.host}`, username: decodeURIComponent(proxy.username), password: decodeURIComponent(proxy.password) };

const targetClient = await request.newContext({
  proxy: proxyConfig, timeout: 30000,
  extraHTTPHeaders: { 'User-Agent': result.solution.userAgent, 'sec-ch-ua': result.solution.secChUa },
  // storageState: 'your-application-session.json', // only if your flow needs it
});
try {
  const response = await targetClient.post(target.href, {
    form: { 'g-recaptcha-response': result.solution.token }, maxRedirects: 0,
  });
  console.log('Application HTTP status:', response.status());
  // Inspect the response and supply the application's actual fields/CSRF/session.
} finally { await targetClient.dispose(); }

client.solve()는 작업을 한 번 생성한 뒤, 준비가 완료되거나 예외가 발생할 때까지 폴링합니다. 예제에서는 CAPTCHA 해결과 제출에 동일한 프록시를 사용합니다. Playwright에 맞게 프록시 서버 주소와 인증 정보를 분리하고 사용자 이름과 비밀번호를 디코딩합니다.

요청 컨텍스트는 solution.userAgent와 solution.secChUa를 헤더로 적용합니다. 폼은 작업 ID가 아니라 solution.token을 g-recaptcha-response에 담아 전송합니다. 프록시와 반환된 식별 정보를 함께 유지하세요. 관련 없는 브라우저 헤더로 바꾸거나 토큰을 다른 대상으로 보내지 마세요.

필요한 경우 인증 정보나 CSRF 데이터를 포함해 애플리케이션의 실제 필드를 폼에 추가하세요. 필요한 애플리케이션 세션이 이미 있다면 선택 사항인 storageState 설정을 활성화하고 해당 세션의 저장된 상태를 지정하세요.

APIRequestContext는 자체 쿠키 저장소를 유지하므로 동일한 컨텍스트를 통해 보낸 요청에서는 수신한 쿠키가 유지됩니다. 별개의 브라우저 컨텍스트와 쿠키를 자동으로 공유하지는 않습니다. 사전 세션 요청과 최종 POST 요청이 쿠키를 공유해야 한다면 동일한 컨텍스트에서 수행하세요. 제출이 끝나면 finally 블록이 컨텍스트를 해제합니다.

예제는 애플리케이션의 HTTP 상태를 로그로 남길 뿐, 로그인 성공 여부를 확인하지는 않습니다. maxRedirects를 0으로 설정하면 리디렉션을 따라가지 않고 최초 응답을 확인할 수 있습니다. 응답 본문, 헤더, 쿠키를 애플리케이션에서 기대하는 성공 응답과 비교해 확인하세요. 리디렉션이나 HTTP 200만으로는 작업의 성공 여부를 알 수 없을 수 있습니다.

작업은 준비되었지만 애플리케이션이 POST 요청을 거부합니다.

먼저 전송되는 요청의 토큰 필드, 호스트 이름과 액션, 프록시, 반환된 식별 정보, 필수 폼 필드, CSRF 값, 세션 쿠키를 확인하세요.

다음을 시도해 보세요: 다른 CAPTCHA 해결에 비용을 지불하기 전에 누락되거나 일치하지 않는 요청 데이터를 수정하세요. 준비된 작업은 사용 가능한 해결 결과를 제공할 뿐, 대상 애플리케이션에서 수락된다고 보장하지는 않습니다.

CAPTCHA 해결이 작업 실패로 끝납니다.

errorCode와 error를 확인하세요. 모든 실패를 크레딧 문제로 간주하지 마세요.

다음을 시도해 보세요: 해당 작업의 폴링을 중단하고 보고된 원인을 해결하세요. 실패한 CAPTCHA 해결 비용은 환불됩니다. 오류 해석은 API 오류 처리를 참고하세요.

작업 생성 시간이 초과되거나 연결이 끊깁니다.

작업 ID가 있는지 또는 requestId를 사용했는지 확인하세요. 연결 시간 초과가 발생했다고 해서 생성에 실패한 것은 아닙니다.

다음을 시도해 보세요: 작업 ID가 있다면 기존 작업을 조회하세요. 생성 요청을 복구할 수 있도록 requestId를 제공하고, 완전히 동일한 입력값으로 이를 재사용하세요. 그러면 기존 작업이 반환됩니다. 별도의 CAPTCHA 해결 작업을 즉시 새로 시작하지 마세요.

애플리케이션 요청이 HTTP 오류를 반환합니다.

대상 응답을 solvethree 작업 결과와 별도로 확인하세요.

다음을 시도해 보세요: 응답 본문을 성공 페이로드로 처리하기 전에 성공이 아닌 응답을 처리하세요. 토큰이 원인이라고 단정하지 말고 애플리케이션 요청이나 보고된 서버 오류를 수정하세요.