O que é uma API

Uma API (Interface de Programação de Aplicações) é uma interface de programação que permite a comunicação entre sistemas de software. Pense nela como um restaurante: você faz um pedido, o garçom leva para a cozinha e traz o prato de volta. O mesmo acontece quando sua aplicação envia uma solicitação através da API e recebe uma resposta do servidor Octo Browser.

Solicitações HTTP

A comunicação de API ocorre através de solicitações HTTP — mensagens que um cliente envia para um servidor para solicitar ou transferir dados.

Métodos principais de HTTP

Estrutura da solicitação

Cada solicitação consiste em vários componentes:

• URL: para onde a solicitação é enviada.

• Método: o que queremos fazer (GET, POST, etc.).

• Cabeçalhos: informações adicionais da solicitação (por exemplo, um token de API).

• Corpo: os dados que enviamos (por exemplo, informações para um novo perfil).

Vamos passar por criar um perfil usando uma solicitação POST, Node.js e a biblioteca Axios. Aqui está um exemplo de script:

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' (o ponto final da API usado para trabalhar com perfis).

Método: 'post' (criar um novo perfil).

Corpo da solicitação (dados): um objeto JSON contendo os campos necessários (nome do perfil e SO).

Cabeçalhos:

• Content-Type': 'application/json' informa ao servidor que os dados estão em formato JSON.

• 'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>' é um token de API único disponível nas configurações da conta principal para assinaturas Base e superiores.

Após enviar a solicitação, o servidor sempre retorna uma resposta HTTP que inclui um código de status — um número de três dígitos indicando o resultado do processamento da solicitação.

Respostas do servidor

• Bem-sucedido (2xx):

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

• Erros (4xx e 5xx):
  
  

  • 400 Solicitação Inválida — sintaxe incorreta ou um parâmetro necessário está faltando.

  • 401 Não Autorizado — API token inválido ou ausente.

  • 404 Não Encontrado — o URL não existe.

  • 429 Muitas Solicitações — o limite de solicitações foi excedido.

  • 500 Erro Interno do Servidor — um erro do lado do servidor.

O bloco .catch no script ajuda a lidar com esses erros.

Documentação de API do Octo Browser

A documentação oficial da API do Octo Browser inclui estruturas de solicitações e exemplos de uso:

• O menu à esquerda lista seções como Perfis, Proxies, API do Cliente Local, Equipes e mais.

• O centro contém descrições de solicitações: o ponto final, método (GET, POST, etc.), parâmetros, cabeçalhos e exemplos de uso.

• A direita inclui exemplos de solicitações prontos e respostas do servidor.

• A lista suspensa LANGUAGE permite selecionar exemplos em Node.js, Python, Java, C#, PHP e outras linguagens.

Trabalhando com a API Pública e Local

API Pública

• Uma interface remota disponível online. Não requer que o navegador esteja em execução.

• As solicitações são enviadas para: https://app.octobrowser.net.

• Os limites dependem da assinatura:

Usando a API Pública, você pode:

• recuperar informações do perfil;

• criar, editar e excluir perfis;

• trabalhar com tags, equipes e proxies.

Exemplo de solicitação: criando um perfil

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

Cabeçalho: X-Octo-Api-Token: <-SEU_API_TOKEN>

API Local

• Funciona localmente quando o Octo Browser está em execução no dispositivo.

• Os limites dependem do tipo de solicitação: Iniciar Perfil — 1 solicitação, Perfil Único — 4 solicitações. Todas as outras solicitações de API Local não afetam os limites.

• Você pode fazer login, iniciar e parar perfis e conectar bibliotecas de automação.

• As solicitações são enviadas para: http://localhost:58888 (58888 é a porta do servidor HTTP local).

Exemplo de solicitação: iniciando um perfil

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

Cabeçalho: Content-Type: application/json e um corpo JSON com o UUID e outros parâmetros.

Soluções para enviar solicitações

Postman

1. Baixe o Postman ou use a versão web.

2. Importe a API do Octo Browser para o seu espaço de trabalho usando o botão Executar no Postman.

3. Escolha uma solicitação (por exemplo, POST Criar Perfil → Perfil Simples).

4. Especifique https://app.octobrowser.net em vez de {{baseUrl}}.

   

5. Defina o token de API na aba Headers.

   

6. Insira os parâmetros do perfil necessários na aba Body.

   

7. Clique em Enviar para criar um perfil.

O mesmo se aplica ao iniciar um perfil:

1. Selecione a solicitação POST Iniciar Perfil.

2. Especifique a URL da API Local: http://localhost:58888.

3. Encontre o UUID do perfil em “Histórico e Restauração”, na tabela de perfis ou usando a solicitação GET Obter Perfis.

4. Na aba Body, defina os parâmetros:

• uuid: o ID do perfil;

• headless: iniciar sem uma interface gráfica (true/false);

• debug_port: habilitar a porta de automação (true/false ou uma porta específica);

• timeout: tempo limite em segundos;

• only_local: restringir acesso ao localhost (true/false);

• flags: argumentos adicionais (por exemplo, ["--start-maximized"]);

• senha: a senha do perfil, se definida.

5. Clique em Enviar e verifique a resposta.

VS Code

1. Baixe e instale o VS Code.

2. Baixe e instale node.js para JavaScript.

3. Baixe e instale Python para scripts em Python .

4. Abra o VS Code e crie uma pasta de projeto.

5. Instale as dependências:

   • Para Node.js: npm install axios.

   • Para Python: pip install requests.

6. Copie o exemplo da documentação do Octo para POST Criar Perfil usando node.js + axios.

7. Crie um arquivo .js e cole o script nele.

8. Insira seu token de API e salve o arquivo.

9. Execute o script com o comando node <nome_do_arquivo> (por exemplo, node post_create_profile).

Da mesma forma, para iniciar um perfil usando Python, selecione POST Iniciar Perfil em Exemplo de Solicitação, cole o script em um arquivo .py, salve-o e execute-o.

Terminal/CMD

Você também pode trabalhar com a API no Terminal/CMD. Para fazer isso, selecione cURL no menu LANGUAGE.

Insira seu token de API na solicitação POST Criar Perfil e execute:

Importante: para CMD no Windows, é necessário adaptar a sintaxe, já que o CMD interpreta comandos de forma diferente dos shells Unix-like. Em particular, é preciso trabalhar corretamente com aspas e lidar adequadamente com quebras de linha. Aqui está um exemplo adaptado de um script de inicialização 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\": \"\"}"

*Insira o UUID do perfil necessário.

Essas não são todas as maneiras possíveis de trabalhar com a API do Octo Browser — são apenas alguns exemplos.

Frameworks de automação e CDP

CDP (Protocolo de Ferramentas de Desenvolvedor do Chrome) permite controlar ações do perfil através do código: abrir sites, clicar, digitar e tirar screenshots. 

O Octo Browser suporta conexões CDP através da API Local. Quando você inicia um perfil via POST Iniciar Perfil, precisa passar o parâmetro debug_port: true (ou especificar uma porta), e Octo abrirá uma porta para acesso remoto (por exemplo, ws://127.0.0.1:53215/devtools/browser/...).

Exemplo de inicialização de um perfil com uma porta 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
}'

A resposta conterá o endereço de conexão:

{"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":""}}

Você pode usar esse endereço em qualquer biblioteca que suporte CDP, por exemplo, Puppeteer/Pyppeteer ou Playwright. Exemplos detalhados de uso estão disponíveis na documentação.

Além do uso direto do CDP, você pode conectar o Selenium aos perfis do Octo Browser através do WebDriver. Nesse caso, o Selenium controla um navegador já em execução via debug_port, mas usa WebDriver em vez de comandos CDP diretos. Um exemplo de conexão está disponível na documentação.

O uso de bibliotecas de automação abre amplas possibilidades, desde o aquecimento de perfis e coleta de cookies até a construção de lógica complexa de registro de contas e gerenciamento de ações de contas.

Como executar o Octo Browser no Docker

Docker é um software para automatizar a implantação e gerenciamento de aplicações em contêineres. Cada contêiner tem seu próprio SO (geralmente Linux), bibliotecas, dependências e configurações. Diferente de uma máquina virtual, um contêiner é leve e inicia muito rapidamente.

Vantagens de usar o Docker para Octo Browser:

• Isolamento: Octo Browser e suas dependências rodam de forma independente, sem conflitar com outras aplicações.

• Portabilidade: o mesmo contêiner pode rodar em um servidor, laptop ou VPS, e tudo funcionará da mesma forma.

• Escalabilidade: você pode rodar muitos perfis ao mesmo tempo e criar novos contêineres quando precisar lidar com mais perfis em paralelo.

• Automação: conveniente para scripts onde o navegador é executado em modo headless sem uma interface gráfica.

Executando o Docker:

1. Prepare um Dockerfile. Um exemplo de Dockerfile para Ubuntu 22.04 com todas as dependências, incluindo Octo Browser e Google Chrome, está disponível na documentação.

2. Construa um contêiner Docker:

docker build -t octobrowser:latest

3. Execute o contêiner:

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

Como gerenciar contêineres Octo Browser usando Kubernetes

Kubernetes (K8s) ajuda a gerenciar múltiplos contêineres de uma vez.

• Docker é destinado a executar um único contêiner.

• Kubernetes ajuda a executar todo um cluster de contêineres com distribuição automática de carga.

Você pode usar Minikube, kind, Docker Desktop ou outras ferramentas para executar o Kubernetes.

Fluxo de trabalho para Octo Browser e Kubernetes:

1. Construa o contêiner Docker.

2. Execute o contêiner.

3. Use o Kubernetes para gerenciar os contêineres.

Um exemplo de Deployment YAML está disponível na documentação.

Scripts e trechos úteis

Na documentação da API do Octo Browser, você encontrará não apenas métodos básicos, mas também scripts prontos em Node.js e Python. Os seguintes cenários são descritos na documentação:

1. Criação em massa de perfis — especifique o número de perfis e seu token de API.

2. Adição em massa de extensões, páginas iniciais e favoritos a perfis selecionados — especifique a lista de perfis, extensões, páginas iniciais, favoritos e token de API.

3. Adição em massa de extensões, páginas iniciais e favoritos a todos os perfis — especifique extensões, páginas iniciais, favoritos e token de API.

4. Adição em massa de extensões, páginas iniciais e favoritos a perfis com uma tag/tags específicas — especifique a tag/tags, extensões, páginas iniciais, favoritos e token de API.

5. Criação em massa de proxies a partir de um arquivo .txt e consequente criação de perfis usando esses proxies — o arquivo deve estar no formato protocol;host;port;login;password;title;change_ip_url (change_ip_url é opcional). Especifique o token de API e o nome do arquivo no script.

6. Adicionar um proxy salvo a um perfil — especifique o proxy, o perfil e o token de API.

7. Copiar todos os perfis exportados da lista de exportação do navegador para uma pasta especificada — especifique a pasta e o token de API.

8. Gerar um arquivo .txt contendo os nomes de todos os perfis na sua conta Octo Browser — insira seu token de API.

FAQ sobre API

Como passo parâmetros ao criar um perfil usando a API?

Exemplo de corpo de solicitação:

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
    */
  }
};

O campo os dentro do objeto impressão digital é obrigatório. Se você não especificar os outros parâmetros, o Octo Browser gerará automaticamente valores ótimos para eles.

Para ver quais outros parâmetros podem ser passados ao criar um perfil:

1. Vá para a solicitação POST Criar Perfil na documentação da API do Octo Browser.

2. Role para baixo até a seção Corpo — ela mostra a estrutura de todos os parâmetros disponíveis.

3. Após criar um perfil, você pode recuperar seus parâmetros através da solicitação GET Obter Perfil — a resposta do servidor conterá a estrutura completa do perfil.

Como funcionam os perfis de uso único?

Um perfil de uso único é um perfil descartável que é criado e lançado imediatamente com uma única solicitação de API, e automaticamente deletado após o fechamento.

• Não há necessidade de enviar solicitações separadas para criar, lançar, parar e deletar o perfil. Isso pode ser útil, por exemplo, para scraping de web, onde você só precisa visitar um recurso web com uma nova impressão digital do navegador, coletar dados e deletar o perfil em seguida.

• Perfis de uso único estão disponíveis em todas as assinaturas com acesso à API.

• Uma única solicitação POST Perfil de uso único conta como 4 solicitações em relação aos seus limites RPM/RPH.

Para finalizar o trabalho com um perfil de uso único, você só precisa enviar POST Parar Perfil, fechar a janela do navegador manualmente, ou chamar programaticamente uma ação de fechamento via Puppeteer, Playwright, ou bibliotecas similares — por exemplo, usando await browser.close(). Após o fechamento, o perfil é deletado automaticamente e não aparece na sua lista de perfis ou na Lixeira.

O que devo fazer se exceder os limites de API (erro 429)?

Pare seu script e pause o envio de solicitações por algum tempo. Você pode verificar seus limites de API nos cabeçalhos de resposta:

• Retry-After: 0 # você pode enviar a próxima solicitação se o valor for zero

• X-Ratelimit-Limit: 200 # RPM indicando total de solicitações por minuto

• X-Ratelimit-Limit-Hour: 3000 # RPH indicando total de solicitações por hora

• X-Ratelimit-Remaining: 4 # RPM restante indicando solicitações restantes neste minuto

• X-Ratelimit-Remaining-Hour: 2999 # RPH restante indicando solicitações restantes nesta hora

• X-Ratelimit-Reset: 1671789217 # timestamp UNIX indicando quando os limites serão redefinidos

Não envie solicitações quando seus limites estiverem esgotados. Caso contrário, o período de restrição aumentará, e limites de taxa mais restritivos podem ser aplicados. Certifique-se de que seus scripts verifiquem esses cabeçalhos de limite antes de enviar solicitações.

Como obtenho um ws_endpoint para conexões CDP?

Quando você lança um perfil via API com o parâmetro "debug_port": true (ou especifica uma porta específica, por exemplo, "debug_port": 20000), o Octo Browser retorna um valor ws_endpoint na resposta.

Esse ws_endpoint é usado por bibliotecas de automação (como Puppeteer ou Playwright) para se conectar a um perfil em execução.

Onde posso encontrar meu token de API?

A API está disponível para usuários com a assinatura Base e superior.

O token de API é mostrado nas configurações da conta principal, na aba “Adicional”. Outros membros da equipe não podem ver o token de API.