Automatización de Octo Browser mediante API: una guía completa

¿Te gustaría probar Octo Browser con descuento?
Usa el código promocional OCTOBLOG para obtener un 30% de descuento en cualquier suscripción. Esta oferta solo es válida para nuevos usuarios.

Qué es una API

Una API (Application Programming Interface o interfaz de programación de aplicaciones) es una interfaz de programación que permite que los sistemas de software se comuniquen. Piense en ello como en un restaurante: usted hace un pedido, el camarero lo lleva a la cocina y le trae el plato. Lo mismo sucede cuando su aplicación envía una solicitud a través de la API y recibe una respuesta del servidor de Octo Browser.

Solicitudes HTTP

La comunicación de la API se realiza a través de solicitudes HTTP, que son mensajes que un cliente envía a un servidor para solicitar o transferir datos.

Principales métodos HTTP

Estructura de la solicitud

Cada solicitud consta de varios componentes:

• URL: dónde se envía la solicitud.

• Método: qué queremos hacer (GET, POST, etc.).

• Cabeceras: información adicional de la solicitud (por ejemplo, un token de API).

• Cuerpo: los datos que enviamos (por ejemplo, información para un nuevo perfil).

Veamos cómo crear un perfil usando una solicitud POST, Node.js y la biblioteca Axios. Aquí tiene un script de ejemplo:

const axios = require('axios');
const data = JSON.stringify({
  "title": "Test profile from api",
  "fingerprint": {
    "os": "win"
  }
});
const config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://app.octobrowser.net/api/v2/automation/profiles',
  headers: { 
    'Content-Type': 'application/json', 
    'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'
  },
  data : data
};
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

const axios = require('axios');
const data = JSON.stringify({
  "title": "Test profile from api",
  "fingerprint": {
    "os": "win"
  }
});
const config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://app.octobrowser.net/api/v2/automation/profiles',
  headers: { 
    'Content-Type': 'application/json', 
    'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'
  },
  data : data
};
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

URL: 'https://app.octobrowser.net/api/v2/automation/profiles' (el punto de conexión de la API utilizado para trabajar con perfiles).

Método: 'post' (crear un nuevo perfil).

Cuerpo de la solicitud (datos): un objeto Json que contiene los campos obligatorios (nombre del perfil y SO).

Cabeceras:

• Content-Type': 'application/json' le indica al servidor que los datos están en formato Json.

• 'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>' es un token de API único disponible en la configuración de la cuenta principal para las suscripciones Base y superiores.

Después de enviar la solicitud, el servidor siempre devuelve una respuesta HTTP que incluye un código de estado, un número de tres dígitos que indica el resultado del procesamiento de la solicitud.

Respuestas del servidor

• Exitosas (2xx):

{"success":true,"msg":"","data":{"uuid":"<profile_uuid>"},"code":null}

{"success":true,"msg":"","data":{"uuid":"<profile_uuid>"},"code":null}

• Errores (4xx y 5xx):

  • 400 Bad Request — sintaxis incorrecta o falta un parámetro requerido.

  • 401 Unauthorized — token de API no válido o ausente.

  • 404 Not Found — la URL no existe.

  • 429 Too Many Requests — se ha superado el límite de solicitudes.

  • 500 Internal Server Error — un error del lado del servidor.

El bloque .catch en el script ayuda a manejar estos errores.

Documentación de la API de Octo Browser

La documentación oficial de la API de Octo Browser incluye estructuras de solicitud y ejemplos de uso:

• El menú de la izquierda enumera secciones como Perfiles, Proxies, API del cliente local, Equipos y más.

• El centro contiene descripciones de las solicitudes: el punto de conexión, el método (GET, POST, etc.), los parámetros, las cabeceras y los ejemplos de uso.

• El lado derecho incluye ejemplos listos de solicitudes y respuestas del servidor.

• El menú desplegable LANGUAGE le permite seleccionar ejemplos en Node.js, Python, Java, C#, PHP y otros lenguajes.

Trabajar con la API pública y local

API pública

• Una interfaz remota disponible en línea. No requiere que el navegador esté ejecutándose.

• Las solicitudes se envían a: https://app.octobrowser.net.

• Los límites dependen de la suscripción:

Usando la API pública, puede:

• recuperar información del perfil;

• crear, editar y eliminar perfiles;

• trabajar con etiquetas, equipos y proxies.

Ejemplo de solicitud: crear un perfil

POST https://app.octobrowser.net/api/v2/automation/profiles

Cabecera: X-Octo-Api-Token: <SU_TOKEN_DE_API>

API local

• Funciona localmente cuando Octo Browser se está ejecutando en el dispositivo.

• Los límites dependen del tipo de solicitud: Iniciar perfil — 1 solicitud, Perfil de un solo uso — 4 solicitudes. Todas las demás solicitudes de la API local no afectan los límites.

• Puede iniciar sesión, iniciar y detener perfiles y conectar bibliotecas de automatización.

• Las solicitudes se envían a: http://localhost:58888 (58888 es el puerto del servidor HTTP local).

Ejemplo de solicitud: iniciar un perfil

POST http://localhost:58888/api/profiles/start

Cabecera: Content-Type: application/json y un cuerpo Json con el UUID y otros parámetros.

Soluciones para enviar solicitudes

Postman

1. Descargue Postman o use la versión web.

2. Importe la API de Octo Browser en su espacio de trabajo usando el botón Run in Postman.

3. Elija una solicitud (por ejemplo, POST Create Profile → Simple Profile).

4. Especifique https://app.octobrowser.net en lugar de {{baseUrl}}.
   
   

   

5. Establezca el token de la API en la pestaña Headers.

   

6. Introduzca los parámetros de perfil requeridos en la pestaña Body.

   

7. Haga clic en Send para crear un perfil.

Lo mismo se aplica a iniciar un perfil:

1. Seleccione la solicitud POST Start Profile.

2. Especifique la URL de la API local: http://localhost:58888.

3. Busque el UUID del perfil en "History and Restore", en la tabla de perfiles, o usando la solicitud GET Get Profiles.

4. En la pestaña Body, establezca los parámetros:

• uuid: el ID del perfil;

• headless: iniciar sin GUI (true/false);

• debug_port: habilitar el puerto de automatización (true/false o un puerto específico);

• timeout: tiempo de espera en segundos;

• only_local: restringir el acceso a localhost (true/false);

• flags: argumentos adicionales (por ejemplo, ["--start-maximized"]);

• password: la contraseña del perfil, si está establecida.

5. Haga clic en Send y verifique la respuesta.

VS Code

1. Descargue e instale VS Code.

2. Descargue e instale node.js para JavaScript.

3. Descargue e instale Python para scripts de Python .

4. Abra VS Code y cree una carpeta para el proyecto.

5. Instale las dependencias:

   • Para Node.js: npm install axios.

   • Para Python: pip install requests.

6. Copie el ejemplo de la documentación de Octo para POST Create Profile usando node.js + axios.

7. Cree un archivo .js y pegue el script en él.

8. Inserte su token de API y guarde el archivo.

9. Ejecute el script con el comando node <nombre_archivo> (por ejemplo, node post_create_profile)."

Del mismo modo, para iniciar un perfil usando Python, seleccione POST Start Profile en Example Request, pegue el script en un archivo .py, guárdelo y ejecútelo.

Terminal/CMD

También puede trabajar con la API en la Terminal/CMD. Para hacer esto, seleccione cURL en el menú LANGUAGE.

Inserte su token de API en la solicitud POST Create Profile y ejecute:

Importante: para CMD en Windows debe adaptar la sintaxis, ya que CMD interpreta los comandos de manera diferente a los shells tipo Unix. En particular, las comillas se deben usar correctamente y los saltos de línea se deben manejar de forma adecuada. Aquí tiene un ejemplo adaptado de un script de inicio de perfil:

curl --location "http://localhost:58888/api/profiles/start" ^
--header "Content-Type: application/json" ^
--data "{\"uuid\": \"42c4231d71f6495fb33e70d97915c696\", \"headless\": false, \"debug_port\": true, \"timeout\": 120, \"only_local\": true, \"flags\": [], \"password\": \"\"}"

curl --location "http://localhost:58888/api/profiles/start" ^
--header "Content-Type: application/json" ^
--data "{\"uuid\": \"42c4231d71f6495fb33e70d97915c696\", \"headless\": false, \"debug_port\": true, \"timeout\": 120, \"only_local\": true, \"flags\": [], \"password\": \"\"}"

*Inserte el UUID del perfil requerido.

Estas no son todas las formas posibles de trabajar con la API de Octo Browser; estos son solo algunos ejemplos.

Marcos de automatización y CDP

CDP (Chrome DevTools Protocol) le permite controlar las acciones del perfil a través de código: abrir sitios web, hacer clics, escribir y tomar capturas de pantalla. 

Octo Browser admite conexiones CDP a través de la API local. Cuando inicia un perfil a través de POST Start Profile, debe pasar el parámetro debug_port: true (o especificar un puerto), y Octo abrirá un puerto para acceso remoto (por ejemplo, ws://127.0.0.1:53215/devtools/browser/...).

Ejemplo de inicio de un perfil con un puerto CDP:

curl --location 'http://localhost:58888/api/profiles/start' \
--header 'Content-Type: application/json' \
--data '{
    "uuid": "eb5d6441b2b349368b31fd901b82a8ac",
    "headless": false,
    "debug_port": true,
    "timeout": 120,
    "only_local": true
}'

curl --location 'http://localhost:58888/api/profiles/start' \
--header 'Content-Type: application/json' \
--data '{
    "uuid": "eb5d6441b2b349368b31fd901b82a8ac",
    "headless": false,
    "debug_port": true,
    "timeout": 120,
    "only_local": true
}'

La respuesta contendrá la dirección de conexión:

{"uuid":"eb5d6441b2b349368b31fd901b82a8ac","state":"STARTED","headless":false,"start_time":1761735064,"ws_endpoint":"ws://127.0.0.1:53215/devtools/browser/d633f197-1623-4f61-a9b0-28a65e0df2fd","debug_port":"53215","one_time":false,"browser_pid":57411,"connection_data":{"ip":"","country":""}}

{"uuid":"eb5d6441b2b349368b31fd901b82a8ac","state":"STARTED","headless":false,"start_time":1761735064,"ws_endpoint":"ws://127.0.0.1:53215/devtools/browser/d633f197-1623-4f61-a9b0-28a65e0df2fd","debug_port":"53215","one_time":false,"browser_pid":57411,"connection_data":{"ip":"","country":""}}

Puede utilizar esta dirección en cualquier biblioteca que admita CDP, por ejemplo, Puppeteer/Pyppeteer o Playwright. Encontrará ejemplos detallados de uso en la documentación.

Además del uso directo de CDP, puede conectar Selenium a los perfiles de Octo Browser a través de WebDriver. En este caso, Selenium controla un navegador que ya se está ejecutando a través de debug_port, pero utiliza WebDriver en lugar de comandos directos de CDP. Hay un ejemplo de conexión disponible en la documentación.

El uso de bibliotecas de automatización abre un amplio abanico de posibilidades, desde calentar perfiles y recopilar cookies hasta crear complejas lógicas de registro de cuentas y gestionar las acciones de las mismas.

Cómo ejecutar Octo Browser en Docker

Docker es un software para automatizar la implementación y gestión de aplicaciones en contenedores. Cada contenedor tiene su propio SO (normalmente Linux), bibliotecas, dependencias y configuraciones. A diferencia de una máquina virtual, un contenedor es ligero y se inicia muy rápidamente.

Ventajas de usar Docker para Octo Browser:

• Aislamiento: Octo Browser y sus dependencias se ejecutan de forma independiente, sin conflictos con otras aplicaciones.

• Portabilidad: el mismo contenedor se puede ejecutar en un servidor, portátil o VPS, y todo funcionará de la misma manera.

• Escalabilidad: puede ejecutar muchos perfiles al mismo tiempo y crear nuevos contenedores cuando necesite procesar más perfiles en paralelo.

• Automatización: conveniente para scripts donde el navegador se ejecuta en modo headless sin interfaz gráfica.

Ejecución de Docker:

1. Prepare un Dockerfile. En la documentación hay disponible un ejemplo de Dockerfile para Ubuntu 22.04 con todas las dependencias, incluidos Octo Browser y Google Chrome.

2. Construya un contenedor Docker:

docker build -t octobrowser:latest

docker build -t octobrowser:latest

3. Ejecute el contenedor:

docker run --name octo -it --rm \
       --security-opt seccomp:unconfined \
       -v '/srv/docker_octo/cache:/home/octo/.Octo Browser/' \
       -p 58895:58888 \
       octobrowser:latest

docker run --name octo -it --rm \
       --security-opt seccomp:unconfined \
       -v '/srv/docker_octo/cache:/home/octo/.Octo Browser/' \
       -p 58895:58888 \
       octobrowser:latest

Cómo gestionar contenedores de Octo Browser usando Kubernetes

Kubernetes (K8s) ayuda a gestionar múltiples contenedores a la vez.

• Docker está diseñado para ejecutar un solo contenedor.

• Kubernetes ayuda a ejecutar un clúster completo de contenedores con distribución automática de carga.

Puede utilizar Minikube, kind, Docker Desktop u otras herramientas para ejecutar Kubernetes.

Flujo de trabajo para Octo Browser y Kubernetes:

1. Construya el contenedor Docker.

2. Ejecute el contenedor.

3. Use Kubernetes para gestionar los contenedores.

Un ejemplo de YAML de despliegue está disponible en la documentación.

Scripts y fragmentos útiles

En la documentación de la API de Octo Browser, encontrará no solo métodos básicos sino también scripts listos para usar en Node.js y Python. En la documentación se describen los siguientes escenarios:

1. Creación masiva de perfiles: especifique el número de perfiles y su token de API.

2. Adición masiva de extensiones, páginas de inicio y marcadores a perfiles seleccionados: especifique la lista de perfiles, extensiones, páginas de inicio, marcadores y token de API.

3. Adición masiva de extensiones, páginas de inicio y marcadores a todos los perfiles: especifique extensiones, páginas de inicio, marcadores y token de API.

4. Adición masiva de extensiones, páginas de inicio y marcadores a perfiles con una o varias etiquetas específicas: especifique las etiquetas, extensiones, páginas de inicio, marcadores y token de API.

5. Creación masiva de proxies a partir de un archivo .txt y posterior creación de perfiles utilizando estos proxies: el archivo debe tener el formato protocol;host;port;login;password;title;change_ip_url (change_ip_url es opcional). Especifique el token de API y el nombre del archivo en el script.

6. Agregar un proxy guardado a un perfil: especifique el proxy, el perfil y el token de API.

7. Copiar todos los perfiles exportados de la lista de exportación del navegador a una carpeta específica: especifique la carpeta y el token de API.

8. Generar un archivo .txt que contenga los nombres de todos los perfiles en su cuenta de Octo Browser: inserte su token de API.

Preguntas frecuentes sobre la API

¿Cómo paso parámetros al crear un perfil utilizando la API?

Ejemplo de cuerpo de solicitud:

const body = {
  title: "profile_title", // required field
  fingerprint: {
    os: "mac", // required field: "mac", "win", or "android"
    os_arch: "arm", // optional field: you can set "x86" if you want to create a mac profile with an Intel processor
    os_version: "13" // optional field
    /*
      Possible values:
      — for Windows: 10, 11
      — for macOS (arm): 12, 13, 14, 15
      — for macOS (x86): 12, 13, 14, 15
      — for Android: 12, 13, 14, 15
    */
  }
};

const body = {
  title: "profile_title", // required field
  fingerprint: {
    os: "mac", // required field: "mac", "win", or "android"
    os_arch: "arm", // optional field: you can set "x86" if you want to create a mac profile with an Intel processor
    os_version: "13" // optional field
    /*
      Possible values:
      — for Windows: 10, 11
      — for macOS (arm): 12, 13, 14, 15
      — for macOS (x86): 12, 13, 14, 15
      — for Android: 12, 13, 14, 15
    */
  }
};

El campo os dentro del objeto fingerprint es obligatorio. Si no especifica los demás parámetros, Octo Browser generará automáticamente los valores óptimos para ellos.

Para ver qué otros parámetros se pueden pasar al crear un perfil:

1. Vaya a la documentación de la API de Octo Browser (solicitud POST Create Profile).

2. Desplácese hacia abajo hasta la sección Body; allí se muestra la estructura de todos los parámetros disponibles.

3. Después de crear un perfil, puede recuperar sus parámetros mediante la solicitud GET Get Profile; la respuesta del servidor contendrá la estructura completa del perfil.

¿Cómo funcionan los perfiles de un solo uso?

Un perfil de un solo uso es un perfil desechable que se crea y se inicia inmediatamente con una sola solicitud de API, y se elimina automáticamente después de cerrarse.

• No es necesario enviar solicitudes individuales para crear, iniciar, detener y eliminar el perfil. Esto puede ser útil, por ejemplo, para el web scraping, donde solo necesita visitar un recurso web con una nueva huella digital de navegador, recopilar datos y luego eliminar el perfil.

• Los perfiles de un solo uso están disponibles en todas las suscripciones con acceso a la API.

• Una única solicitud de POST One-time profile cuenta como 4 solicitudes para sus límites de RPM/RPH.

Para terminar de trabajar con un perfil de un solo uso, solo necesita enviar POST Stop Profile, cerrar la ventana del navegador manualmente o llamar programáticamente a una acción de cierre a través de Puppeteer, Playwright o bibliotecas similares, por ejemplo, usando await browser.close(). Después del cierre, el perfil se elimina automáticamente y no aparece en su lista de perfiles ni en la Papelera.

¿Qué debo hacer si excedo los límites de la API (error 429)?

Detenga su script y pause el envío de solicitudes durante algún tiempo. Puede verificar los límites de su API en las cabeceras de respuesta:

• Retry-After: 0 # puede enviar la siguiente solicitud si el valor es cero

• X-Ratelimit-Limit: 200 # RPM que indica el total de solicitudes por minuto

• X-Ratelimit-Limit-Hour: 3000 # RPH que indica el total de solicitudes por hora

• X-Ratelimit-Remaining: 4 # RPM restante que indica las solicitudes que quedan en este minuto

• X-Ratelimit-Remaining-Hour: 2999 # RPH restante que indica las solicitudes que quedan en esta hora

• X-Ratelimit-Reset: 1671789217 # marca de tiempo UNIX que indica cuándo se restablecen los límites

No envíe solicitudes cuando sus límites estén agotados. De lo contrario, el periodo de restricción aumentará y se podrían aplicar límites de velocidad más estrictos. Asegúrese de que sus scripts verifiquen estas cabeceras de límite antes de enviar solicitudes.

¿Cómo obtengo un ws_endpoint para conexiones CDP?

Al iniciar un perfil a través de la API con el parámetro "debug_port": true (o al especificar un puerto concreto, por ejemplo, "debug_port": 20000), Octo Browser devuelve un valor ws_endpoint en la respuesta.

Las bibliotecas de automatización (como Puppeteer o Playwright) utilizan este ws_endpoint para conectarse a un perfil en ejecución.

¿Dónde puedo encontrar mi token de API?

La API está disponible para usuarios con la Suscripción Base y superiores.

El token de la API se muestra en la configuración de la cuenta principal, en la pestaña "Adicional". Los demás miembros del equipo no pueden ver el token de la API.