Integrazione API Zucchetti: dati da fatture, DDT e ordini nel gestionale
Con Data Alchemy fatture, DDT e ordini arrivano in Zucchetti già letti dall'AI e verificati sulla tua anagrafica, senza data entry manuale. I tuoi utenti continuano a lavorare in Zucchetti e controllano solo le eccezioni segnalate.
Cosa cambia per chi registra fatture e DDT in Zucchetti
Il punto di vista dell'ufficio amministrativo, senza dettagli tecnici: quelli sono più in basso, per chi segue l'integrazione.
Si continua a lavorare in Zucchetti
Gli utenti continuano a lavorare in Zucchetti: nessun nuovo software da imparare. L'automazione opera dietro le quinte, sull'acquisizione dei documenti.
Cosa arriva nel gestionale
Da fatture passive, DDT e ordini: fornitore e partita IVA, numero e data del documento, righe con codice articolo, quantità, prezzo unitario e aliquota IVA, imponibile, imposta e totale. L'AI legge senza template né regole per layout: non serve preparare un modello per ogni fornitore.
Si controllano solo le eccezioni
Prima della registrazione i dati sono confrontati con l'anagrafica di Zucchetti: se un fornitore o un codice articolo non trova riscontro, il documento viene segnalato per la revisione invece di entrare nel gestionale. Il team passa dal copiare al controllare le eccezioni.
Come si collega a Zucchetti
Il collegamento avviene tramite l'Agente AI installato presso di te (database, file o API) oppure con un'integrazione sviluppata sulle API REST di Data Alchemy: i dettagli tecnici sono più in basso.
Perché integrare Zucchetti con un motore IDP
Zucchetti (Ad Hoc, Mago, Infinity) è tra i gestionali più diffusi nelle PMI italiane, ma il ciclo passivo richiede ancora di inserire a mano fatture, DDT e ordini. Un software di Intelligent Document Processing (IDP, il software che legge i documenti con l'AI e ne estrae i dati strutturati) integrato con Zucchetti riduce il data entry manuale e alimenta il gestionale in automatico: ogni documento viene letto, estratto e scritto in Zucchetti senza digitazione, eliminando errori, ritardi e riconciliazioni che pesano sull'amministrazione.
L'integrazione Zucchetti di Data Alchemy elimina questo lavoro: l'Intelligent Document Processing legge il documento, estrae i campi, li confronta con l'anagrafica di Zucchetti (fornitori, articoli, condizioni) e scrive il record direttamente nel gestionale, pronto per la registrazione.
Questo collegamento diretto tra Data Alchemy e il tuo sistema è ciò che si intende per integrazione nativa: la spiegazione completa, con le modalità di collegamento disponibili, è nella pagina dedicata.
Metodi di integrazione Zucchetti supportati
I dati estratti raggiungono Zucchetti in due modi: con l'Agente AI, installato presso di te, oppure, se sviluppi in proprio, con un'integrazione sulle API REST e i webhook di Data Alchemy, inclusi in ogni licenza.
Agente AI
L'Agente AI è installato presso di te: si collega a Data Alchemy via websocket e API e registra in Zucchetti i dati estratti, ordini con testata e righe compresi, sulla destinazione configurata da interfaccia grafica — database, file CSV, JSON o TXT oppure API — senza connettori da sviluppare. Le credenziali di Zucchetti restano nell'agente, nel tuo perimetro. È incluso nella licenza Enterprise e disponibile come opzione quotata a parte nella Business.
API REST e webhook di Data Alchemy
Per chi sviluppa: invii i documenti con l'API REST e ricevi il JSON strutturato via webhook, firmato HMAC SHA-256, oppure con una GET. La scrittura in Zucchetti la gestisce la tua integrazione.
Servizio mail per l'acquisizione
Dalla licenza Business, il Servizio mail installato presso il cliente preleva i documenti dalle caselle aziendali e li porta in Data Alchemy: fatture, DDT e ordini entrano nel flusso senza caricamenti manuali.
Validazione su anagrafica Zucchetti
Prima della scrittura i dati sono confrontati con l'anagrafica di Zucchetti — fornitori, codici articolo, ordini aperti. Lo fanno la remote validation, che verifica i singoli valori sull'anagrafica (per esempio che un codice articolo esista, o il codice fornitore ricavato dalla partita IVA), e gli external fields, che confrontano il documento con i dati a cui rimanda (per esempio l'ordine d'acquisto richiamato sul DDT). Entrambi sono inclusi dalla licenza Business.
Dal documento a Zucchetti in quattro passaggi
Lo stesso flusso vale per fatture, DDT, ordini, contratti e listini: il documento entra, i dati strutturati escono dentro Zucchetti.
Acquisizione
Il documento arriva via email (caselle aziendali, tramite il Servizio mail on-premise, dalla licenza Business), upload o cartella monitorata.
Estrazione AI
Un LLM dedicato al modello documentale estrae i campi senza template né regole per layout.
Validazione
I dati vengono validati e arricchiti sull'anagrafica Zucchetti, con segnalazione delle anomalie.
Scrittura in Zucchetti
I dati validati arrivano in Zucchetti tramite l'Agente AI installato presso di te (database, file o API) oppure tramite la tua integrazione sulle API REST, pronti per la registrazione.
Cosa cambia con l'integrazione Zucchetti di Data Alchemy
Zero data entry
I dati entrano in Zucchetti senza digitazione manuale: il team amministrativo passa dal copiare al controllare le eccezioni.
Dati coerenti con l'anagrafica
La validazione sull'anagrafica Zucchetti riduce errori di codifica, fornitori sbagliati e articoli non trovati.
Tempi di chiusura più rapidi
Le fatture passive arrivano in Zucchetti senza data entry manuale, accelerando registrazione, controllo e pagamento.
Nessun nuovo software per gli utenti
Gli utenti continuano a lavorare in Zucchetti: l'automazione opera dietro le quinte sull'acquisizione documentale.
Tracciabilità completa
Ogni documento mantiene il legame con il record creato in Zucchetti, per audit e riconciliazione.
Scalabile a tutti i documenti
Dalla fattura al DDT all'ordine: la stessa integrazione Zucchetti copre tutti i flussi documentali.
Documentazione API Zucchetti e requisiti tecnici
Il collegamento con Zucchetti avviene in uno di due modi. Con l'Agente AI, installato presso di te, Data Alchemy scrive in Zucchetti su database, file CSV, JSON o TXT oppure API, in base a cosa supporta la tua installazione (cloud o on-premise): l'agente si collega a Data Alchemy via websocket e API, la destinazione si configura da interfaccia grafica e le credenziali di Zucchetti restano nell'agente, nel tuo perimetro. Non serve sviluppare connettori né conoscere in dettaglio la documentazione API di Zucchetti; se non servono integrazioni custom, l'integrazione richiede 2–5 giorni lavorativi. Se invece preferisci governare il flusso nel tuo stack, usi le API REST e i webhook di Data Alchemy descritti qui sotto: invii il documento, ricevi il JSON validato e la scrittura in Zucchetti la gestisce la tua integrazione.
API Zucchetti: endpoint, payload JSON e mappatura dei campi
Il flusso è lo stesso dell'API di estrazione dati di Data Alchemy: invii il documento con una POST indicando erp_target=zucchetti e ricevi il JSON strutturato — via webhook o con una GET su /v1/documents/{id} — già validato sull'anagrafica di Zucchetti e pronto da scrivere nel gestionale.
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" \
-F "erp_target=zucchetti"{
"event": "document.processed",
"id": "doc_8a7f2c91",
"status": "completed",
"erp_target": "zucchetti",
"data": {
"header": {
"supplier": {
"name": "Rossi Forniture S.r.l.",
"vat_number": "IT01234567890"
},
"invoice_number": "2026/00417",
"issue_date": "2026-05-28"
},
"line_items": [
{
"sku": "ART-0042",
"quantity": 12,
"unit_price": 8.50,
"vat_rate": 22
}
],
"totals": { "net": 102.00, "vat": 22.44, "gross": 124.44 },
"validation": { "status": "validated", "erp_match": true }
}
}Webhook: scrittura in Zucchetti senza polling
Registra il tuo endpoint con una POST su /v1/webhooks e riceverai l'evento document.processed appena l'estrazione è completa, senza interrogare l'API a intervalli. Ogni richiesta è firmata con HMAC SHA-256 nell'header X-Data-Alchemy-Signature: verifica la firma prima di scrivere il record in Zucchetti. Se il tuo endpoint è irraggiungibile, la consegna viene ritentata con backoff crescente, così nessun documento va perso.
Mappatura dei campi verso l'anagrafica Zucchetti
I campi del JSON estratto vengono mappati sui campi corrispondenti di Zucchetti. La validazione avviene prima della scrittura: se la partita IVA non trova riscontro nell'anagrafica fornitori o un codice articolo non esiste, il documento viene segnalato invece di generare un record incoerente.
header.supplier.vat_numberAnagrafica fornitori — Partita IVA (chiave di match)header.supplier.nameAnagrafica fornitori — Ragione socialeheader.invoice_numberTestata documento — Numero documentoheader.issue_dateTestata documento — Data documentoline_items[].skuRighe documento — Codice articolo (anagrafica articoli)line_items[].quantityRighe documento — Quantitàline_items[].unit_priceRighe documento — Prezzo unitarioline_items[].vat_rateRighe documento — Aliquota IVAtotals.net / totals.vat / totals.grossTestata documento — Imponibile, imposta e totalevalidation.erp_matchEsito della validazione: true scrive il record, false lo manda in revisioneAPI Zucchetti: autenticazione, formati supportati e rate limit
Chi integra Zucchetti via API lavora sempre sullo stesso endpoint REST di Data Alchemy: base URL https://api.data-alchemy.ai/v1, autenticazione con API key Bearer e risposte JSON UTF-8. Il flusso di autenticazione è identico per fatture, DDT e ordini destinati al gestionale, e non cambia tra installazioni Zucchetti cloud e on-premise.
Genera la API key
La chiave si crea dalla console di Data Alchemy. Va conservata lato server e non deve mai finire nel browser o in un repository: identifica il tuo tenant.
Autentica ogni richiesta
Tutte le chiamate viaggiano su HTTPS e portano l'header Authorization: Bearer $DATA_ALCHEMY_API_KEY. Non esiste un flusso OAuth da implementare: la API key è sufficiente per inviare documenti e leggere i risultati.
Registra il webhook
Con una POST su /v1/webhooks dichiari l'endpoint che riceverà l'evento document.processed. È il canale consigliato per scrivere in Zucchetti appena l'estrazione è pronta, senza polling.
Verifica la firma HMAC
Ogni webhook è firmato con HMAC SHA-256 nell'header X-Data-Alchemy-Signature. Verifica la firma con il segreto del tuo endpoint prima di scrivere qualsiasi record nel gestionale Zucchetti.
Formati e tipi di documento supportati
L'endpoint POST /v1/documents accetta il file in multipart/form-data insieme al parametro document_type (invoice, delivery_note, order, contract, price_list) e a erp_target=zucchetti. Sono supportati PDF nativi e scansionati, immagini e fatture elettroniche in formato XML FatturaPA. La risposta di accettazione è un 202 con l'id del documento; il JSON strutturato si recupera con una GET su /v1/documents/{id} oppure arriva direttamente al webhook, già validato sull'anagrafica di Zucchetti.
Codici di stato e gestione degli errori
L'API usa codici HTTP standard e restituisce sempre un JSON con error.code ed error.message. Gestire questi casi lato integrazione evita che un documento non leggibile o una chiave scaduta si trasformino in un record incoerente dentro Zucchetti.
202Documento accettato e in elaborazione.200Risultato disponibile e pronto per Zucchetti.401API key mancante, scaduta o non valida.422Documento non leggibile o tipo non supportato.429Rate limit superato: riprova con backoff esponenziale.In caso di 429 o di errori 5xx conviene ritentare con backoff esponenziale invece di insistere a intervallo fisso. I webhook non consegnati vengono ritentati automaticamente con backoff crescente: se il tuo endpoint resta irraggiungibile per qualche minuto, nessun evento document.processed va perso. I documenti che falliscono la validazione sull'anagrafica non vengono scritti nel gestionale ma messi in revisione, con il dettaglio del campo che non ha trovato riscontro.
Altre integrazioni e risorse
SAP
Scrittura diretta dei dati estratti in SAP tramite Agente AI o API REST.
Scopri di più →Integrazione ERPTeamSystem
Integrazione nativa con TeamSystem, dati validati sull'anagrafica.
Scopri di più →APIAPI per sviluppatori
REST API e webhook per integrare l'IDP nel tuo stack, incluso Zucchetti.
Scopri di più →Domande frequenti sull'integrazione Zucchetti
Porta i tuoi documenti dentro Zucchetti, senza data entry
Mostraci un campione dei tuoi documenti: ti facciamo vedere l'estrazione, la validazione sull'anagrafica e la scrittura in Zucchetti sul tuo caso reale.
Pianifica una call con demo sui tuoi documenti