공식 [검증된 CaptchaSonic 커뮤니티 노드](https://n8n.io/integrations/captchasonic/)로 **n8n 워크플로**에서 CAPTCHA 해결을 자동화하세요. 노드를 캔버스에 끌어다 놓고 CAPTCHA를 지정하면 해결된 토큰이나 답을 반환합니다. HTTP 연결 작업, 이미지 스크래핑, 프록시 설정이 필요 없습니다.

> [!TIP]
> 이 노드는 **20종 이상의 캡차 유형**을 지원하며, **독립형 워크플로 노드**와 **n8n AI Agent 노드의 도구**로 모두 사용할 수 있습니다. 전체 목록은 [기능 매트릭스](/docs/clients-sdks/capabilities)를 참고하세요.

**링크:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [n8n.io 목록](https://n8n.io/integrations/captchasonic/)

---

## 사전 요구 사항

- 실행 중인 **n8n 인스턴스** (self-hosted 또는 n8n Cloud)
- **CaptchaSonic API 키** — [my.captchasonic.com](https://my.captchasonic.com)에서 발급받은 뒤 [잔액 충전](/docs/guides/add-funds)
- **Node.js 18+** (self-hosted 전용)

---

## 설치

1. n8n 인스턴스를 열고 **Settings → Community Nodes**로 이동합니다.
2. **Install**을 클릭하고 다음을 입력합니다:
   ```
   n8n-nodes-captchasonic
   ```
3. **Self-hosted:** 설치 후 n8n을 재시작합니다. **Cloud:** 노드가 자동으로 로드됩니다.
4. **확인** — 노드 팔레트(**+** 클릭)를 열고 `CaptchaSonic`을 검색하여 노드가 나타나는지 확인합니다.

> [!NOTE]
> 이 노드는 [n8n 검증](https://n8n.io/integrations/captchasonic/)을 받았으며 공식 통합 디렉터리에 등록되어 있습니다.

---

## 자격 증명 설정

1. n8n에서 **Credentials → Add Credential**로 이동하여 **CaptchaSonic API**를 검색합니다.
2. [대시보드](https://my.captchasonic.com)에서 복사한 **API 키**를 붙여 넣습니다.
3. **Save**를 클릭합니다. 자격 증명은 연결을 자동으로 테스트합니다.

이제 워크플로의 모든 CaptchaSonic 노드에서 이 자격 증명을 사용할 수 있습니다.

---

## 빠른 시작 워크플로

가장 간단한 워크플로: 트리거 → 해결 → 출력.

```json
{
  "nodes": [
    {
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300]
    },
    {
      "name": "CaptchaSonic",
      "type": "n8n-nodes-captchasonic.captchaSonic",
      "position": [450, 300],
      "parameters": {
        "operation": "solveCaptcha",
        "captchaType": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://example.com/login",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
      }
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [[ { "node": "CaptchaSonic", "type": "main", "index": 0 } ]]
    }
  }
}
```

> [!TIP]
> 위 JSON을 복사한 뒤 빈 캔버스에서 **Import from clipboard**(Ctrl/⌘ + V)를 사용하면 워크플로를 바로 불러올 수 있습니다.

---

## 작업 참조

### CAPTCHA 해결

기본 작업입니다. 캡차 유형을 선택하고 필요한 매개변수를 입력하세요.

#### 토큰 작업 (브라우저 자동화)

| 캡차 유형 | 필수 매개변수 | 반환값 |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | `gRecaptchaResponse` 토큰 |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | `gRecaptchaResponse` 토큰 |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### 인식 작업 (이미지 기반)

| 캡차 유형 | 필수 매개변수 | 반환값 |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (base64 이미지) | `text` |
| **PopularCaptcha (이미지 그리드)** | `images`, `question` | `solution` 배열 |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | solver 출력 |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | `images` 배열 | `solution` |

> [!NOTE]
> 이미지 기반 작업에서는 이미지를 **원시 base64 문자열**(`data:image/…;base64,` 접두사 제외)로 제공하세요. 상위 노드가 접두사를 추가한다면 **Function** 노드로 접두사를 제거하세요.

### 잔액 확인

현재 USD 잔액을 반환합니다. 일괄 작업 전에 가드로 사용하세요.

---

## 워크플로 레시피

### 레시피 1: 웹 스크래핑 파이프라인의 reCAPTCHA v2

**트리거 → HTTP Request(페이지 가져오기) → CaptchaSonic(reCAPTCHA 해결) → HTTP Request(폼 제출)**

1. **Schedule Trigger**가 매시간 실행됩니다.
2. **HTTP Request**가 대상 페이지를 가져오고 **Function** 노드로 `siteKey`를 추출합니다.
3. **CaptchaSonic**이 `ReCaptchaV2TaskProxyLess`로 reCAPTCHA를 해결합니다.
4. 두 번째 **HTTP Request**가 해결된 `gRecaptchaResponse`로 폼을 제출합니다.

---

### 레시피 2: 모니터링을 위한 Cloudflare Turnstile 우회

**Schedule Trigger → CaptchaSonic(Turnstile 해결) → HTTP Request(보호된 API 접근)**

1. **Schedule Trigger**가 15분마다 실행됩니다.
2. **CaptchaSonic**이 `AntiTurnstileTaskProxyLess`로 Turnstile 챌린지를 해결합니다.
3. **HTTP Request**가 해결된 토큰을 쿠키 또는 헤더로 사용해 보호된 엔드포인트를 호출합니다.

---

### 레시피 3: 이미지-텍스트 OCR 일괄 처리

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic(OCR) → Google Sheets(결과 쓰기)**

1. **Google Sheets Trigger**가 이미지 URL이 있는 새 행을 감지합니다.
2. **Loop Over Items**가 각 행을 순회합니다.
3. **HTTP Request**가 이미지를 다운로드하고 **Function**이 base64로 변환합니다.
4. **CaptchaSonic**이 `ImageToTextTask`로 OCR을 실행합니다.
5. **Google Sheets**가 추출된 텍스트를 해당 행에 다시 씁니다.

---

### 레시피 4: 일괄 실행 전 잔액 가드

**Manual Trigger → CaptchaSonic(잔액 확인) → IF(< $5) → Stop / Continue**

1. **Manual Trigger**가 일괄 작업을 시작합니다.
2. `getBalance` 작업의 **CaptchaSonic** 노드가 `{ balance: 12.50 }`을 반환합니다.
3. **IF** 노드가 `{{ $json.balance < 5 }}`를 확인합니다.
4. **True 경로:** "잔액 부족 — 충전해 주세요." 메시지가 있는 **Stop and Error** 노드로 이동합니다.
5. **False 경로:** 메인 해결 루프를 계속 진행합니다.

> [!TIP]
> 워크플로가 조용히 실패하기 전에 알림을 받을 수 있도록 잔액 부족 경로에 **Send Email** 노드를 추가하세요.

---

## 오류 처리

### 자주 발생하는 오류와 해결 방법

| 오류 | 원인 | 해결 방법 |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | 잘못된 API 키 | **Credentials → CaptchaSonic API**에서 키를 다시 입력하세요 |
| `ERROR_ZERO_BALANCE` | 남은 크레딧 없음 | [잔액 충전](/docs/guides/add-funds)을 하거나 위의 잔액 가드 레시피를 사용하세요 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 잘못된 siteKey, URL 또는 이미지 | 매개변수가 실제 페이지와 일치하는지 확인하고 한 번 재시도하세요 |
| `TIMEOUT` | 해결 시간 초과 | 노드의 timeout 설정을 늘리고 캡차 유형이 맞는지 확인하세요 |

### 재시도 패턴

CaptchaSonic 노드의 **오류 출력**을 재시도 루프에 연결하세요:

**CaptchaSonic → (오류) → Wait(5초) → CaptchaSonic(재시도)**

무한 루프를 막으려면 Wait 뒤에 **IF** 노드를 두고 재시도를 3회로 제한하세요.

### 잔액 가드 패턴

일괄 작업 전에는 항상 잔액을 확인하세요. [레시피 4](#recipe-4-balance-guard-before-batch-execution)를 참고하세요.

---

## AI 에이전트 도구로 사용하기

n8n **AI Agent** 노드는 CaptchaSonic을 도구로 호출할 수 있으므로, 에이전트가 대화나 작업 중 필요할 때 CAPTCHA 해결 여부를 동적으로 결정합니다.

1. 캔버스에 **CaptchaSonic** 노드를 추가합니다.
2. **AI Agent** 노드에서 **Tools → Add Tool**로 이동하고 CaptchaSonic 노드를 선택합니다.
3. 이제 에이전트는 `solveCaptcha` 및 `getBalance` 작업을 사용할 수 있으며, 대화 맥락에 따라 이를 호출합니다.

> [!NOTE]
> 순수 코드 에이전트 워크플로(Claude Code, Cursor 등)라면 대신 [MCP 서버 설정](/docs/mcp/get-started)을 참고하세요. 에이전트의 도구 시스템에 직접 연결됩니다.

---

## 팁과 권장 사항

- 가능하면 **ProxyLess 작업 유형**을 사용하세요. 더 간단하고 빠릅니다.
- 일부만 실행되는 것을 피하려면 일괄 작업 전에 **먼저 잔액을 확인**하세요.
- 캡차 유형에 맞게 **timeout 값을 설정**하세요(토큰: 60초, 이미지: 30초).
- 해결이 실패할 때 알림(Slack, 이메일)을 보내려면 **n8n의 오류 워크플로**를 사용하세요.
- 워크플로를 만드는 동안 크레딧이 소모되지 않도록 테스트 모드에서 결과를 **고정(Pin)**하세요.

---

## 문제 해결

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 설치 후 노드가 팔레트에 없음 | n8n이 다시 로드되지 않음 | n8n을 재시작하거나(self-hosted) 브라우저를 새로 고치세요 |
| "Invalid credentials" | 키 만료 또는 오타 | [대시보드](https://my.captchasonic.com)에서 키를 재발급하고 자격 증명을 업데이트하세요 |
| 작업이 "processing"에서 멈춤 | 캡차 유형 불일치 또는 사이트 변경 | 매개변수가 실제 페이지와 일치하는지 확인하고 다른 작업 유형을 시도하세요 |
| 요청 한도 오류 | 동시 요청이 너무 많음 | 해결 사이에 **Wait** 노드(1–2초)를 추가하세요 |

---

## 리소스

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [n8n.io 목록](https://n8n.io/integrations/captchasonic/)
- [CaptchaSonic 대시보드](https://my.captchasonic.com)
- [REST API 참조](/docs/api)
- [기능 매트릭스](/docs/clients-sdks/capabilities)
- [AI 에이전트 & MCP](/docs/clients-sdks/ai-agents)
