Node.js로 reCAPTCHA Enterprise 해결하기

solvethree.com에서 공식 패키지를 직접 설치합니다:

npm install https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz

1. 1.

   사이트 프로필 활성화

   콘솔에서 대상 사이트를 설정하고 해당 프로필이 활성 상태이며 워크스페이스에서 사용할 수 있는지 확인하세요. 호스트 이름과 액션을 보내도 프로필이 생성되지는 않습니다. 사이트 프로필 설정을 참조하세요.

2. 2.

   서버 환경 설정

   Node.js 프로세스의 환경에서 SOLVETHREE_API_KEY를 워크스페이스 API 키로, SOLVETHREE_PROXY를 프록시 URL로 설정하세요. API 키는 서버에 보관하고 브라우저 코드에 노출하지 마세요.

3. 3.

   스크립트 준비

   다음 예제를 solve.mjs로 저장하세요. accounts.example.com을 구성한 호스트 이름으로, login을 페이지의 실제 reCAPTCHA 액션으로 바꾸세요.

site에는 페이지 URL이 아닌 호스트 이름을 사용하세요. reCAPTCHA의 기본값은 enterprise-v3이므로 이 예제에는 recaptchaType이 필요하지 않습니다. type이나 url을 추가하지 마세요. 요청에는 proxy와 proxyCandidates 중 정확히 하나가 필요합니다. 이 예제는 단일 프록시를 사용합니다.

import { randomUUID } from 'node:crypto';
import { Solvethree, SolvethreeError, TaskFailedError } from '@solvethree/sdk';

const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const request = {
  site: 'accounts.example.com', // Use your configured hostname.
  action: 'login',              // Use the page's actual action.
  proxy: process.env.SOLVETHREE_PROXY,
  requestId: randomUUID(),
};
let result;
try {
  result = await client.solve(request, { timeoutMs: 180_000 });
} catch (error) {
  if (error instanceof TaskFailedError) {
    throw new Error(`Task failed: ${error.errorCode}`);
  }
  if (error instanceof SolvethreeError) {
    // Save these IDs; use them to recover the existing task.
    console.error({ requestId: error.requestId, taskId: error.taskId });
  }
  throw error;
}
const { token, userAgent, secChUa } = result.solution;
console.log('Ready task:', result.id); // Keep solution credentials private.

환경 변수를 설정한 후 Node.js로 스크립트를 실행하세요. solve는 작업을 한 번 생성하고 준비 상태가 되거나 예외가 발생할 때까지 폴링합니다. 180,000 ms 시간 제한은 클라이언트의 대기 시간을 제한합니다.

반환된 필드의 역할은 각각 다릅니다:

• result.id는 작업을 식별합니다. CAPTCHA 토큰이 아닙니다.
• result.solution.token은 애플리케이션의 CAPTCHA 필드에 제출할 값입니다.
• result.solution.userAgent와 result.solution.secChUa는 해당 토큰과 함께 사용할 브라우저 식별 정보입니다.

솔루션 값은 비공개로 유지하세요. 프로세스 재시작 후 복구가 필요하다면 solve를 호출하기 전에 requestId와 정확한 작업 입력을 저장하고 프록시 자격 증명도 보호하세요.

solve가 반환되면 같은 스크립트에서 계속 진행하세요. 이 예제는 undici를 사용하며, 주석에 설명된 대로 별도로 설치해야 합니다. 토큰은 request.proxy를 통해 전송되며 반환된 브라우저 식별 정보 필드 두 개를 모두 사용합니다.

// Continue after client.solve(). Install undici separately: npm install undici@7.
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent(request.proxy);
try {
  // Replace the URL and form fields with your application's contract.
  const response = await fetch('https://accounts.example.com/login', {
    method: 'POST',
    dispatcher,
    redirect: 'manual',
    headers: {
      'user-agent': result.solution.userAgent,
      'sec-ch-ua': result.solution.secChUa,
    },
    body: new URLSearchParams({
      'g-recaptcha-response': result.solution.token,
    }),
    signal: AbortSignal.timeout(30_000),
  });
  console.log('Application HTTP status:', response.status);
  await response.arrayBuffer();
} finally {
  await dispatcher.close();
}

URL과 폼 필드를 애플리케이션의 요청 규격에 맞게 바꾸세요. 이 예제는 g-recaptcha-response만 제공하므로 애플리케이션에 필요한 다른 필드와 세션 데이터도 포함하세요. 대상은 해결 요청에 사용한 사이트 및 액션과 일치해야 합니다.

해결 요청이 프록시 하나를 사용하므로 request.proxy를 재사용하면 제출에도 해당 프록시가 사용됩니다. 요청을 proxyCandidates를 사용하도록 변경한다면 SDK의 successfulProxy 헬퍼로 성공한 프록시를 선택하세요.

준비된 작업은 솔루션이 생성되었다는 뜻이지 대상이 애플리케이션 요청을 수락했다는 뜻은 아닙니다. 대상의 응답에서 실제 성공 조건을 확인하세요. HTTP 상태를 출력하는 것만으로는 충분하지 않습니다. 거부 원인을 진단하려면 준비된 토큰의 거부를 참조하세요.

해결 예제는 최종 작업 실패와 다른 SDK 오류를 구분합니다. 이 구분을 유지하세요. 작업 실패와 HTTP 요청 실패는 서로 다르게 처리해야 합니다.

solve에서 TaskFailedError 발생

예외에는 errorCode와 taskId가 포함됩니다. 오류 텍스트를 포함한 전체 실패 작업 응답이 필요하면 getTask(taskId)를 호출하세요.

다음을 시도해 보세요: 해당 작업의 폴링을 중단하고 보고된 원인을 해결한 뒤 새 작업을 생성하세요. 잘못된 입력을 그대로 재시도하지 마세요.

SolvethreeError에 taskId 포함

SDK에 기존 작업의 ID가 있습니다.

다음을 시도해 보세요: getTask로 폴링을 재개하세요. pending 또는 solving 상태에서는 계속 진행하고, ready 상태일 때만 솔루션을 사용하며, failed 상태에서는 중단하세요.

생성이 중단되고 requestId만 사용 가능

연결 시간이 초과되었다고 해서 작업이 생성되지 않았다는 뜻은 아닙니다.

다음을 시도해 보세요: 동일한 작업 입력과 같은 requestId로 createTask를 사용해 복구하세요. 다른 입력으로 해당 ID를 재사용하면 충돌이 발생합니다.

API에서 HTTP 요청 거부

응답을 준비되거나 실패한 작업으로 취급하지 말고 ApiError가 제공하는 HTTP 상태를 확인하세요.

다음을 시도해 보세요: 성공 페이로드를 처리하기 전에 HTTP 오류를 해결하세요. 모든 실패가 크레딧 부족 때문이라고 가정하지 마세요.

이 샘플은 프로그램이 시작될 때마다 새 requestId를 생성합니다. 변경 없이 다시 실행하는 것은 복구가 아닙니다. 대신 저장한 요청과 ID를 사용하세요. SDK는 작업 생성을 자동으로 재시도하지 않습니다. 다만 해결 기한 내에 일시적인 폴링 실패가 발생하면 Retry-After를 따릅니다.

명시적 폴링 및 대기 설정은 작업 폴링 및 시간 제한을 참조하세요.