Dirección y permisos
La base es http://127.0.0.1:3848/v1. El servidor escucha únicamente en 127.0.0.1: atiende programas del mismo PC. La app debe estar abierta. /health comprueba disponibilidad; las demás operaciones necesitan un plan con API (Pro o Max).
Envía JSON con Content-Type: application/json en las solicitudes con cuerpo. Los nombres de campos y rutas se mantienen en español en ambos idiomas. Las solicitudes desde páginas web con Origin se rechazan por defecto; ejecuta tus integraciones como programas locales.
Invoke-RestMethod 'http://127.0.0.1:3848/v1/health'
Invoke-RestMethod 'http://127.0.0.1:3848/v1/perfiles' | Select-Object id,nombre
Rutas de perfiles
| Método | Ruta | Resultado |
|---|---|---|
| GET | /v1/health | ok y version; no exige plan con API. |
| GET | /v1/perfiles | Lista de perfiles. |
| GET | /v1/perfiles/activos | Lista de ids activos. |
| GET | /v1/perfiles/:id | Datos de un perfil. |
| POST | /v1/perfiles | Crea un perfil; responde 201. |
| POST | /v1/perfiles/bulk | Crea un lote; responde 201 con {creados}. |
| PATCH | /v1/perfiles/:id | Actualiza campos del perfil. |
| DELETE | /v1/perfiles/:id | Envía a la papelera; responde 204. |
| POST | /v1/perfiles/:id/start | Inicia o devuelve la conexión de un perfil ya activo. |
| POST | /v1/perfiles/:id/stop | Detiene el perfil; responde con {ok: true}. |
Cuerpos de solicitud
| Operación | Campos |
|---|---|
| Crear perfil | nombre, plataforma (windows/macos/linux), userAgent y fingerprint. La huella básica requiere webRTC, canvas, webGL, timezone e idioma. |
| Conexión proxy | proxy: {type, host, port, username?, password?}. No combinar con nordVpnExtension. |
| Crear lote | cantidad, presetId, prefijo opcional y proxies como lista de objetos o texto. |
| Iniciar perfil | Cuerpo opcional: iniciarMinimizado, minimizado y extraArgs (lista de cadenas). Úsalos solo si tu integración los necesita. |
{
"automation": {
"port": 12345,
"wsEndpoint": "ws://127.0.0.1:12345/devtools/browser/RETURNED_VALUE"
}
}Los valores de esta respuesta son ilustrativos: usa siempre los que devuelve tu app. Obtén la configuración real de un perfil preparado en la interfaz para conocer sus campos avanzados; evita copiar id, fechas o rutas locales al crear otro.
Presets de huella
| Método | Ruta | Acción |
|---|---|---|
| GET | /v1/presets | Lista los presets. |
| GET | /v1/presets/:id | Obtiene uno. |
| POST | /v1/presets | Crea un preset con nombre y configuración de plataforma y huella. |
| PATCH | /v1/presets/:id | Actualiza el preset. |
| DELETE | /v1/presets/:id | Elimina el preset; responde 204. |
Un preset proporciona una configuración base para crear perfiles; editarlo no cambia automáticamente los perfiles existentes.
Respuestas de error
{ "error": { "code": "NO_ENCONTRADO", "mensaje": "Perfil no encontrado" } }| HTTP | Interpretación |
|---|---|
| 400 | Datos inválidos o lote que no puede crearse. Revisa error.code y error.mensaje. |
| 403 | Plan, cupo, sesión o acceso no permitido. /health disponible no demuestra permiso de automatización. |
| 404 | Perfil o preset no encontrado; comprueba el id. |
| 409 | Conflicto de estado; por ejemplo NO_ACTIVO al detener un perfil ya cerrado. |
Para no perder el diagnóstico, conserva el estado HTTP y el cuerpo al registrar un error. Una respuesta 204 no contiene JSON: no intentes parsearla como si fuera un objeto.