Tự động giải CAPTCHA trong **quy trình n8n** của bạn với [node cộng đồng CaptchaSonic chính thức, đã được xác minh](https://n8n.io/integrations/captchasonic/). Kéo node vào canvas, trỏ đến CAPTCHA, và node sẽ trả về token hoặc đáp án đã giải — không cần thiết lập HTTP, không cần thu thập ảnh, không cần cấu hình proxy.

> [!TIP]
> Node hỗ trợ **hơn 20 loại captcha** và hoạt động cả như **node quy trình độc lập** lẫn như **công cụ cho node AI Agent của n8n**. Xem [bảng so sánh khả năng](/docs/clients-sdks/capabilities) để biết danh sách đầy đủ.

**Liên kết:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [Trang n8n.io](https://n8n.io/integrations/captchasonic/)

---

## Yêu cầu trước khi bắt đầu

- Một **instance n8n** đang chạy (tự lưu trữ hoặc n8n Cloud)
- **Khóa API CaptchaSonic** — lấy tại [my.captchasonic.com](https://my.captchasonic.com), sau đó [nạp tiền](/docs/guides/add-funds)
- **Node.js 18+** (chỉ khi tự lưu trữ)

---

## Cài đặt

1. Mở instance n8n và vào **Settings → Community Nodes**.
2. Nhấn **Install** và nhập:
   ```
   n8n-nodes-captchasonic
   ```
3. **Tự lưu trữ:** khởi động lại n8n sau khi cài. **Cloud:** node tự động được tải.
4. **Kiểm tra** — mở bảng node (nhấn **+**), tìm `CaptchaSonic` và xác nhận node xuất hiện.

> [!NOTE]
> Node đã [được n8n xác minh](https://n8n.io/integrations/captchasonic/) và có trong danh mục tích hợp chính thức.

---

## Thiết lập thông tin xác thực

1. Trong n8n, vào **Credentials → Add Credential** và tìm **CaptchaSonic API**.
2. Dán **khóa API** của bạn từ [bảng điều khiển](https://my.captchasonic.com).
3. Nhấn **Save** — thông tin xác thực sẽ tự động kiểm tra kết nối.

Thông tin xác thực này giờ có thể dùng cho mọi node CaptchaSonic trong quy trình của bạn.

---

## Quy trình bắt đầu nhanh

Quy trình đơn giản nhất: trigger → giải → đầu ra.

```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]
> Sao chép JSON ở trên và **Import from clipboard** (Ctrl/⌘ + V trên canvas trống) để tải quy trình ngay lập tức.

---

## Tham chiếu thao tác

### Giải CAPTCHA

Thao tác chính. Chọn loại captcha và cung cấp các tham số cần thiết.

#### Tác vụ token (tự động hóa trình duyệt)

| Loại Captcha | Tham số bắt buộc | Trả về |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | token `gRecaptchaResponse` |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | token `gRecaptchaResponse` |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### Tác vụ nhận dạng (dựa trên hình ảnh)

| Loại Captcha | Tham số bắt buộc | Trả về |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (ảnh base64) | `text` |
| **PopularCaptcha (lưới ảnh)** | `images`, `question` | mảng `solution` |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | kết quả từ solver |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | mảng `images` | `solution` |

> [!NOTE]
> Với tác vụ dựa trên hình ảnh, cung cấp ảnh dưới dạng **chuỗi base64 thuần** (không có tiền tố `data:image/…;base64,`). Dùng node **Function** để bỏ tiền tố nếu node phía trước của bạn có thêm vào.

### Kiểm tra số dư

Trả về số dư tín dụng hiện tại tính bằng USD. Dùng làm điều kiện chặn trước các thao tác hàng loạt.

---

## Công thức quy trình

### Công thức 1: reCAPTCHA v2 trong quy trình thu thập dữ liệu

**Trigger → HTTP Request (lấy trang) → CaptchaSonic (giải reCAPTCHA) → HTTP Request (gửi biểu mẫu)**

1. **Schedule Trigger** chạy mỗi giờ.
2. **HTTP Request** tải trang đích và trích xuất `siteKey` bằng node **Function**.
3. **CaptchaSonic** giải reCAPTCHA bằng `ReCaptchaV2TaskProxyLess`.
4. **HTTP Request** thứ hai gửi biểu mẫu với `gRecaptchaResponse` đã giải.

---

### Công thức 2: Vượt Cloudflare Turnstile để giám sát

**Schedule Trigger → CaptchaSonic (giải Turnstile) → HTTP Request (truy cập API được bảo vệ)**

1. **Schedule Trigger** chạy mỗi 15 phút.
2. **CaptchaSonic** giải thử thách Turnstile bằng `AntiTurnstileTaskProxyLess`.
3. **HTTP Request** gọi endpoint được bảo vệ, dùng token đã giải như cookie hoặc header.

---

### Công thức 3: OCR hàng loạt từ ảnh sang văn bản

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (ghi kết quả)**

1. **Google Sheets Trigger** phát hiện hàng mới có URL ảnh.
2. **Loop Over Items** duyệt qua từng hàng.
3. **HTTP Request** tải ảnh, **Function** chuyển thành base64.
4. **CaptchaSonic** chạy OCR với `ImageToTextTask`.
5. **Google Sheets** ghi văn bản trích xuất trở lại hàng.

---

### Công thức 4: Chặn theo số dư trước khi chạy hàng loạt

**Manual Trigger → CaptchaSonic (lấy số dư) → IF (< $5) → Stop / Continue**

1. **Manual Trigger** bắt đầu đợt chạy.
2. Node **CaptchaSonic** với thao tác `getBalance` trả về `{ balance: 12.50 }`.
3. Node **IF** kiểm tra `{{ $json.balance < 5 }}`.
4. **Nhánh đúng:** node **Stop and Error** với thông báo "Số dư thấp — vui lòng nạp thêm."
5. **Nhánh sai:** tiếp tục vòng lặp giải chính.

> [!TIP]
> Thêm node **Send Email** vào nhánh số dư thấp để tự cảnh báo trước khi quy trình lỗi âm thầm.

---

## Xử lý lỗi

### Lỗi thường gặp và cách khắc phục

| Lỗi | Nguyên nhân | Cách khắc phục |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Khóa API không hợp lệ | Nhập lại khóa trong **Credentials → CaptchaSonic API** |
| `ERROR_ZERO_BALANCE` | Hết tín dụng | [Nạp tiền](/docs/guides/add-funds), hoặc dùng công thức chặn số dư ở trên |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey, URL hoặc ảnh sai | Kiểm tra tham số khớp với trang đang hoạt động; thử lại một lần |
| `TIMEOUT` | Giải quá lâu | Tăng cài đặt timeout của node; kiểm tra loại captcha có đúng không |

### Mẫu thử lại

Nối **đầu ra lỗi** của node CaptchaSonic vào vòng lặp thử lại:

**CaptchaSonic → (lỗi) → Wait (5 s) → CaptchaSonic (thử lại)**

Dùng node **IF** sau Wait để giới hạn tối đa 3 lần thử, tránh vòng lặp vô hạn.

### Mẫu chặn theo số dư

Luôn kiểm tra số dư trước các thao tác hàng loạt. Xem [Công thức 4](#recipe-4-balance-guard-before-batch-execution) ở trên.

---

## Dùng như công cụ của AI Agent

Node **AI Agent** của n8n có thể gọi CaptchaSonic như một công cụ, nhờ đó agent tự quyết định khi nào cần giải CAPTCHA trong cuộc hội thoại hoặc tác vụ.

1. Thêm node **CaptchaSonic** vào canvas.
2. Trong node **AI Agent**, vào **Tools** → **Add Tool** → chọn node CaptchaSonic của bạn.
3. Agent giờ có quyền dùng các thao tác `solveCaptcha` và `getBalance`, và sẽ gọi chúng khi ngữ cảnh cuộc hội thoại yêu cầu.

> [!NOTE]
> Với quy trình agent viết mã thuần (Claude Code, Cursor, v.v.), xem [thiết lập máy chủ MCP](/docs/mcp/get-started) thay thế — nó kết nối trực tiếp với hệ thống công cụ của agent.

---

## Mẹo và thực hành tốt nhất

- **Dùng loại tác vụ ProxyLess** khi có thể — đơn giản và nhanh hơn.
- **Kiểm tra số dư trước** các thao tác hàng loạt để tránh chạy dở dang.
- **Đặt giá trị timeout** phù hợp với từng loại captcha (token: 60 s, hình ảnh: 30 s).
- **Dùng quy trình lỗi của n8n** để gửi cảnh báo (Slack, email) khi giải thất bại.
- **Ghim kết quả** ở chế độ thử nghiệm để không tốn tín dụng khi đang xây dựng quy trình.

---

## Khắc phục sự cố

| Triệu chứng | Nguyên nhân | Giải pháp |
|---|---|---|
| Không thấy node trong bảng sau khi cài | n8n chưa tải lại | Khởi động lại n8n (tự lưu trữ) hoặc làm mới trình duyệt |
| "Invalid credentials" | Khóa hết hạn hoặc nhập sai | Tạo lại khóa trong [bảng điều khiển](https://my.captchasonic.com) và cập nhật thông tin xác thực |
| Tác vụ kẹt ở "processing" | Sai loại captcha hoặc trang đã thay đổi | Kiểm tra tham số khớp với trang đang hoạt động; thử loại tác vụ khác |
| Lỗi giới hạn tần suất | Quá nhiều yêu cầu đồng thời | Thêm node **Wait** (1–2 s) giữa các lần giải |

---

## Tài nguyên

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [Trang n8n.io](https://n8n.io/integrations/captchasonic/)
- [Bảng điều khiển CaptchaSonic](https://my.captchasonic.com)
- [Tham chiếu REST API](/docs/api)
- [Bảng so sánh khả năng](/docs/clients-sdks/capabilities)
- [AI agents & MCP](/docs/clients-sdks/ai-agents)
