Zucchetti API integration: invoice, delivery-note and order data written straight into your ERP
With Data Alchemy, invoices, delivery notes and orders reach Zucchetti already read by the AI and checked against your master data, with no manual data entry. Your users keep working in Zucchetti and only review the exceptions that are flagged.
What changes for the people posting invoices and delivery notes in Zucchetti
The finance team's view, without the technical detail: that comes further down, for whoever looks after the integration.
You keep working in Zucchetti
Users keep working in Zucchetti: there is no new software to learn. The automation operates behind the scenes, on document acquisition.
What reaches the ERP
From accounts-payable invoices, delivery notes and orders: vendor and VAT number, document number and date, lines with item code, quantity, unit price and VAT rate, plus net, tax and gross totals. The AI reads them with no templates or per-layout rules, so there is no model to build for each supplier.
You only review the exceptions
Before posting, data is checked against Zucchetti master data: if a vendor or an item code finds no match, the document is flagged for review instead of entering the ERP. The team moves from copying to reviewing exceptions.
How it connects to Zucchetti
The connection runs through the AI agent installed at your premises (database, files or APIs) or through an integration built on Data Alchemy's REST APIs: the technical details are further down.
Why integrate Zucchetti with an IDP engine
Zucchetti (Ad Hoc, Mago, Infinity) is one of the most widely used management systems among Italian SMEs, but the accounts-payable cycle still requires manually entering invoices, delivery notes and orders. Intelligent Document Processing (IDP) software, which reads documents with AI and extracts structured data, integrated with Zucchetti reduces manual data entry and feeds the system automatically: every document is read, extracted and written into Zucchetti without typing, eliminating the errors, delays and reconciliations that weigh on the back office.
Data Alchemy's Zucchetti integration removes that work: Intelligent Document Processing reads the document, extracts the fields, checks them against Zucchetti master data (vendors, items, terms) and writes the record straight into the system, ready to be posted.
This direct link between Data Alchemy and your system is what we mean by native integration: the full explanation, including the available connection methods, is on the dedicated page.
Supported Zucchetti integration methods
Extracted data reaches Zucchetti in one of two ways: through the AI agent, installed at your premises, or, if you develop in-house, through an integration on Data Alchemy's REST API and webhooks, included in every licence.
AI agent
The AI agent is installed at your premises: it connects to Data Alchemy over websocket and APIs and posts the extracted data into Zucchetti, including orders with header and lines, on the destination configured from a graphical interface — a database, CSV, JSON or TXT files, or APIs — with no connectors to build. Your Zucchetti credentials stay in the agent, in your perimeter. It is included in the Enterprise licence and available as a separately quoted add-on on Business.
Data Alchemy REST API and webhooks
For developers: submit documents through the REST API and receive the structured JSON via webhook, signed with HMAC SHA-256, or with a GET. Your own integration handles the write into Zucchetti.
Mail service for acquisition
From the Business licence, the Mail service installed on your premises picks up documents from your company mailboxes and brings them into Data Alchemy: invoices, delivery notes and orders enter the flow with no manual uploads.
Validation on Zucchetti master data
Before writing, data is matched against Zucchetti master data — vendors, item codes, open orders. This is done by remote validation, which checks individual values against master data (for example that an item code exists, or the vendor code found from the VAT number), and by external fields, which compare the document with the data it refers to (for example the purchase order quoted on a delivery note). Both are included from the Business licence.
From document to Zucchetti in four steps
The same flow applies to invoices, delivery notes, orders, contracts and price lists: the document goes in, structured data comes out inside Zucchetti.
Acquisition
The document arrives via email (business mailboxes, via the on-premise Mail service, from the Business licence), upload or a monitored folder.
AI extraction
An LLM dedicated to the document model extracts the fields, with no templates or per-layout rules.
Validation
Data is validated and enriched against Zucchetti master data, with anomalies flagged for review.
Write to Zucchetti
Validated data reaches Zucchetti through the AI agent installed at your premises (database, files or APIs) or through your own integration on the REST API, ready to be posted.
What changes with Data Alchemy's Zucchetti integration
Zero data entry
Data enters Zucchetti with no manual typing: the finance team moves from copying to reviewing exceptions.
Master-data consistency
Validation against Zucchetti master data reduces coding errors, wrong vendors and items not found.
Faster closing times
Payables reach Zucchetti with no manual data entry, speeding up posting, control and payment.
No new software for users
Users keep working in Zucchetti: the automation operates behind the scenes on document acquisition.
Full traceability
Every document keeps the link to the Zucchetti record it created, for audit and reconciliation.
Scales to all documents
From invoice to delivery note to order: the same Zucchetti integration covers every document flow.
Zucchetti API documentation and technical requirements
The connection with Zucchetti works in one of two ways. With the AI agent, installed at your premises, Data Alchemy writes to Zucchetti through a database, CSV, JSON or TXT files, or APIs, depending on what your installation (cloud or on-premise) supports: the agent connects to Data Alchemy over websocket and APIs, the destination is configured from a graphical interface and your Zucchetti credentials stay in the agent, in your perimeter. There is no need to build connectors or study Zucchetti's API documentation in detail; without custom integrations, integration takes 2–5 working days. If you would rather run the flow in your own stack, you use the Data Alchemy REST API and webhooks described below: you submit the document, receive the validated JSON, and your integration handles the write into Zucchetti.
Zucchetti API: endpoints, JSON payload and field mapping
The flow is the same as Data Alchemy's data extraction API: submit the document with a POST setting erp_target=zucchetti and receive structured JSON — via webhook or with a GET on /v1/documents/{id} — already validated against Zucchetti master data and ready to write into the ERP.
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 }
}
}Webhooks: write to Zucchetti without polling
Register your endpoint with a POST to /v1/webhooks and you'll receive the document.processed event as soon as extraction completes, with no interval polling. Every request is signed with HMAC SHA-256 in the X-Data-Alchemy-Signature header: verify the signature before writing the record into Zucchetti. If your endpoint is unreachable, delivery is retried with increasing backoff, so no document is lost.
Field mapping to Zucchetti master data
Fields from the extracted JSON are mapped onto their Zucchetti counterparts. Validation happens before the write: if the VAT number has no match in the vendor master data, or an item code does not exist, the document is flagged instead of creating an inconsistent record.
header.supplier.vat_numberVendor master data — VAT number (match key)header.supplier.nameVendor master data — Company nameheader.invoice_numberDocument header — Document numberheader.issue_dateDocument header — Document dateline_items[].skuDocument lines — Item code (item master data)line_items[].quantityDocument lines — Quantityline_items[].unit_priceDocument lines — Unit priceline_items[].vat_rateDocument lines — VAT ratetotals.net / totals.vat / totals.grossDocument header — Net, tax and gross totalvalidation.erp_matchValidation result: true writes the record, false sends it to reviewZucchetti API: authentication, supported formats and rate limits
Integrating Zucchetti via API always means the same Data Alchemy REST endpoint: base URL https://api.data-alchemy.ai/v1, Bearer API key authentication and UTF-8 JSON responses. The authentication flow is identical for invoices, delivery notes and orders headed for the ERP, and does not change between cloud and on-premise Zucchetti installations.
Generate the API key
The key is created from the Data Alchemy console. Keep it server-side and never let it reach the browser or a repository: it identifies your tenant.
Authenticate every request
All calls run over HTTPS and carry the Authorization: Bearer $DATA_ALCHEMY_API_KEY header. There is no OAuth flow to implement: the API key is enough to submit documents and read results.
Register the webhook
A POST to /v1/webhooks declares the endpoint that will receive the document.processed event. It is the recommended channel for writing into Zucchetti as soon as extraction is ready, with no polling.
Verify the HMAC signature
Every webhook is signed with HMAC SHA-256 in the X-Data-Alchemy-Signature header. Verify the signature with your endpoint secret before writing any record into Zucchetti.
Supported formats and document types
The POST /v1/documents endpoint accepts the file as multipart/form-data together with the document_type parameter (invoice, delivery_note, order, contract, price_list) and erp_target=zucchetti. Native and scanned PDFs, images and Italian FatturaPA XML e-invoices are supported. The acceptance response is a 202 with the document id; the structured JSON is retrieved with a GET on /v1/documents/{id} or delivered straight to your webhook, already validated against Zucchetti master data.
Status codes and error handling
The API uses standard HTTP status codes and always returns JSON with error.code and error.message. Handling these cases on the integration side stops an unreadable document or an expired key from turning into an inconsistent record inside Zucchetti.
202Document accepted and processing.200Result available and ready for Zucchetti.401API key missing, expired or invalid.422Unreadable document or unsupported type.429Rate limit exceeded: retry with exponential backoff.On a 429 or any 5xx error, retry with exponential backoff rather than hammering at a fixed interval. Undelivered webhooks are retried automatically with increasing backoff: if your endpoint stays unreachable for a few minutes, no document.processed event is lost. Documents that fail master-data validation are not written into the ERP but sent to review, with the detail of the field that found no match.
Other integrations and resources
SAP
Extracted data written directly into SAP through the AI agent or REST API.
Learn more →ERP integrationTeamSystem
Native TeamSystem integration, data validated on master data.
Learn more →APIDeveloper API
REST API and webhooks to integrate IDP into your stack, including Zucchetti.
Learn more →Frequently asked questions about Zucchetti integration
Get your documents into Zucchetti, without data entry
Show us a sample of your documents: we'll demonstrate extraction, master-data validation and the write to Zucchetti on your real case.
Plan a call with a demo on your own documents