SDK de Node.js
Biblioteca oficial de CaptchaSonic para Node.js y TypeScript — moderna, basada en Promises, con múltiples transportes (gRPC / ConnectRPC / HTTP).
El SDK de Node.js de CaptchaSonic (captchasonic) es una biblioteca moderna, basada en Promises y orientada a TypeScript, para resolver CAPTCHAs a gran escala. Cada método devuelve una Promise, incluye definiciones de tipos completas y funciona con tres transportes intercambiables: gRPC nativo (el más rápido, solo Node.js), ConnectRPC (funciona en Node.js y en navegadores) y HTTP/JSON sencillo. Los errores transitorios se reintentan automáticamente con retroceso exponencial.
Funciona en Node.js ≥ 18 y en navegadores modernos, y es compatible con Express, Fastify, Next.js, React, Vue y Vite.
Instalación
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
Requisitos
| Requisito | Notas |
|---|---|
| Node.js | ≥ 18.0.0 (necesario para el transporte grpc) |
| Formato de módulo | ES Module: el paquete incluye "type": "module" |
| Navegador | Cualquier navegador moderno con fetch; usa el transporte connect o http |
El paquete se publica solo como ESM. En un proyecto ESM ("type": "module" en tu package.json, o un archivo .mjs), impórtalo directamente:
import { CaptchaSonic } from "captchasonic";
Desde un archivo CommonJS, cárgalo con un import() dinámico:
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
Si usas TypeScript, define "module": "NodeNext" (o "ESNext") y "moduleResolution": "NodeNext" en tsconfig.json para que las definiciones de tipos incluidas se resuelvan correctamente.
Autenticación
Crea una clave API en el panel de CaptchaSonic y pásala como primer argumento del constructor:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Nunca incluyas claves en el código fuente del control de versiones. Léela desde el entorno:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
Inicio rápido
Cada tipo de CAPTCHA tiene un ayudante solve* dedicado que envía la tarea y se resuelve con el resultado. No hay un paso de sondeo aparte para las tareas de imagen: el SDK lo gestiona por ti.
solveRecaptchaV2TokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solveRecaptchaV2Token(…)returnssolution.tokenimport { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await solver.solveRecaptchaV2Token({
websiteURL: "https://example.com/login",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT... ← drop into the g-recaptcha-response fieldfrom captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com/login",
website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)
print(result["token"])
# 03AGdBq25SxXT... ← drop this into the g-recaptcha-response fieldDevuelve: los métodos de imagen resuelven un resultado cuya respuesta está en
typedSolution(p. ej.,typedSolution.grid.objects, los índices de las casillas seleccionadas); los métodos de token devuelven el token en el mapasolution.
TIP
Los métodos basados en token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, token de popular-captcha) envían una tarea de automatización de navegador y sondean internamente hasta que el token está listo; por defecto, hasta 120 segundos.
Tipos de CAPTCHA compatibles
Todos los métodos de imagen reciben un único objeto de opciones tipado. Las imágenes pueden ser Uint8Array, Buffer de Node o una ruta de archivo en forma de cadena (las rutas de archivo solo funcionan en Node.js).
reCAPTCHA v2 (imagen)
await solver.solveRecaptchaV2({
images: tiles, // typically 9 tiles for a 3×3 grid
question: "traffic lights", // plain text, or a Google class code like "/m/015qff"
});
// → result.typedSolution.grid.objects (number[] — selected tile indices)
PopularCaptcha (imagen estilo hCaptcha)
await solver.solvePopularCaptcha({
images: tiles, // 1–64 tiles
question: "Click each image with a cat",
questionType: "objectClassify", // "objectClassify" | "grid" | "objectClick" | "objectDrag"
examples, // optional reference images for objectClick
websiteURL: "https://example.com",
});
// objectClassify/grid → typedSolution.grid.objects
// objectClick → typedSolution.click
// objectDrag → typedSolution.drag
GeeTest
// nine-grid (question + images required)
await solver.solveGeetest({ type: "nine", question: "Select all bicycles", images: tiles });
// click / icon (question + images required)
await solver.solveGeetest({ type: "click", question: "the bear", images: tiles });
// slide puzzle (piece + background)
await solver.solveGeetest({ type: "slide", images: [piece], examples: [background] });
// swap puzzles
await solver.solveGeetest({ type: "match" });
await solver.solveGeetest({ type: "winlinze" });
Devuelve: los tipos grid/click van a typedSolution.grid.objects (o typedSolution.click); slide devuelve typedSolution.slide.x.
Alias aceptados en type:
| Canónico | Alias |
|---|---|
| cuadrícula de 9 | "nine", "geetest_nine", "9" |
| click / icono | "click", "geetest_click", "icon" |
| deslizar | "slide", "geetest_slide" |
| coincidencia | "match", "geetest_match" |
| winlinze | "winlinze", "geetest_winlinze" |
OCR / imagen a texto
await solver.solveOcr({ images: [img] }); // general OCR
await solver.solveOcr({ images: [img], module: "mtcaptcha", maxLength: 4 });
await solver.solveOcr({ images: imgs, module: "bls", numeric: true, maxLength: 3 });
// → result.typedSolution.text.texts[0]
| Opción | Tipo | Notas |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Predeterminado "common" |
numeric | boolean | Solo dígitos (se activa automáticamente para "bls") |
caseSensitive | boolean | Conserva las mayúsculas y minúsculas |
minLength / maxLength | number | Límites de longitud |
TikTok
await solver.solveTikTok({ type: "click", question: "Select the shape", images });
await solver.solveTikTok({ type: "whirl", question: "Rotate to match", images, examples }); // examples required
await solver.solveTikTok({ type: "slide", question: "Slide to fit", images, examples }); // examples required
Devuelve: click va a typedSolution.click; whirl/slide devuelven typedSolution.slide.x.
type acepta "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide".
Binance
await solver.solveBinance({ type: "grid", question: "Select the bicycle", images });
await solver.solveBinance({ type: "slide", images: [puzzle], examples: [background] });
Devuelve: grid va a typedSolution.grid.objects; slide devuelve typedSolution.slide.x.
type acepta "grid"/"binance_grid" y "slide"/"binance_slide".
AWS WAF
solveAwsWaf recibe argumentos posicionales. La question tiene el formato "type:category:target".
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
Devuelve: los índices de las casillas seleccionadas en typedSolution.grid.objects.
Imagen de slide (local, sin IA)
Detecta el desplazamiento del slide localmente mediante detección de contornos. Acepta una imagen combinada o [background, piece].
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
Devuelve: el desplazamiento del slide en píxeles en typedSolution.slide.x.
Métodos de token (automatización de navegador)
Estos envían una tarea y sondean internamente hasta que se devuelve un token (hasta el tiempo límite de sondeo, 120 s por defecto).
solveTurnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solveTurnstile(…)returnssolution.tokenawait solver.solveTurnstile({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solveRecaptchaV2Token({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solveRecaptchaV3Token({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solvePopularCaptchaToken({ websiteURL, websiteKey, proxy, metadata }); // proxy optional
await solver.solveCloudflare({ websiteURL, websiteKey, proxy }); // proxy REQUIREDsolver.solve_turnstile(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v2_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v3_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_popular_captcha_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_cloudflare(website_url=..., website_key=..., proxy=...) # proxy REQUIREDDevuelve: el token en el mapa solution de la respuesta (por ejemplo, result.solution.token o result.solution.gRecaptchaResponse, según el CAPTCHA).
Uso con TypeScript
El SDK exporta tipos para cada objeto de opciones y de respuesta. Impórtalos con import type.
import { CaptchaSonic } from "captchasonic";
import type { SolveGeetestOptions, GetTaskResultResponse } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY!);
const opts: SolveGeetestOptions = {
type: "nine",
question: "Select all bicycles",
images: tiles,
};
const result = await solver.solveGeetest(opts);
console.log(result.typedSolution?.grid?.objects);
Tipos exportados
import type {
CaptchaSonicOptions,
ImageInput,
SolvePopularCaptchaOptions,
SolveRecaptchaV2Options,
SolveGeetestOptions,
SolveOcrOptions,
SolveTikTokOptions,
SolveBinanceOptions,
SolveTurnstileOptions,
SolvePopularCaptchaTokenOptions,
SolveRecaptchaV2TokenOptions,
SolveRecaptchaV3TokenOptions,
SolveCloudflareOptions,
SolveSlideImageOptions,
GeetestSubtype,
TikTokSubtype,
BinanceSubtype,
Task,
CreateTaskResponse,
GetTaskResultResponse,
} from "captchasonic";
ImageInput es Uint8Array | Buffer | string.
Compatibilidad con proxy
Los métodos de token y de automatización de navegador aceptan una cadena proxy opcional con el formato http://user:pass@host:port:
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare siempre requiere un proxy: el campo proxy es obligatorio para ese método. Los demás métodos de token se ejecutan sin proxy cuando se omite proxy.
Para hCaptcha empresarial también puedes pasar metadata (rqdata, rqtoken, fingerprint) a solvePopularCaptchaToken.
Configuración
Pasa un objeto de opciones como segundo argumento del constructor. Solo se admiten las opciones siguientes.
const solver = new CaptchaSonic("YOUR_API_KEY", {
transport: "connect", // "grpc" (default) | "connect" | "http"
timeout: 180_000, // max poll wait in ms (alias: timeoutMs); per-call default 30000
pollingInterval: 5_000, // polling frequency in ms (default 2000)
baseUrl: "https://api.captchasonic.com", // override endpoint (alias: url)
});
| Opción | Tipo | Predeterminado | Descripción |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Protocolo de transmisión (ver la tabla siguiente) |
timeout / timeoutMs | number | 30000 por llamada | Tiempo límite de la petición; timeout también limita la espera del sondeo |
pollingInterval | number | 2000 | Frecuencia con la que se sondean las tareas de token |
url / baseUrl | string | según el transporte | Sustituye el endpoint de la API |
Transportes
| Transporte | Entornos | Protocolo |
|---|---|---|
grpc | Solo Node.js | gRPC binario sobre HTTP/2: menor latencia, envía las imágenes como binario sin procesar |
connect | Node.js y navegadores | ConnectRPC sobre fetch |
http | Node.js y navegadores | REST/JSON sencillo sobre fetch |
TIP
En el navegador usa connect (recomendado) o http. El gRPC nativo requiere Node.js. Con connect/http, las imágenes se codifican automáticamente en base64 antes de enviarse; con grpc se envían como binario sin procesar, sin sobrecarga.
Manejo de errores
Todos los fallos a nivel de API lanzan un SonicError, que extiende el Error integrado. Incluye un errorId numérico y asigna a name el nombre del error correspondiente.
import { CaptchaSonic, SonicError } from "captchasonic";
try {
const result = await solver.solveGeetest({ type: "nine", question: "bicycles", images });
} catch (err) {
if (err instanceof SonicError) {
console.error(err.errorId); // 1–6
console.error(err.name); // e.g. "InvalidApiKeyError"
console.error(err.message);
} else {
throw err; // network / unexpected
}
}
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription has expired. | Renew your subscription. |
Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).
TIP
Los errores transitorios de gRPC se reintentan automáticamente con retroceso exponencial (hasta 3 intentos), así que normalmente solo necesitas gestionar los casos de SonicError de arriba.
Ayudantes de cuenta
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
Los métodos de tarea de bajo nivel están disponibles si necesitas control directo sobre el envío y el sondeo:
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
Solución de problemas
require is not defined / Cannot use import statement outside a module: el paquete es solo ESM. Usa import en un proyecto ESM, o await import("captchasonic") desde CommonJS. Consulta Instalación.
El transporte grpc falla en el navegador: el gRPC nativo es solo para Node.js. Cambia a transport: "connect" o transport: "http".
InvalidApiKeyError en cada llamada: confirma que la clave se pasa como primer argumento del constructor y que no es undefined por accidente (por ejemplo, una variable de entorno que falta).
El método de token agota el tiempo de espera: las tareas de token sondean hasta timeout ms (por defecto 120000). Aumenta timeout y verifica que websiteURL / websiteKey coincidan con la página de destino. En Cloudflare es obligatorio un proxy válido.
Las imágenes con ruta de archivo no se cargan: las rutas de archivo en forma de cadena se leen de forma síncrona y solo son válidas en Node.js; en el navegador pasa un Uint8Array en su lugar.