Per sviluppatori

API per Sviluppatori: REST, Webhook e Schema Dati

Data Alchemy espone il suo motore di Intelligent Document Processing tramite REST API, webhook e connettori SQL. Invia 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. Questa pagina è la documentazione API per sviluppatori e system integrator.

Richiedi l'accesso API Vedi l'integrazione ERP →

Cos'è

Un'API IDP che trasforma i documenti in dati strutturati

L'API per sviluppatori è il lato programmatico della piattaforma di Intelligent Document Processing di Data Alchemy. Invece di usare l'app web, i tuoi sistemi inviano i documenti via HTTP e ricevono dati validati e strutturati in risposta: così puoi incorporare l'estrazione di fatture, DDT e ordini direttamente nel tuo software, automatizzare il ciclo passivo o alimentare qualsiasi ERP o CRM senza reinserimento manuale.

Autenticazione

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.

Richiesta — invio documento (cURL)

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"

Riferimento API

Riferimento REST API: invia un documento e leggi i dati

Il flusso tipico è asincrono: invii un documento con una POST, ricevi un id e lo stato di elaborazione, poi recuperi il risultato con una GET — oppure, meglio, lasci che sia il webhook a notificarti al termine. Tutti gli endpoint sono versionati sotto /v1.

POST/v1/documentsInvia un documento (PDF, XML, immagine) e avvia l'estrazione. Restituisce un id e lo stato.

GET/v1/documents/{id}Recupera lo stato e i dati estratti e validati di un documento già inviato.

GET/v1/documentsElenca i documenti elaborati con filtri per stato, tipo e intervallo di date.

POST/v1/webhooksRegistra un endpoint che riceverà gli eventi document.processed in tempo reale.

Risposta 202 — documento in elaborazione

{
  "id": "doc_8a7f2c91",
  "status": "processing",
  "document_type": "invoice",
  "created_at": "2026-06-04T09:12:33Z",
  "webhook_url": "https://yourapp.example.com/hooks/data-alchemy"
}

Recupero del risultato (cURL)

curl https://api.data-alchemy.ai/v1/documents/doc_8a7f2c91 \
  -H "Authorization: Bearer $DATA_ALCHEMY_API_KEY"

Webhook

Webhook: ricevi i dati appena il documento è pronto

Registra un URL e Data Alchemy invia una POST al tuo endpoint quando ogni documento è stato elaborato, così non devi 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à.

Payload webhook — document.processed

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 */ }
}

Schema dati

Schema dei dati di output (JSON)

Ogni documento restituisce JSON tipizzato e validato: testata (fornitore, numero, date), righe di dettaglio, totali, IVA e l'esito della validazione sull'anagrafica del gestionale. La struttura è coerente tra i tipi di documento, così il mapping verso il tuo ERP si scrive una sola volta.

Schema di output — fattura

{
  "document_type": "invoice",
  "header": {
    "supplier": {
      "name": "Rossi Forniture S.r.l.",
      "vat_number": "IT01234567890"
    },
    "invoice_number": "2026/00417",
    "issue_date": "2026-05-28",
    "currency": "EUR"
  },
  "line_items": [
    {
      "sku": "ART-0042",
      "description": "Cartone 30x20x15",
      "quantity": 12,
      "unit_price": 8.50,
      "total": 102.00,
      "vat_rate": 22
    }
  ],
  "totals": { "net": 102.00, "vat": 22.44, "gross": 124.44 },
  "validation": { "status": "validated", "erp_match": true }
}

document_type: Tipo di documento classificato dall'AI: invoice, delivery_note, order, contract, price_list.
header: Dati di testata: anagrafica fornitore/cliente, partita IVA, numero documento, date e valuta.
line_items: Array delle righe: codice articolo (SKU), descrizione, quantità, prezzo unitario, totale e aliquota IVA.
totals: Totali calcolati e ricontrollati: imponibile (net), imposta (vat) e totale documento (gross).
validation: Esito della validazione in tempo reale sull'anagrafica dell'ERP, con flag erp_match ed eventuali anomalie.

Metodi di integrazione

Quattro modi per integrare l'estrazione documenti

REST API

Invia un documento e recupera i dati estratti e validati come JSON strutturato, pronto da mappare sul tuo ERP.

Webhook

Pipeline asincrone event-driven: Data Alchemy notifica il tuo endpoint a fine elaborazione, senza polling.

Connettori SQL

Preferisci l'integrazione a livello database? Scrivi i dati estratti direttamente nel tuo sistema via SQL.

Acquisizione da email

Collega una casella Google Workspace o Microsoft 365 e lascia che l'AI acquisisca i documenti — integrazione a zero codice.

Approfondisci

Esplora la piattaforma dietro l'API

Integrazione ERP

SAP, Zucchetti, TeamSystem

Come i dati estratti vengono scritti nel gestionale via API REST, webhook e SQL.

Scopri di più →Tecnologia

Un LLM dedicato per documento

Il motore AISP che assegna a ogni modello documentale l'LLM migliore per leggerlo.

Scopri di più →Piattaforma IDP

Soluzione IDP completa

Fatture, ordini, contratti e listini elaborati dalla stessa piattaforma AI.

Scopri di più →

FAQ

Domande frequenti sull'API per sviluppatori

Che cos'è l'API per sviluppatori di Data Alchemy?

È l'interfaccia programmatica del motore di Intelligent Document Processing (IDP) di Data Alchemy. Invece di usare l'app web, i tuoi sistemi inviano documenti — fatture, DDT, ordini, contratti, listini — e ricevono in risposta dati strutturati e validati, pronti da scrivere nel tuo ERP o CRM.

Quali metodi di integrazione sono disponibili?

Data Alchemy espone una REST API e webhook per i flussi event-driven, oltre a connettori SQL diretti per chi preferisce l'integrazione a livello database. I documenti possono anche essere acquisiti automaticamente da una casella Google Workspace o Microsoft 365, senza scrivere codice.

In che formato tornano i dati estratti?

I campi estratti vengono restituiti come JSON strutturato — dati di testata, righe di dettaglio, totali, imposte e riferimenti documento — già validati sull'anagrafica del tuo gestionale, così possono essere mappati direttamente sul sistema di riferimento.

Come funziona l'autenticazione e la sicurezza dei webhook?

Le richieste si autenticano con una API key Bearer nell'header Authorization, su HTTPS. I webhook in uscita sono firmati con HMAC SHA-256 nell'header X-Data-Alchemy-Signature, così puoi verificare che ogni notifica provenga davvero da Data Alchemy prima di processarla.

Quanto è accurata e veloce l'estrazione?

Data Alchemy assegna un LLM dedicato a ogni modello di documento (oggi Claude AI), raggiungendo il 99,8% di accuratezza in circa 3 secondi a documento, senza template e senza addestramento per layout.

In quali ERP posso scrivere i dati?

L'API è agnostica rispetto al sistema: esistono integrazioni native per SAP, Zucchetti e TeamSystem, mentre REST API, webhook e connettori SQL permettono di inviare i dati strutturati a qualsiasi altro ERP, CRM o applicazione interna.

Costruisci con l'API per sviluppatori

Raccontaci il tuo caso d'uso: attiviamo l'accesso API e ti accompagniamo nell'integrazione sui tuoi documenti reali, senza impegno.

Richiedi l'accesso API