Laravel에서 CAPTCHA API 호출하기

작성: solvethree읽는 데 3분

Laravel의 HTTP 클라이언트로 solvethree 작업을 생성한 다음 해당 ID로 작업을 조회하세요. API 키와 프록시 자격 증명은 서버에 보관하세요. HTTP 응답이 성공했다는 것만으로는 충분하지 않습니다. 솔루션을 사용하기 전에 작업 상태를 확인하세요.

이 페이지의 내용

사이트 및 서버 자격 증명 구성

  1. 1.

    사이트 프로필 활성화

    워크스페이스에 활성 reCAPTCHA 프로필이 있도록 콘솔에서 대상 호스트 이름을 설정하세요. 작업에 호스트 이름을 보내도 프로필이 생성되지는 않습니다. 사이트 프로필 설정을 참고하세요.

  2. 2.

    서버 설정 추가

    config/services.php의 기존 배열에 예제의 solvethree 항목을 추가하세요. 서버 환경에 SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY를 설정하세요. 이 값들을 브라우저 코드에 넣지 마세요. CAPTCHA_SITE는 전체 URL이 아니라 호스트 이름입니다.

  3. 3.

    대상 액션에 맞추기

    예제는 login을 전송합니다. 의도한 대상 요청에서 사용하는 액션으로 바꾸세요. proxy 하나를 제공하므로 proxyCandidates를 함께 보내지 마세요.

생성과 조회 메서드가 분리된 서비스 만들기

Laravel 서비스 · 인증된 HTTP 생성 및 조회
<?php
// app/Services/CaptchaApi.php — configure services.solvethree in config/services.php.
namespace App\Services;

use Illuminate\Support\Facades\Http;
use InvalidArgumentException;

final class CaptchaApi
{
    private function client()
    {
        return Http::baseUrl('https://api.solvethree.com/v1')
            ->withToken(config('services.solvethree.key'))
            ->acceptJson()->asJson()->connectTimeout(10)->timeout(25);
    }

    public function create(string $requestId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,64}$/', $requestId)) {
            throw new InvalidArgumentException('Invalid logical request ID');
        }
        // The caller keeps this requestId; do not generate another on a timeout.
        return $this->client()->post('/tasks?waitMs=0', [
            'site' => config('services.solvethree.site'),
            'action' => 'login',
            'proxy' => config('services.solvethree.proxy'),
            'requestId' => $requestId,
        ])->throw()->json();
    }

    public function retrieve(string $taskId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,128}$/', $taskId)) {
            throw new InvalidArgumentException('Invalid task ID');
        }
        return $this->client()->get('/tasks/'.rawurlencode($taskId), ['waitMs' => 15000])
            ->throw()->json();
    }
}
// config/services.php entry:
// 'solvethree' => ['key' => env('SOLVETHREE_API_KEY'),
//   'site' => env('CAPTCHA_SITE'), 'proxy' => env('SOLVETHREE_PROXY')],
// Invoke from your authenticated controller/job. Poll retrieve only while pending
// or solving; ready contains the solution, failed is terminal. Never use retry()
// on create without preserving both this ID and the exact original inputs.

withToken은 워크스페이스 키를 Bearer 인증으로 전송합니다. POST 본문은 평면 구조이며 site, action, proxy, requestId는 최상위 필드입니다. reCAPTCHA에는 type 또는 url 필드를 추가하지 마세요. recaptchaType을 생략하면 문서에 명시된 기본값인 enterprise-v3가 선택됩니다.

두 메서드 모두 json() 전에 throw()를 호출합니다. Laravel의 HTTP 클라이언트는 기본적으로 실패한 HTTP 응답에 대해 예외를 발생시키지 않으므로, 이 호출은 호출자가 HTTP 오류 페이로드를 성공한 작업 응답으로 취급하지 않도록 합니다. 서비스는 연결 및 요청 시간 제한을 설정하며, 의도적으로 POST 자동 재시도를 하지 않습니다.

작업 ID 보관 및 상태 확인

  1. 1.

    논리적 풀이 요청마다 한 번만 생성

    인증된 컨트롤러나 잡에서 create를 호출하기 전에 호출자가 생성한 requestId를 보관하세요. 이 값은 1–64자의 ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 구성되어야 합니다. 반환된 작업 ID는 별도로 저장하세요. 논리적 요청 ID는 생성 복구용이며, retrieve에는 작업 ID를 전달합니다.

  2. 2.

    기존 작업 조회

    저장한 작업 ID로 retrieve를 호출하세요. 상태가 pending 또는 solving이면 컨트롤러에서 쉬지 않고 반복 조회하는 대신 나중에 다시 조회하도록 예약하세요. 호출자에게 전체 대기 기한을 설정하세요. 서비스의 HTTP 시간 제한은 각 요청을 제한하며 풀이 수명을 제한하지 않습니다. 기한에 도달했다는 이유로 새 작업을 생성하지 마세요.

  3. 3.

    최종 결과 처리

    failed이면 조회를 중단하고 errorCode와 error를 확인하세요. 풀이에 실패하면 환불됩니다. ready이면 반환된 솔루션 토큰을 사용하세요. 반환된 userAgent 및 secChUa 식별 정보와 풀이에 사용한 프록시로 제출하세요. 준비된 솔루션도 대상의 수락을 받아야 합니다.

HTTP 오류와 작업 실패를 구분하세요. 실패한 HTTP 응답은 throw()로 처리하며, failed가 포함된 성공 응답은 작업 수준에서 처리해야 합니다. 잘못된 입력을 변경 없이 재시도하거나 모든 실패를 잔액 부족으로 단정하지 마세요. API 오류 처리를 참고하세요.

다른 풀이를 구매하지 않고 시간 초과된 생성 요청 복구

연결 시간 초과만으로는 solvethree가 작업을 생성했는지 알 수 없습니다. 작업 ID가 이미 있다면 해당 작업을 조회하세요. 없다면 같은 requestId와 정확히 동일한 작업 입력으로 생성을 다시 요청하여 기존 작업을 복구하세요.

첫 작업을 실행하세요.

워크스페이스 크레딧 $5로 시작하세요.

워크스페이스 만들기
Laravel에서 CAPTCHA API 호출하기 · solvethree