DATEV and Cleo integration

What moves between them

The flow runs from Cleo into DATEV. Trading partners send supplier invoices as X12 810 EDI, which Cleo receives and stores as files in a mailbox folder. ml-connector polls that folder, downloads each new invoice file, parses the 810 into header and line amounts, and submits it to DATEV as a DXSO XML booking suggestion mapped to the matching account numbers and cost centers, then polls the DATEV job until it completes. The original invoice file, whether a PDF or an XML e-invoice, is uploaded to DATEV Unternehmen Online against the incoming-invoice document type. The direction is one way: Cleo is the transport for partner documents and DATEV bookings cannot be read back, so ml-connector never writes financial entries back into Cleo.

How ml-connector handles it

ml-connector stores both credential sets encrypted. For Cleo it sends the password grant once to the tenant host, holds the opaque bearer token, and re-authenticates on a 401 using the refresh token before falling back to username and password. For DATEV it runs the interactive PKCE login with the tax advisor, refreshes the 900-second token automatically using the client_id alone, and looks up the DATEV client ID before any submission. Because Cleo exposes no invoice objects, it walks the folder children endpoint and downloads each raw 810 file, paging through the HATEOAS links, then parses the EDI into the DXSO XML layout: supplier, document number, gross and net amounts, tax code, and cost center, with account numbers and cost centers mapped first because DATEV's chart of accounts cannot be read back and must be configured in advance. Submitted DXSO XML must validate against the DATEV XSD, and any uploaded document file is sent UTF-8 NFC normalized with a whitelisted filename so DATEV does not reject it; a deterministic filename keeps a retry safe since DATEV rejects a duplicate filename and document-type pair. Neither side pushes events, so ml-connector polls Cleo for new files and polls the DATEV job endpoint with backoff until it posts or fails. Cleo returns HTTP 429 above roughly five requests per second per path, so reads are throttled and retried. Every record carries a full audit trail and can be replayed if a call fails.

A real-world example

A German wholesale distributor with around 120 employees keeps its books in DATEV through its Steuerberater and exchanges EDI with its larger retail customers and suppliers through Cleo Integration Cloud. Before the integration, a clerk opened the Cleo portal each day, downloaded the supplier invoice files partners had sent as X12 810, and typed each one into DATEV by hand, matching every line to the right SKR account and Kostenstelle, then filed the source document separately in DATEV Unternehmen Online. With DATEV and Cleo connected, each inbound 810 invoice is parsed and submitted to DATEV as a booking suggestion automatically, allocated to the correct accounts and cost centers, and the source file is uploaded alongside it. The daily re-keying step is gone and the tax advisor reviews ready-made suggestions instead of raw EDI.

What you can do

• •Poll Cleo folders for inbound X12 810 supplier invoices and download each new EDI file as it arrives.
• •Submit parsed invoices to DATEV as DXSO XML booking suggestions, then poll the job until it posts.
• •Upload the source invoice file to DATEV Unternehmen Online against the correct incoming-invoice document type.
• •Map EDI supplier and amount fields to DATEV account numbers and cost centers configured in advance.
• •Bridge Cleo's tenant password-grant token with DATEV interactive PKCE login and automatic token refresh, with retries and a full audit trail on every record.

Questions

Which direction does data move between DATEV and Cleo?

The flow is Cleo into DATEV. Inbound supplier invoices that partners send as X12 810 EDI are pulled from Cleo folders, parsed, and submitted to DATEV as booking suggestions, with the source file uploaded to DATEV Unternehmen Online. DATEV bookings cannot be read back over the API, so ml-connector does not write financial entries back into Cleo.

Cleo has no invoice objects, so how does the integration get invoices out of it?

Cleo is an EDI and file transfer platform, so an invoice is a raw X12 810 file sitting in a mailbox folder rather than a structured record. ml-connector walks the Cleo folder children endpoint, downloads each new 810 file, and parses the EDI into the fields DATEV needs. The business data lives in the file payload, and ml-connector does the mapping that Cleo itself does not.

How does the integration handle the two different file-based APIs and DATEV's short token?

Neither system pushes events, so ml-connector polls Cleo for new files and polls the DATEV job endpoint until it posts or fails. DATEV access tokens last only 900 seconds, so they are refreshed automatically using the client_id alone after the one-time tax advisor login. Because DATEV does not expose its chart of accounts, the SKR account numbers and cost centers are configured in advance and the EDI values are mapped to them so every booking line references a valid account.