Interface requirements | DATEV Developer Portal

Every new Online API integration of a 3rd party app has to go through a approval process together with DATEV. The interface requirements include all requirements on the part of DATEV for the integration by the API consumer.

With this we want to ensure that:

our DATEV customers can expect a certain minimum integration quality for all 3rd party apps
the infrastructure for the DATEV API gateway is used responsibly
the lowest possible support & service burden is ensured for all parties involved (software companies, customer, DATEV member, DATEV)
the software companies already get a first orientation based on best practices

Within the interface requirements, we work with the following evaluation scale for the relevance of a requirement:

MUST: These requirements are mandatory to implement in order to release the integration.

SHOULD: DATEV recommends these items based on experience/best practices/customer expectations. This requirement is not mandatory to implement for a successful release, but should definitely be considered for implementation.

DONT: These items are to be avoided at all costs and will jeopardize a successful release of the integration.

Each software companies has the:

General interface requirements for handling the DATEV API gateway as well as
Special interface requirements of the respective DATEV data service in conjunction with the online APIs must be observed.

REQUIREMENTS & PREPARATION

Each release of an integration includes at least two common release dates. Before an API consumer goes into the release dates, they should consider certain prerequisites and make preparations.

Step 1: Sandbox release

API integration implemented & tested on sandbox
General & Specific interface requirements followed
Posting a release date

If the release appointment is positive, the API consumer will receive access to the production environment for the next 3 months.

Step 2: Production release

API integration implemented & tested on production
Integration tested in interaction with your DATEV test system (inclusion of first customers is recommended)
General & Specific interface requirements observed
Possibly existing file formats (CSV, XML, etc.) of the API integration are accepted (appointment booking)
Preparation of test clients with test data (invoices, data, documents, etc.) for the apps involved.
Important: No real clients or real data may be used as part of the technical review!
Book a release appointment

When the integration is released into production, the time limit on access is removed and the API consumer can put their integration into production with all of their customers.

RELEASE PROCEDURE

Integration release meetings are held via a joint video conference. The software companies presents its screen and shows the DATEV consultant the new interface in its app. The consultant moderates the video conference and guides the software companies through the appointment. Along the appointment, the consultant asks various questions and challenges to prove compliance with the interface requirements. In parallel, the consultant checks the log records generated in the DATEV API gateway for compliance. In the production release, the successful data exchange with the DATEV apps is also checked.

GENERAL INTERFACE REQUIREMENTS

We have certain requirements for the use of our DATEV API gateway and the online APIs behind it, which are intended to serve the purpose explained at the beginning.

Economy & Ecology

Every communication via our DATEV API gateway consumes resources (power, infrastructure, etc.). The use of our gateway is currently free of charge for API consumers (software companies). Nevertheless, we attach importance to a mindful, proportionate use of our API gateway. Integrations that send blanket API calls 24/7 (around the clock) without concrete customer interest are generally not permitted. Set up your DATEV interface in such a way that only those API calls are made that the customer has requested directly beforehand (e.g. manually by click or rule-based). Exceptions to this can be discussed individually during the release meetings.

DONT: Integration of 24/7 (round-the-clock) polling.

Support

We distinguish here in support, which is provided by the API Consumer towards the API User and the support, which is provided on the part of DATEV towards the API Consumer.

The API Consumer must offer its API Users first level support for its DATEV interfaces. DATEV expects the software companies to deal with the reported problems of its API Users and to enter into an analysis. If the analysis shows that no immediate remedy is possible by the API Consumer itself, then the API User is to be presented with targeted self-help media from DATEV (e.g. general from DATEV Help Center or for initial setup of DATEV data services).

In order to avoid support cases at the API User in the first place, we expect a solid error management in the 3rd party app. For all error codes in the HTTP 4XX range, DATEV also provides a standardized error message in the response body with URLs for error handling. At best, these URLs directly solve the API user's problem or at least show him who the right contact person is (3rd-party app/DATEV/DATEV member). Which HTTP codes an API throws everything can be seen via the API documentation.

The API consumer can open a ticket at DATEV in case of technical problems with the DATEV API gateway: https://www.terminland.de/datev_schnittstellenberatung/online/ticket (30min)

Furthermore, for complex questions or for joint error analysis, consultants can be booked at any time via video conference: https://www.terminland.de/datev_schnittstellenberatung/ (60min)

MUST: 4XX error codes are to be handled. At a minimum, the help URL must be displayed in the UI or other help must be provided. We realize that solid error management does not happen in a day. We would like to see some baseline and expect continuous improvement of the error management after release.

MUST: The API Consumer uses the ticket system of DATEV for its support needs and complies with its obligations to cooperate.

DONT: Direct referrals to DATEV or the DATEV members in case of problems with the integration. Should a software companies here several times to DATEV conspicuous, the release is reviewed.

Technical log

In order to provide the best possible support in case of problems during implementation or live operation, the API consumer must integrate a technical log for HTTP requests & responses. If unexpected errors or questions occur for an HTTP request, then these logs are required for opening a ticket and further analysis at DATEV. The logs for HTTP error codes (4XXer/5XXer) must be kept for at least 14 days by the API consumer. The log must record at least the following values:

HTTP-REQUEST

Timestamp (min. hh:mm:ss)
HTTP verb/method + full URL/addressed endpoint (e.g. GET https://<domain+path>/clients)
HTTP header (without Authorization header!)
HTTP-Body incl. Payload (file does not need to be logged extra but must be available if needed)

HTTP-RESPONSE

HTTP code + message
HTTP body, if available

MUST: The API consumer must implement a technical log. HTTP error codes (4XXer/5XXer) must be kept for at least 14 days

Authentication & Authorization

We have implemented an OAuth 2.0 & OpenID connect for our DATEV data services. Via the app registration in the DATEV Developer Portal, you have to choose between the hybrid or authorization code flow. On the customer side, both flows run identically, but the code flow is easier in terms of technical integration (e.g. better support from frameworks, SDKs, etc.). It is therefore recommended to implement the code flow. The durability of the tokens does not differ between the flows. The Access token (AT) has a default lifetime of 15 minutes. For the refresh token (RT), we support two variants:

Short-term RT:
- lifetime of 11 hours
- No extension of lifetime for token refresh
- Unlimited number of token refreshes per RT
- Always only 1 valid AT per RT, i.e. token refresh invalidates last AT & RT
- Access to all datasets released for DATEV identity

Long-term RT:
- lifetime of 2 years
- Extend lifetime on token refresh to 2 years again
- Unlimited number of token refreshes per RT
- Always only 1 valid AT per RT, i.e. token refresh invalidates last AT & RT
- Access to one dataset that is released for the DATEV identity

Depending on which refresh token is supported on the part of the API consumer, different expectations must also be met.

In general, we expect a consistent separation between connection establishment and data exchange in the user interface of the 3rd party app. The user interface for the connection must meet the following requirements

MUST: Authentication process is started via a button (e.g. "Connect to DATEV")
MUST: Connection status of the RT is quickly visible (green/red traffic light, connected/disconnected, connection active/inactive)
MUST: RT can be deleted via a button (e.g. "Disconnect"), i.e. deletion in the 3rd party app and /revoke call to DATEV
MUST: calculated expiration date of the RT (min. format DD.MM.YYYY HH:MM) is visible
MUST: Person (full name) who issued the token is visible (via user info endpoint)
MUST: DATEV app "Verbundene Anwendungen" (https://apps.datev.de/tokrevui) linked

The following requirements are placed on the handling of the token itself

SHORT TERM - REFRESH TOKEN

MUST: Token revoke from RT on logout in the 3rd party app.
MUST: There must never be more than one valid RT issued with DATEV.

SHOULD: Token revoke (AT) immediately after data exchange.

LONG TIME - REFRESH TOKEN

MUST: Display in the connection status for which file name/database (= parameter {client-id}) the connection applies
MUST: Additional check routine for establishing the connection. A successful connection may only be displayed here if the online API has confirmed the access rights to the folder term/database. A GET /clients/{client-id} is usually offered for each API for this purpose.
MUST: There must never be more than one valid RT per dataset issued by DATEV.

SHOULD: Token Revoke (AT) immediately after data exchange.

Security

We have implemented common web standards (OAuth 2.0 & OIDC incl. PKCE) for authentication and authorization in our API gateway. These standards offer various security mechanisms that must be used by the software companies. There are various public SDKs/libraries for these web standards (e.g. https://openid.net/developers/libraries/) for pretty much all programming languages. Use this option, as in-house development is otherwise very time-consuming and may not meet all security aspects.

MUST: The security mechanisms provided must be used (e.g. parameters such as code_challenge, code_verifier and nonce must be regenerated/recalculated for each request

Sensitive data

Communication with the DATEV datacenter requires various authentication and authorization processes. Treat the data exchanged here as strictly confidential. This involves:

Client ID for the API client (low protection requirement, as readable in URL for web service communication)
Client-Secret for the API Client (high protection requirement)
Access-& Refresh-Token (highest protection requirement)

MUST: Data with higher protection needs must always be encrypted based on current techniques.

DONT: Data with higher protection needs must not be displayed or logged with in the API user's UI at any time

Access scopes

Each online API can have one or more scopes. A scope maps a specific use case of an API, which is relevant to the API user from the perspective of the API provider (DATEV). For example, if an API includes read and write use cases, then an API User may well want an API Consumer to transfer data to DATEV for him, but not to perform any read accesses to his data in the DATEV datacenter. The API user is shown the technical scopes requested by the 3rd party app in a translated form (description of the use case incl. read/write verb) in the Consent page. However, the API user cannot reject individual scopes here. He can only agree or disagree to the sum of the requested scopes.

MUST: When fetching tokens, only those scopes may be requested which the end user needs to use the data service. If an API consumer has implemented multiple data services, all scopes for all data services must not be requested across the board.

Rights & roles concept

In DATEV, inventory-related APIs are addressed via the URL parameter ".../{client-id}/...". A {client-id} (e.g. 123456-12345-123) can represent different entities (e.g. a mandate of a tax advisor, an employee of a mandate, etc.) and is only one-to-one for the respective API. For example, the {client-id} "123-456" for an accounting API is not necessarily the same entity as {client-id} "123-456" for a human resources API (but it could be). The {client-id} is also the basis for our APIs to check if the API user who issued the token has all the necessary permissions to use the API and the addressed entity.

The 3rd party app usually has its own entities and an underlying rights & roles concept. It is the responsibility of the API consumer to ensure that it clearly keys its entities to the DATEV entities and stores the issued tokens carefully accordingly. Particularly when using the long-term token (2 years), care must be taken to ensure that once tokens have been issued, they cannot necessarily be used by every user of the entity (in the 3rd party app). Especially for highly sensitive APIs like access to salary data, the 3rd party app itself should introduce a new role/authorization for such access.

MUST: In the release appointments, it must be outlined how the entities interact with the DATEV entities and how the handling of the tokens is regulated.

Design

In principle, all regulations from the terms of use of the DATEV Developer Portal and additionally the regulations from the interface contracts apply to the use of DATEV logos/wordmarks. The provisions located here are partly additional but also partly redundant (and already contained in the above agreements).

The word mark must always be displayed in capital letters in the 3rd party app. The terms of the DATEV data services are to be used vis-à-vis the API users (no online APIs). Which DATEV data services are available must be made clear to the API user in the 3rd party app. Depending on which DATEV data services are implemented in the 3rd party app, the names of the corresponding data services must also be correctly reproduced. The correct spelling can be determined via our overview of released DATEV data services: DATEV Data Services.

Depending on the form in which a software company cooperates with DATEV, different logos are accessible. Any use of DATEV logos must be contractually agreed with DATEV.

MUST: The specifications for word mark and logos must be complied with.

Architecture

The API client generated via the DATEV Developer Portal can be used in various forms to communicate with the DATEV API Gateway. However, not just any API user can generate a productive API client. Joint release dates with DATEV would always be required here. Therefore, the API consumer must come up with a concept of how to make the API client securely(!) accessible to all of its API users. If an unusual usage by an API client is detected at the gateway, at least the API client will be blocked for further communication with the DATEV API gateway.

Webserver integration:
The API consumer runs a web server itself (or uses a service provider) with the app and the integrated API client. All communication with the DATEV API Gateway is controlled via this central web server. The API consumer usually only needs a redirect URL (HTTPS) for the OAuth flow. The parameter "state" from the authorization call can be used to identify the API user and assign a redirect from DATEV to the correct customer. The data exchange is also done centrally via the IP of the web server.

Hybrid integration (web server + desktop/mobile):
The API consumer runs a web server itself (or has it run) with an app and the integrated API client. The communication for the tokens runs centrally via this web server. The API consumer usually only needs a redirect URL (HTTPS) for the OAuth flow. The web server in turn has a secure communication link to the individual API users with a desktop/mobile app. The data exchange takes place either centrally via the IP of the web server or via the IP of the desktop/mobile app.

Desktop/Mobile Integration:
The API consumer delivers the app to its customers (app stores, download, DVD, etc.). Any communication with the DATEV API gateway is done from the hardware and IP where the customer is running the app.

MUST: For release dates, outline the architecture chosen. Address all involved components that communicate with the DATEV API Gateway.

SPECIFIC INTERFACE REQUIREMENTS

Our online APIs can be used for various DATEV data services. A DATEV data service can include the integration of one or more online APIs. Our interface requirements for an online API depend on the particular DATEV data service in which they are used.

Accounting data services

Belegbilderservice

With the DATEV Belegbilderservice Rechnungswesen you can transfer digital documents to DATEV Unternehmen online.

Interface requirements

Related online APIs:

accounting:documents
accounting:clients (optional)

Buchungsdatenservice

With the DATEV Buchungsdatenservice you can transfer structured master and transaction data (CSV) including digital voucher image linking to DATEV Accounting. For this data service, the interface requirements for the data service and file format must be observed.

Interface requirements data service

Interface requirements DATEV-Format

Related online APIs:

accounting:extf-files
accounting:documents
accounting:clients

Rechnungsdatenservice 1.0

With the DATEV Rechnungsdatenservice 1.0 you can transfer digital documents including structured data (XML) to DATEV Unternehmen online. For this data service, the interface requirements for the data service and file format must be observed

Interface requirements data service

Interface requirements DXSO-Format

Related online APIs:

accounting:dxso-jobs

Payroll data services

Lohnimportdatenservice

The Lohnimportdatenservice primarily supports the division of labor process between law firm and client when transferring transaction data and master data from a 3rd party app. For this data service, the interface requirements for the data service and file format must be observed

Interface requirements data service

Interface requirements ASCII-Format

Related online APIs:

hr:import

Lohnauswertungsdatenservice

With the DATEV Lohnauswertungsdatenservice you can retrieve provided wage evaluations as PDF.

Interface requirements

Related online APIs:

hr:payrollreports

Lohnergebnisdatenservice

With the DATEV Lohnergebnisdatenservice, relevant salary result data can be retrieved from the DATEV payroll products.

Interface requirements

Related online APIs:

hr:exports

Lohnaustauschdatenservice (eAU)

With the DATEV Lohnaustauschdatenservice (eAU), electronic certificates of incapacity for work can be retrieved from the responsible health insurance fund.

Interface requirements

Related online APIs:

hr:eau

Tax data services

Belegbilderservice ESt

With the DATEV Belegbilderservice ESt you can transfer documents to the DATEV Meine Steuern app.

Interface requirements

Associated online APIs:

my-tax:income-tax-documents

Login mit DATEV

"Login mit DATEV" allows to register and log in with their usual access medium such as SmartCard, SmartLogin or DATEV Kommserver. The user logs in to DATEV and agrees that their profile information may be used on the vendor's website. In addition, the user can transfer data released for him in the DATEV ecosystem, such as e-mail address or name, to the vendor's website for use.

Interface requirements

Related online APIs:

Userinfo Endpoint