WebExtrator Guida all'integrazione dell'API di rendering delle pagine web

POST https://api.acedata.cloud/webextrator/render L’API di rendering delle pagine web WebExtrator è un servizio di rendering basato su Chromium senza testa. 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 di base di WebExtrator. Se hai bisogno di risultati di estrazione strutturati (testo dell’articolo, prezzi dei prodotti, ingredienti delle ricette …), utilizza /webextrator/extract —— che esegue un’intera pipeline di estrazione tipizzata sulla stessa base di rendering.

Processo di richiesta

Per utilizzare la pagina del servizio WebExtrator, prima vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro.

Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere, una volta completato verrai automaticamente riportato alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, non è necessario richiederne uno separato per ogni servizio. La prima richiesta riceverà un credito gratuito, per un’esperienza gratuita; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 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 di richiesta

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
`url`	string	✅	—	URL della pagina da renderizzare, deve essere `http(s)://`.
`user_agent`	string	❌	Pool UA integrato rotante	User-Agent personalizzato.
`timeout`	number	❌	`30`	Timeout per navigazione singola (secondi).
`wait_until`	enum	❌	`networkidle`	Evento di completamento del caricamento: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	number	❌	`0`	Secondi di attesa aggiuntivi dopo il trigger di `wait_until` (per il secondo rendering di SPA).
`wait_for_selector`	string	❌	—	Attendere che questo selettore CSS appaia, più stabile di `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Tipi di risorse da bloccare, opzioni: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Intestazioni HTTP aggiuntive (es. `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookie iniettati prima della navigazione, struttura come sotto.
`callback_url`	string	❌	—	Indirizzo di callback in modalità asincrona, la piattaforma `POST` i risultati completi a questo indirizzo al termine del compito.
`bypass_cache`	boolean	❌	`false`	Salta la lettura della cache Redis (ma scriverà comunque il risultato nella cache).
`cache_ttl_seconds`	number	❌	`3600`	TTL della cache personalizzato per questa scrittura, invia `0` per non memorizzare questa risposta.
`async`	boolean	❌	`false`	Imposta su `true` per restituire immediatamente `task_id`, i risultati possono essere recuperati tramite `callback_url` o Tasks API.

Il contratto della piattaforma utilizza uniformemente snake_case. I servizi di rendering interni supportano 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 `"render"`.
`data.url`	string	L’URL che hai inviato.
`data.finalUrl`	string	URL finale dopo il reindirizzamento.
`data.title`	string	`document.title` renderizzato.
`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 testo più pulito, utilizza Extract).
`data.userAgent`	string	UA effettivamente utilizzato.
`data.elapsedMs`	number	Tempo impiegato solo per il rendering del browser.
`data.cached`	boolean?	`true` se è stata colpita la cache.
`data.cacheStoredAt`	number?	Timestamp Unix in millisecondi della prima scrittura dell’elemento della cache.

Risposta asincrona

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

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

I risultati verranno inviati tramite POST a callback_url (se configurato), oppure tramite /webextrator/tasks per interrogare attivamente.

Struttura del callback

La piattaforma POST invia un envelope identico a quello della modalità sincrona a callback_url, Content-Type: application/json. Restituire qualsiasi 2xx è considerato confermato; 5xx verrà riprovato con backoff esponenziale per circa 5 minuti.

Risposta di errore

HTTP	`error.code`	Significato
400	`bad_request`	Il corpo della richiesta non ha superato la validazione Zod (manca `url`, tipo errato …).
401	`unauthorized`	Mancanza o invalidità di `Authorization: Bearer …`.
402	(x402)	Saldo della piattaforma insufficiente, restituisce x402 richiesta di pagamento envelope.
408	`timeout`	Navigazione oltre il `timeout`.
429	`queue_busy`	La coda di sincronizzazione è affollata, riprova o usa `async=true`.
500	`internal_error`	Eccezione non gestita dal server (crash del browser, ecc.), 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" }
}

Esempio

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 il compito è completato, la piattaforma invierà un POST con 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 problemi

È importante scegliere correttamente wait_until. networkidle è il più stabile ma il più lento; domcontentloaded è veloce ma potrebbe perdere contenuti iniettati in modo asincrono; load è adatto per pagine statiche tradizionali.
La chiave della cache ignora async. Le richieste sincrone e asincrone per lo stesso URL colpiscono la stessa voce di cache, passare liberamente non causerà errori.
La chiave della cache ignora bypass_cache e cache_ttl_seconds. Questi due sono interruttori operativi, non influenzano il contenuto della risposta.
I cookies e gli headers verranno memorizzati in cache separatamente. Personalizzare questi due farà sì che la prima combinazione identica 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 modo più veloce per ridurre la latenza. Per impostazione predefinita, sono già bloccati immagini / font / media; se l’estrazione non dipende dal layout CSS, aggiungere stylesheet può rendere tutto ancora più veloce.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

WebExtrator Guida all'integrazione dell'API di rendering delle pagine web

Processo di richiesta

Autenticazione

Parametri di richiesta

Risposta sincrona

Risposta asincrona

Struttura del callback

Risposta di errore

Esempio

cURL

Python (requests)

Node.js (fetch)

Asincrono + Callback

Forzare il bypass della cache

Suggerimenti e problemi

​Processo di richiesta

​Autenticazione

​Parametri di richiesta

​Struttura dei Cookie

​Risposta sincrona

​Risposta asincrona

​Struttura del callback

​Risposta di errore

​Esempio

​cURL

​Python (requests)

​Node.js (fetch)

​Asincrono + Callback

​Forzare il bypass della cache

​Suggerimenti e problemi

Processo di richiesta

Autenticazione

Parametri di richiesta

Struttura dei Cookie

Risposta sincrona

Risposta asincrona

Struttura del callback

Risposta di errore

Esempio

cURL

Python (requests)

Node.js (fetch)

Asincrono + Callback

Forzare il bypass della cache

Suggerimenti e problemi