Guida all'integrazione dell'API di rendering web WebExtrator

POST https://api.acedata.cloud/webextrator/render L’API di rendering web WebExtrator è un servizio di rendering web basato su Chromium headless. Fornisci un URL, restituisce l’HTML completamente renderizzato (inclusi i contenuti iniettati da JS), testo semplice, titolo della pagina e URL finale. Render è l’interfaccia più basilare di WebExtrator. Se ti servono risultati di estrazione strutturati (corpo dell’articolo, prezzo del prodotto, ingredienti della ricetta …), usa /webextrator/extract —— esegue un’intera pipeline di estrazione tipizzata sulla stessa base di rendering.

Procedura di richiesta

Per utilizzare la pagina del servizio WebExtrator, vai prima alla console Ace Data Cloud per ottenere il tuo API Token, da conservare come backup.

Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza bisogno di richiederne uno separatamente per ogni servizio. La prima richiesta include crediti gratuiti, per provare gratuitamente; quando i crediti sono insufficienti, puoi ricaricare il saldo comune nella console.

📘 Documentazione completa: Pagina del servizio WebExtrator →

Autenticazione

Tutte le interfacce WebExtrator utilizzano l’autenticazione standard Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parametri della richiesta

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
`url`	string	✅	—	URL della pagina da renderizzare, deve essere `http(s)://`.
`user_agent`	string	❌	Rotazione del pool UA integrato	User-Agent personalizzato.
`timeout`	integer	❌	`30`	Timeout della singola navigazione (secondi interi positivi).
`wait_until`	enum	❌	`load`	Evento di completamento del caricamento: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Secondi di attesa aggiuntivi dopo l’attivazione di `wait_until` (intero non negativo) (per il rendering secondario SPA).
`wait_for_selector`	string	❌	—	Attende la comparsa di questo selettore CSS, più stabile di `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Tipi di risorse bloccati, opzionali: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Intestazioni di richiesta HTTP aggiuntive (ad esempio `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookie iniettati prima della navigazione, struttura riportata sotto.
`callback_url`	string	❌	—	Indirizzo di callback in modalità asincrona, la piattaforma invia tramite `POST` il risultato completo a questo indirizzo al completamento dell’attività.
`bypass_cache`	boolean	❌	`false`	Ignora la lettura della cache Redis (ma scrive comunque il risultato corrente nella cache).
`cache_ttl_seconds`	integer	❌	`3600`	TTL della cache personalizzato per questa scrittura, passando `0` la risposta corrente non viene memorizzata nella cache.
`async`	boolean	❌	`false`	Impostalo su `true` per restituire immediatamente `task_id`; il risultato viene recuperato tramite `callback_url` o Tasks API.

Il contratto della piattaforma utilizza uniformemente snake_case. Il servizio di rendering interno supporta camelCase, ma le chiamate esterne utilizzano sempre snake_case.

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

Risposta sincrona

{
  "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	Descrizione
`data.kind`	string	Fisso a `"render"`.
`data.url`	string	L’URL che hai inviato.
`data.finalUrl`	string	L’URL finale dopo aver seguito i reindirizzamenti.
`data.title`	string	Il `document.title` dopo il rendering.
`data.status`	number \| null	Codice di stato HTTP della navigazione principale.
`data.html`	string	HTML completo dopo il rendering.
`data.text`	string	Snapshot di `document.body.innerText` (per un corpo più pulito usa Extract).
`data.userAgent`	string	L’UA effettivamente utilizzato.
`data.elapsedMs`	number	Solo tempo di rendering del browser.
`data.cached`	boolean?	È `true` quando viene colpita la cache.
`data.cacheStoredAt`	number?	Timestamp Unix in millisecondi della prima scrittura della voce in cache.

Risposta asincrona

Quando async=true (o viene fornito callback_url) restituisce immediatamente (HTTP 200):

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

Il risultato verrà inviato tramite POST a callback_url (se configurato), oppure potrà essere interrogato attivamente tramite /webextrator/tasks.

Struttura del callback

La piattaforma invia tramite POST lo stesso envelope identico alla modalità sincrona a callback_url, con Content-Type: application/json. La restituzione di qualsiasi 2xx viene considerata una conferma; i 5xx verranno ritentati con backoff esponenziale per circa 5 minuti.

Risposta di errore

HTTP	`error.code`	Significato
400	`bad_request`	Il corpo della richiesta non supera la convalida Zod (manca `url`, tipo errato …).
401	`unauthorized`	`Authorization: Bearer …` mancante o non valido.
402	(x402)	Saldo della piattaforma insufficiente, restituisce un envelope con richiesta di pagamento x402.
408	`timeout`	La navigazione supera `timeout`.
429	`queue_busy`	Coda sincrona congestionata, riprova o usa `async=true`.
500	`internal_error`	Eccezione non gestita lato server (arresto anomalo del browser ecc.), il Worker riprova automaticamente una volta.

Struttura dell’errore:

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

Esempi

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);

Asincrono + 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"
  }'

Restituisce immediatamente { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }； quando l’attività è completata, la piattaforma invia tramite POST il risultato completo al tuo callback_url.

Forzare il bypass della cache

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
  }'

Suggerimenti e insidie

È importante scegliere correttamente wait_until. networkidle è il più stabile ma il più lento; domcontentloaded è veloce ma potrebbe tralasciare contenuti iniettati in modo asincrono; load è adatto alle pagine statiche tradizionali.
La chiave della cache ignora async. Le richieste sincrone e asincrone per lo stesso URL colpiscono la stessa voce della cache, quindi passare arbitrariamente dall’una all’altra non la invalida.
La chiave della cache ignora bypass_cache e cache_ttl_seconds. Questi due sono interruttori operativi, non influiscono sul contenuto della risposta.
cookies e headers suddividono la cache in bucket. Personalizzare questi due fa sì che il primo hit della stessa combinazione fallisca.
Le SPA pesanti superano spesso i 30 secondi predefiniti. Si consiglia timeout: 60, wait_until: "domcontentloaded", delay: 4, insieme a wait_for_selector per attendere gli elementi di reale interesse.
block_resources è il percorso più rapido per ridurre la latenza. Per impostazione predefinita immagini / font / media sono già bloccati; se la tua estrazione non dipende dal layout CSS, aggiungere stylesheet può renderla ancora più veloce.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Guida all'integrazione dell'API di rendering web WebExtrator

Procedura di richiesta

Autenticazione

Parametri della richiesta

Risposta sincrona

Risposta asincrona

Struttura del callback

Risposta di errore

Esempi

cURL

Python (requests)

Node.js (fetch)

Asincrono + callback

Forzare il bypass della cache

Suggerimenti e insidie

​Procedura di richiesta

​Autenticazione

​Parametri della richiesta

​Struttura dei Cookie

​Risposta sincrona

​Risposta asincrona

​Struttura del callback

​Risposta di errore

​Esempi

​cURL

​Python (requests)

​Node.js (fetch)

​Asincrono + callback

​Forzare il bypass della cache

​Suggerimenti e insidie

Procedura di richiesta

Autenticazione

Parametri della richiesta

Struttura dei Cookie

Risposta sincrona

Risposta asincrona

Struttura del callback

Risposta di errore

Esempi

cURL

Python (requests)

Node.js (fetch)

Asincrono + callback

Forzare il bypass della cache

Suggerimenti e insidie