Otomatiskan penyelesaian CAPTCHA di **workflow n8n** Anda dengan [community node CaptchaSonic resmi yang terverifikasi](https://n8n.io/integrations/captchasonic/). Seret node ke canvas, arahkan ke CAPTCHA, dan node akan mengembalikan token atau jawaban yang sudah diselesaikan — tanpa perlu HTTP manual, tanpa scraping gambar, tanpa setup proxy.

> [!TIP]
> Node ini mendukung **20+ jenis captcha** dan dapat digunakan sebagai **node workflow mandiri** maupun sebagai **tool untuk node AI Agent n8n**. Lihat [matriks kemampuan](/docs/clients-sdks/capabilities) untuk daftar lengkapnya.

**Tautan:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [daftar n8n.io](https://n8n.io/integrations/captchasonic/)

---

## Prasyarat

- Instance **n8n** yang berjalan (self-hosted atau n8n Cloud)
- **API key CaptchaSonic** — dapatkan dari [my.captchasonic.com](https://my.captchasonic.com), lalu [isi saldo](/docs/guides/add-funds)
- **Node.js 18+** (hanya self-hosted)

---

## Instalasi

1. Buka instance n8n Anda lalu buka **Settings → Community Nodes**.
2. Klik **Install** dan masukkan:
   ```
   n8n-nodes-captchasonic
   ```
3. **Self-hosted:** mulai ulang n8n setelah instalasi. **Cloud:** node dimuat otomatis.
4. **Verifikasi** — buka palet node (klik **+**), cari `CaptchaSonic`, dan pastikan node muncul.

> [!NOTE]
> Node ini [terverifikasi oleh n8n](https://n8n.io/integrations/captchasonic/) dan tercantum di direktori integrasi resmi.

---

## Setup credential

1. Di n8n, buka **Credentials → Add Credential** lalu cari **CaptchaSonic API**.
2. Tempel **API key** Anda dari [dashboard](https://my.captchasonic.com).
3. Klik **Save** — credential akan menguji koneksi secara otomatis.

Credential ini sekarang dapat digunakan oleh node CaptchaSonic mana pun di workflow Anda.

---

## Workflow mulai cepat

Workflow paling sederhana: trigger → selesaikan → output.

```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]
> Salin JSON di atas lalu **Import from clipboard** (Ctrl/⌘ + V pada canvas kosong) untuk memuat workflow seketika.

---

## Referensi operasi

### Selesaikan CAPTCHA

Operasi utama. Pilih jenis captcha lalu isi parameter yang diperlukan.

#### Task token (otomatisasi browser)

| Jenis Captcha | Parameter Wajib | Mengembalikan |
|---|---|---|
| **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` |

#### Task recognition (berbasis gambar)

| Jenis Captcha | Parameter Wajib | Mengembalikan |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (gambar base64) | `text` |
| **PopularCaptcha (grid gambar)** | `images`, `question` | array `solution` |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | output solver |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | array `images` | `solution` |

> [!NOTE]
> Untuk task berbasis gambar, berikan gambar sebagai **string base64 mentah** (tanpa prefix `data:image/…;base64,`). Gunakan node **Function** untuk menghapus prefix jika node sebelumnya menambahkannya.

### Cek saldo

Mengembalikan saldo kredit Anda saat ini dalam USD. Gunakan sebagai pengaman sebelum operasi batch.

---

## Resep workflow

### Resep 1: reCAPTCHA v2 dalam pipeline web scraping

**Trigger → HTTP Request (ambil halaman) → CaptchaSonic (selesaikan reCAPTCHA) → HTTP Request (kirim formulir)**

1. **Schedule Trigger** berjalan setiap jam.
2. **HTTP Request** mengambil halaman target dan mengekstrak `siteKey` dengan node **Function**.
3. **CaptchaSonic** menyelesaikan reCAPTCHA menggunakan `ReCaptchaV2TaskProxyLess`.
4. **HTTP Request** kedua mengirim formulir dengan `gRecaptchaResponse` yang sudah diselesaikan.

---

### Resep 2: Bypass Cloudflare Turnstile untuk monitoring

**Schedule Trigger → CaptchaSonic (selesaikan Turnstile) → HTTP Request (akses API yang dilindungi)**

1. **Schedule Trigger** berjalan setiap 15 menit.
2. **CaptchaSonic** menyelesaikan tantangan Turnstile dengan `AntiTurnstileTaskProxyLess`.
3. **HTTP Request** memanggil endpoint yang dilindungi dengan menggunakan token hasil sebagai cookie atau header.

---

### Resep 3: OCR gambar ke teks secara batch

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (tulis hasil)**

1. **Google Sheets Trigger** mendeteksi baris baru yang berisi URL gambar.
2. **Loop Over Items** mengulangi setiap baris.
3. **HTTP Request** mengunduh gambar, **Function** mengubahnya menjadi base64.
4. **CaptchaSonic** menjalankan OCR dengan `ImageToTextTask`.
5. **Google Sheets** menulis teks hasil kembali ke baris.

---

### Resep 4: Pengaman saldo sebelum eksekusi batch

**Manual Trigger → CaptchaSonic (cek saldo) → IF (< $5) → Stop / Continue**

1. **Manual Trigger** memulai batch.
2. Node **CaptchaSonic** dengan operasi `getBalance` mengembalikan `{ balance: 12.50 }`.
3. Node **IF** memeriksa `{{ $json.balance < 5 }}`.
4. **Jalur true:** node **Stop and Error** dengan pesan "Saldo rendah — silakan isi ulang."
5. **Jalur false:** lanjut ke loop penyelesaian utama.

> [!TIP]
> Tambahkan node **Send Email** pada jalur saldo rendah untuk memberi tahu Anda sebelum workflow gagal tanpa suara.

---

## Penanganan error

### Error umum dan solusinya

| Error | Penyebab | Solusi |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | API key tidak valid | Masukkan ulang key Anda di **Credentials → CaptchaSonic API** |
| `ERROR_ZERO_BALANCE` | Kredit habis | [Isi saldo](/docs/guides/add-funds), atau gunakan resep pengaman saldo di atas |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey, URL, atau gambar tidak tepat | Pastikan parameter sesuai dengan halaman live; coba ulang sekali |
| `TIMEOUT` | Penyelesaian terlalu lama | Tambah pengaturan timeout node; pastikan jenis captcha sudah benar |

### Pola retry

Hubungkan **error output** node CaptchaSonic ke loop retry:

**CaptchaSonic → (error) → Wait (5 dtk) → CaptchaSonic (retry)**

Gunakan node **IF** setelah Wait untuk membatasi retry hingga 3 kali agar tidak terjadi loop tak terbatas.

### Pola pengaman saldo

Selalu cek saldo sebelum operasi batch. Lihat [Resep 4](#recipe-4-balance-guard-before-batch-execution) di atas.

---

## Menggunakan sebagai tool AI agent

Node **AI Agent** n8n dapat memanggil CaptchaSonic sebagai tool, sehingga agent memutuskan sendiri kapan menyelesaikan CAPTCHA selama percakapan atau tugas.

1. Tambahkan node **CaptchaSonic** ke canvas.
2. Di node **AI Agent**, buka **Tools** → **Add Tool** → pilih node CaptchaSonic Anda.
3. Agent sekarang memiliki akses ke operasi `solveCaptcha` dan `getBalance` dan akan memanggilnya saat konteks percakapan membutuhkannya.

> [!NOTE]
> Untuk workflow code agent murni (Claude Code, Cursor, dll.), lihat [setup server MCP](/docs/mcp/get-started) sebagai gantinya — server ini terhubung langsung ke sistem tool agent.

---

## Tips & praktik terbaik

- **Gunakan jenis task ProxyLess** jika memungkinkan — lebih sederhana dan lebih cepat.
- **Cek saldo dulu** sebelum operasi batch untuk menghindari eksekusi yang terhenti di tengah.
- **Atur nilai timeout** sesuai jenis captcha (token: 60 dtk, gambar: 30 dtk).
- **Gunakan error workflow n8n** untuk mengirim peringatan (Slack, email) saat penyelesaian gagal.
- **Pin hasil** dalam mode test agar kredit tidak terpakai saat Anda membangun workflow.

---

## Pemecahan masalah

| Gejala | Penyebab | Solusi |
|---|---|---|
| Node tidak muncul di palet setelah instalasi | n8n belum dimuat ulang | Mulai ulang n8n (self-hosted) atau muat ulang browser |
| "Invalid credentials" | Key kedaluwarsa atau salah ketik | Buat ulang key di [dashboard](https://my.captchasonic.com) dan perbarui credential |
| Task macet di "processing" | Jenis captcha tidak cocok atau situs berubah | Pastikan parameter sesuai dengan halaman live; coba jenis task lain |
| Error rate-limit | Terlalu banyak permintaan bersamaan | Tambahkan node **Wait** (1–2 dtk) di antara penyelesaian |

---

## Sumber daya

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [daftar n8n.io](https://n8n.io/integrations/captchasonic/)
- [Dashboard CaptchaSonic](https://my.captchasonic.com)
- [Referensi REST API](/docs/api)
- [Matriks kemampuan](/docs/clients-sdks/capabilities)
- [AI agents & MCP](/docs/clients-sdks/ai-agents)
