API IDP per Sviluppatori: Estrazione Dati da Fatture, DDT e Ordini in JSON via REST e Webhook

Data Alchemy espone il suo motore di Intelligent Document Processing (IDP) tramite REST API, webhook e connettori SQL: una soluzione IDP con integrazione nativa a ERP e CRM, pensata per chi deve automatizzare il data entry documentale invece di ricostruirlo a mano. 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 API Zucchetti.

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"

Quickstart: dalla prima chiamata al JSON in 5 minuti

1. Genera la API key. Dalla console Data Alchemy crea una chiave per l'ambiente di test o di produzione. La chiave va conservata lato server (variabile d'ambiente o secret manager), mai nel codice client o nel browser.
2. Invia il primo documento. Una POST multipart su /v1/documents con il PDF e il document_type avvia l'estrazione e restituisce subito un id e lo stato processing.
3. Registra un webhook. Con una POST su /v1/webhooks indichi l'URL che riceverà l'evento document.processed: eviti il polling e ricevi i dati nell'istante in cui l'elaborazione termina.
4. Verifica la firma HMAC. Ricalcola l'HMAC SHA-256 sul body grezzo e confrontalo con l'header X-Data-Alchemy-Signature prima di leggere il payload.
5. Mappa il JSON sul tuo ERP. Lo schema di output è identico per tutti i tipi di documento: scrivi il mapping una sola volta e riusalo per fatture, DDT, ordini, contratti e listini.

Una singola integrazione copre l'intero ciclo passivo: ricezione documento, classificazione automatica, estrazione, validazione sull'anagrafica del gestionale e scrittura in SAP, Zucchetti o TeamSystem.

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

API OCR ed estrazione dati: cosa cambia rispetto a un OCR classico

Se stai cercando un'API OCR per leggere fatture e documenti, questa API fa quel lavoro e si ferma un passo più avanti. Un OCR restituisce il testo che ha riconosciuto sull'immagine: una stringa, che poi qualcuno deve interpretare per capire quale numero è l'imponibile e quale la partita IVA. Qui la chiamata è la stessa — una POST multipart con il tuo PDF — ma la risposta è già JSON tipizzato, con testata, righe, totali ed esito della validazione sull'anagrafica del gestionale.

In pratica: dove con un OCR scriveresti tu il parser e lo manterresti a ogni fornitore nuovo, qui il parsing è il servizio. Il documento passa per il riconoscimento del testo, la classificazione del tipo, l'estrazione dei campi con un LLM dedicato e la validazione — e quello che torna al tuo codice è la struttura descritta nello schema di output qui sopra, identica tra tipi di documento diversi.

Se stai ancora decidendo quale delle due tecnologie ti serve, il confronto software OCR fatture vs IDP AI entra nel dettaglio. Se preferisci vederlo su un tuo documento, prova gratis l'estrazione OCR.

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