Browser API

A Browser API entrega sessões de navegador headless (Chromium) rodando na infraestrutura da Veloz, com stealth garantido em toda sessão, prontas para você controlar via Playwright com chromium.connectOverCDP(...). Use para automação, scraping, testes end-to-end, geração de PDFs/screenshots ou qualquer fluxo que precise de um navegador real e isolado, sem manter Chromium na sua própria infraestrutura.

Você cria uma sessão, recebe uma connectUrl (um endpoint CDP sobre WebSocket) e conecta com o seu próprio playwright/playwright-core. A Veloz cuida do provisionamento, do isolamento e do encerramento.

Nota: a Browser API está em early access (acesso antecipado) e é liberada por organização. Se a seção Sessões de navegador ainda não aparece no seu dashboard, solicite acesso antecipado para habilitá-la na sua conta.

Chaves de API

Toda chamada usa uma chave bk_live_* no cabeçalho Authorization:

Authorization: Bearer bk_live_sua_chave

Gere e revogue chaves na seção Sessões de navegador → Chaves de API do dashboard. A chave é vinculada à sua organização e concede acesso para criar e controlar sessões.

Segurança: a chave é exibida uma única vez na criação. Copie nesse momento, trate como senha, defina em variável de ambiente (VELOZ_BROWSER_TOKEN) e nunca commite no Git.

SDK @onveloz/browser

A forma recomendada de integrar a partir de Node. O SDK não embute o Playwright — ele entrega a connectUrl e você conecta com o seu próprio cliente.

npm install @onveloz/browser playwright-core

Defina o token no ambiente:

VELOZ_BROWSER_TOKEN=bk_live_sua_chave

Conectar para acordar (uma linha)

Nenhuma sessão é criada de antemão: um navegador quente é provisionado quando você abre o socket CDP e encerrado quando você desconecta. O limite de simultaneidade é checado no momento da conexão.

import { Onveloz } from "@onveloz/browser";
import { chromium } from "playwright-core";
 
const ov = new Onveloz(); // lê VELOZ_BROWSER_TOKEN do ambiente
 
const browser = await chromium.connectOverCDP(await ov.connect());
const page = await browser.contexts()[0].newPage();
await page.goto("https://exemplo.com");
console.log(await page.title());
await browser.close(); // ao desconectar, o navegador é encerrado

Sessão explícita

Quando você precisa do ciclo de vida na mão (criar agora, conectar depois, listar, encerrar):

import { Onveloz } from "@onveloz/browser";
import { chromium } from "playwright-core";
 
const ov = new Onveloz();
 
// O provisionamento roda fora da requisição, então a sessão nasce PENDING.
const session = await ov.sessions.create();
 
// Aguarda ficar RUNNING com connectUrl disponível (polling interno).
const ready = await ov.sessions.waitUntilReady(session.id);
 
const browser = await chromium.connectOverCDP(ready.connectUrl!);
const page = await browser.contexts()[0].newPage();
await page.goto("https://exemplo.com");
 
await browser.close();
await ov.sessions.close(session.id);

Métodos disponíveis no namespace ov.sessions:

E no cliente ov:

Para apontar a um ambiente alternativo, passe { apiUrl } ou defina VELOZ_BROWSER_API.

API REST

Para linguagens fora de Node, fale direto com a API. Base: https://platform.onveloz.com/api/browser. Todas as chamadas exigem o cabeçalho Authorization: Bearer bk_live_*.

Criar e conectar

# 1) Cria a sessão — nasce PENDING.
curl -X POST https://platform.onveloz.com/api/browser/v1/sessions \
  -H "Authorization: Bearer bk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "timeoutSec": 300 }'
# → { "id": "...", "status": "PENDING", "connectUrl": null, "expiresAt": "..." }
 
# 2) Faça polling até connectUrl aparecer (sessão RUNNING).
curl https://platform.onveloz.com/api/browser/v1/sessions/SESSION_ID \
  -H "Authorization: Bearer bk_live_sua_chave"
# → { ..., "status": "RUNNING", "connectUrl": "wss://.../v1/connect?token=..." }

Depois, conecte ao connectUrl com qualquer cliente CDP (Playwright, Puppeteer, ou o protocolo cru).

Estados da sessão

Stealth

Toda sessão já roda com as proteções anti-detecção ativas — fingerprint coerente, WebGL via stack de GPU real e supressão de vazamentos do protocolo. O stealth é garantido e não configurável: não há nada para ligar, e não é possível desligar.

Use o seu próprio proxy

Por padrão o egresso é direto. Para sair por um proxy, traga o seu: informe o gateway em proxyServer (e credenciais, se houver). O proxyCountry mantém o fingerprint de stealth coerente com a geo de saída do seu proxy.

const session = await ov.sessions.create({
  proxyServer: "http://gateway.seu-proxy.com:8080", // http, https ou socks5
  proxyUsername: "usuario", // opcional (omita para proxy autorizado por IP)
  proxyPassword: "senha", // opcional
  proxyCountry: "US", // opcional — país de saída do seu proxy
});

As credenciais são criptografadas em repouso e nunca retornadas nas respostas da API. O proxy próprio é aceito apenas em create() (não em conectar-para-acordar).

Configuração da sessão

Os campos abaixo valem tanto em ov.sessions.create() / ov.connect() quanto no corpo JSON da API REST. O stealth é sempre garantido (não é um campo).

Visualização ao vivo

No dashboard, abra uma sessão para ver o console Sessão ao vivo: a tela do navegador transmitida em tempo real enquanto a sessão roda — útil para acompanhar automações e depurar. A mesma transmissão é o screencast CDP padrão (Page.startScreencast), então você também pode consumi-la a partir do seu próprio cliente CDP.

Limites

As cotas dependem do seu plano:

Estourar o limite de sessões simultâneas retorna 429 (no SDK, BrowserQuotaError). Precisa de cotas maiores? Fale com o suporte.

Boas práticas

Importante: conecte assim que a connectUrl aparecer. Uma sessão RUNNING sem nenhum cliente CDP conectado é liberada por inatividade em poucos segundos. Crie e conecte no mesmo processo — não busque a connectUrl em um passo e conecte em outro muito depois.

• Encerre o que você abre. Chame close() (ou DELETE) ao terminar para liberar a cota; não dependa só do TTL.
• Use conectar-para-acordar para tarefas curtas. É o caminho mais simples: uma connectUrl, conecta, trabalha, desconecta.
• Use timeoutSec para tarefas longas. Suba o TTL até o teto do seu plano quando a automação leva mais que o padrão.
• Trate 429 com backoff. Ao bater no limite de simultaneidade, aguarde uma sessão liberar antes de tentar de novo.

Próximos passos

• Variáveis de Ambiente, para guardar VELOZ_BROWSER_TOKEN com segurança
• Segurança, boas práticas de chaves e segredos