Guia de integração da API de renderização de páginas WebExtrator

POST https://api.acedata.cloud/webextrator/render A API de renderização de páginas WebExtrator é um serviço de renderização de páginas baseado em Chromium sem interface. Dado um URL, retorna o HTML totalmente renderizado (incluindo conteúdo injetado por JS), texto puro, título da página e URL final. Render é a interface mais básica do WebExtrator. Se você precisar de resultados de extração estruturados (corpo de artigo, preço de produto, ingredientes de receita …), use /webextrator/extract —— ela executa um pipeline completo de extração tipada sobre a mesma base de renderização.

Processo de solicitação

Para usar a página de serviço WebExtrator, primeiro obtenha seu API Token no Console Ace Data Cloud e guarde-o para uso posterior.

Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login, convidando você a se registrar e entrar; após a conclusão, você retornará automaticamente à página atual. Um único API Token permite chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concede créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no Console.

📘 Documentação completa: Página de serviço WebExtrator →

Autenticação

Todas as interfaces WebExtrator usam autenticação padrão Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parâmetros de solicitação

Campo	Tipo	Obrigatório	Padrão	Descrição
`url`	string	✅	—	URL da página a renderizar; deve ser `http(s)://`.
`user_agent`	string	❌	Rotação de pool de UA integrado	User-Agent personalizado.
`timeout`	integer	❌	`30`	Tempo limite de navegação única (segundos inteiros positivos).
`wait_until`	enum	❌	`load`	Evento de conclusão de carregamento: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Segundos de espera adicional após o disparo de `wait_until` (inteiro não negativo) (para renderização secundária de SPA).
`wait_for_selector`	string	❌	—	Aguarda o aparecimento deste seletor CSS, mais estável que `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Tipos de recursos bloqueados, opcionais: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Cabeçalhos de solicitação HTTP adicionais (por exemplo, `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookies injetados antes da navegação; a estrutura é mostrada abaixo.
`callback_url`	string	❌	—	Endereço de callback no modo assíncrono; a plataforma faz `POST` do resultado completo para este endereço quando a tarefa é concluída.
`bypass_cache`	boolean	❌	`false`	Ignora a leitura do cache Redis (mas ainda grava o resultado desta vez de volta no cache).
`cache_ttl_seconds`	integer	❌	`3600`	TTL de cache personalizado para esta gravação; passar `0` significa não armazenar esta resposta em cache.
`async`	boolean	❌	`false`	Defina como `true` para retornar `task_id` imediatamente; o resultado é recuperado por `callback_url` ou pela API Tasks.

O contrato da plataforma usa uniformemente snake_case. O serviço de renderização interno suporta camelCase, mas chamadas externas sempre usam snake_case.

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

Resposta síncrona

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

Campo	Tipo	Descrição
`data.kind`	string	Fixo como `"render"`.
`data.url`	string	O URL que você enviou.
`data.finalUrl`	string	URL final após seguir redirecionamentos.
`data.title`	string	`document.title` após a renderização.
`data.status`	number \| null	Código de status HTTP da navegação principal.
`data.html`	string	HTML completo após a renderização.
`data.text`	string	Instantâneo de `document.body.innerText` (para um corpo mais limpo, use Extract).
`data.userAgent`	string	UA realmente usado.
`data.elapsedMs`	number	Apenas o tempo de renderização do navegador.
`data.cached`	boolean?	`true` quando o cache é atingido.
`data.cacheStoredAt`	number?	Carimbo de data/hora Unix em milissegundos de quando a entrada de cache foi gravada pela primeira vez.

Resposta assíncrona

Quando async=true (ou callback_url é fornecido), retorna imediatamente (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

O resultado será enviado por POST para callback_url (se configurado), ou consultado ativamente por meio de /webextrator/tasks.

Estrutura de callback

A plataforma faz POST do envelope exatamente igual ao modo síncrono para callback_url, com Content-Type: application/json. Retornar qualquer 2xx é considerado uma confirmação; 5xx será repetido com recuo exponencial por aproximadamente 5 minutos.

Resposta de erro

HTTP	`error.code`	Significado
400	`bad_request`	O corpo da solicitação não passou na validação do Zod (falta `url`, tipo incorreto …).
401	`unauthorized`	`Authorization: Bearer …` ausente ou inválido.
402	(x402)	Saldo insuficiente na plataforma, retorna o envelope de requisito de pagamento x402.
408	`timeout`	A navegação excede `timeout`.
429	`queue_busy`	A fila síncrona está congestionada; tente novamente ou use `async=true`.
500	`internal_error`	Exceção não tratada no servidor (falha do navegador etc.); o Worker tenta novamente uma vez automaticamente.

Estrutura de erro:

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid url" }
}

Exemplos

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

Assíncrono + callback

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

Retorna imediatamente { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }； quando a tarefa for concluída, a plataforma fará POST do resultado completo para o seu callback_url.

Ignorar o cache à força

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

Dicas e armadilhas

Escolher wait_until corretamente é importante. networkidle é o mais estável, mas o mais lento; domcontentloaded é rápido, mas pode deixar de fora conteúdo injetado assincronamente; load é adequado para páginas estáticas tradicionais.
A chave de cache ignora async. Solicitações síncronas e assíncronas para a mesma URL atingem a mesma entrada de cache, alternar livremente não a invalidará.
A chave de cache ignora bypass_cache e cache_ttl_seconds. Esses dois são opções de operação, e não afetam o conteúdo da resposta.
cookies e headers segmentam o cache. Personalizar esses dois fará com que o primeiro acesso da mesma combinação falhe.
SPAs pesadas frequentemente excedem os 30 segundos padrão. Recomenda-se timeout: 60, wait_until: "domcontentloaded", delay: 4, e então usar wait_for_selector para aguardar os elementos que realmente importam.
block_resources é o caminho mais rápido para reduzir a latência. Imagens / fontes / mídia já são bloqueadas por padrão; se a sua extração não depende do layout CSS, adicionar stylesheet pode torná-la ainda mais rápida.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Guia de integração da API de renderização de páginas WebExtrator

Processo de solicitação

Autenticação

Parâmetros de solicitação

Resposta síncrona

Resposta assíncrona

Estrutura de callback

Resposta de erro

Exemplos

cURL

Python (requests)

Node.js (fetch)

Assíncrono + callback

Ignorar o cache à força

Dicas e armadilhas

​Processo de solicitação

​Autenticação

​Parâmetros de solicitação

​Estrutura de Cookie

​Resposta síncrona

​Resposta assíncrona

​Estrutura de callback

​Resposta de erro

​Exemplos

​cURL

​Python (requests)

​Node.js (fetch)

​Assíncrono + callback

​Ignorar o cache à força

​Dicas e armadilhas

Processo de solicitação

Autenticação

Parâmetros de solicitação

Estrutura de Cookie

Resposta síncrona

Resposta assíncrona

Estrutura de callback

Resposta de erro

Exemplos

cURL

Python (requests)

Node.js (fetch)

Assíncrono + callback

Ignorar o cache à força

Dicas e armadilhas