API IDP per Sviluppatori: Estrazione Dati da Documenti via REST, Webhook e JSON

Data Alchemy espone il suo motore di Intelligent Document Processing (IDP) tramite REST API, webhook e connettori SQL. Con questa API di estrazione dati invii fatture, DDT, ordini o contratti e ricevi JSON strutturato e validato — 99,8% di accuratezza in circa 3 secondi a documento, pronto da scrivere nel tuo gestionale ERP come SAP, Zucchetti o TeamSystem. Questa pagina è la documentazione API per sviluppatori e system integrator: endpoint REST, webhook, schema dei dati e integrazione Zucchetti via API.

Base URL e autenticazione

Tutte le richieste usano HTTPS verso https://api.data-alchemy.ai/v1 e si autenticano con una API key Bearer trasmessa nell'header Authorization. Le chiavi si generano dalla console e vanno conservate lato server, mai esposte nel browser. Ogni risposta è in formato JSON UTF-8.

curl -X POST https://api.data-alchemy.ai/v1/documents \
  -H "Authorization: Bearer $DATA_ALCHEMY_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@fattura.pdf" \
  -F "document_type=invoice"

Webhook: cos'è e come funziona

Un webhook è una richiesta HTTP che un servizio invia automaticamente a un URL indicato da te, non appena si verifica un evento. È il contrario di una normale chiamata API: non sei tu a chiedere «il documento è pronto?», è il servizio che ti avvisa da solo quando lo è. Per questo un webhook viene spesso descritto come una «API al contrario» o una callback HTTP: l'applicazione che riceve l'evento espone un endpoint pubblico e resta in ascolto, mentre è il servizio a fare da client.

In Data Alchemy funziona così: registri un URL e riceverai una POST al tuo endpoint appena un documento è stato elaborato, senza dover fare polling. Il payload contiene l'evento, l'id del documento, il livello di confidenza e i dati estratti secondo lo schema di output. Ogni richiesta è firmata con HMAC SHA-256 nell'header X-Data-Alchemy-Signature per verificarne l'autenticità.

POST /hooks/data-alchemy  (X-Data-Alchemy-Signature: sha256=...)

{
  "event": "document.processed",
  "id": "doc_8a7f2c91",
  "status": "completed",
  "confidence": 0.998,
  "data": { /* schema di output — vedi sotto / see below */ }
}

Webhook o polling: qual è la differenza?

Con il polling è il tuo sistema a interrogare ripetutamente l'API («è pronto adesso?»), sprecando chiamate finché l'elaborazione non termina e introducendo un ritardo pari all'intervallo di attesa. Con un webhook la notifica parte nell'istante in cui il documento è pronto: nessuna chiamata a vuoto, nessun ritardo artificiale e un carico molto minore su entrambi i lati. Il polling resta comunque utile come rete di sicurezza — ad esempio per recuperare un documento se il tuo endpoint è stato irraggiungibile a lungo.

Come verificare la firma di un webhook

Poiché il tuo endpoint è pubblico, chiunque potrebbe inviargli una POST. Per questo ogni webhook di Data Alchemy viaggia con l'header X-Data-Alchemy-Signature, che contiene l'HMAC SHA-256 del corpo grezzo della richiesta calcolato con il tuo secret. Ricalcola la firma sul body ricevuto e confrontala con quella dell'header usando un confronto a tempo costante: se non coincidono, scarta la richiesta. Verifica sempre la firma prima di leggere il payload.

import crypto from "node:crypto";

// Il body va letto grezzo: un JSON già parsato e riserializzato
// produrrebbe una firma diversa. / Read the raw body: a parsed and
// re-serialised JSON would produce a different signature.
function isFromDataAlchemy(rawBody, header, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = header.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

Rate limit, retry e gestione degli errori

Le risposte usano codici HTTP standard: 202 per un documento accettato e in elaborazione, 200 al recupero del risultato, 401 per API key mancante o non valida, 422 per un documento non leggibile e 429 al superamento del rate limit. Ogni errore restituisce un JSON con error.code e error.message.

In caso di 429 o di errori 5xx è consigliato un retry con backoff esponenziale, così da non aggravare un servizio già sotto carico. I webhook non consegnati vengono ritentati automaticamente con backoff crescente, così nessun evento document.processed va perso anche se il tuo endpoint resta irraggiungibile per qualche minuto.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 30s."
  }
}

Esplora la piattaforma dietro l'API