Integrazione API Zucchetti: dati da fatture, DDT e ordini nel gestionale
Cerchi un'integrazione Zucchetti che porti i dati di fatture, DDT e ordini nel gestionale senza data entry manuale? Data Alchemy estrae i dati dai tuoi documenti con l'AI, li valida sull'anagrafica e li scrive in Zucchetti in circa 3 secondi tramite REST API, webhook e query SQL.
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 integrato con Zucchetti riduce il data entry manuale e alimenta il gestionale in tempo reale: 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, senza middleware di terze parti, è ciò che si intende per integrazione nativa: la spiegazione completa, con le differenze rispetto all'integrazione via file e via middleware, è nella pagina dedicata.
Metodi di integrazione Zucchetti supportati
I dati estratti raggiungono Zucchetti attraverso il canale più adatto alla tua installazione, senza dover sviluppare connettori da zero.
REST API
I documenti validati vengono inviati a Zucchetti via API REST in tempo reale, mappati sui campi di fatture, ordini e DDT del tuo ambiente.
Webhook ed eventi
Ogni documento elaborato innesca un webhook: Zucchetti riceve il payload appena l'estrazione è completa, per flussi event-driven senza polling.
Query e scrittura SQL
Per installazioni Zucchetti con accesso al database, i dati vengono scritti tramite query SQL parametriche su tabelle e staging dedicati.
Validazione su anagrafica Zucchetti
Prima della scrittura i dati sono confrontati con l'anagrafica di Zucchetti — fornitori, codici articolo, ordini aperti — per garantire match e coerenza.
Documentazione API Zucchetti e requisiti tecnici
L'integrazione si appoggia alle API REST di Zucchetti (o, dove disponibile, all'accesso al database) per scrivere i record del ciclo passivo. Non serve sviluppare connettori né conoscere in dettaglio la documentazione API di Zucchetti: Data Alchemy gestisce autenticazione, mappatura dei campi e gestione degli errori, adattandosi alla configurazione della tua installazione (cloud o on-premise). Il team tecnico definisce con te endpoint, credenziali e tabelle di staging in fase di onboarding.
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 e i permessi di scrittura verso Zucchetti.
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 connettore verso Zucchetti 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.
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, upload o cartella monitorata (Google Workspace, Microsoft 365).
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
Il record viene scritto in Zucchetti via REST API, webhook o SQL, pronto 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 in pochi secondi, 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.
Altre integrazioni e risorse
SAP
Scrittura diretta dei dati estratti in SAP via REST API, webhook e SQL.
Scopri di più →Integrazione ERPTeamSystem
Integrazione nativa con TeamSystem, dati validati sull'anagrafica.
Scopri di più →APIAPI per sviluppatori
REST API, webhook e SQL 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.
Richiedi una demo