Schnittstellenvorgaben für Belegbilderservice Steuern

With the DATEV Belegbilderservice Steuern you can transfer digital documents images to DATEV Meine Steuern. The workflow for the API my-tax:income-tax-documents is shown below.
 

API WORKFLOW

1. Check the permissions for the data service
2. Query of metadata (e.g. tax years, folders) and if necessary creation of a tax year for DATEV Meine Steuern
3. Transfer of individual files/documents - manually (per click via 3rd party app) or automated (rule-based)
4. (recurring) verification of permissions & metadata immediately before a transfer

MUST: Transmitted documents (PUT/POST) and read API requests (GET) should be in a healthy ratio. Producing another 30 GET requests on top of one successfully submitted document does not demonstrate efficient integration.

ONLINE API & END POINTS for SANDBOX & PRODUCTION

Base URLs:
Sandbox: https://mytax-income-tax-documents.api.datev.de/platform-sandbox
Production: https://mytax-income-tax-documents.api.datev.de/platform

Check permissions

GET https://mytax-income-tax-documents.../clients

GET https://mytax-income-tax-documents.../clients/{client-id}

Here you can query the datasets to which the client has the necessary permissions. The 3rd party app can thereby determine for itself which of the two endpoints it uses. If the first endpoint is used, the API returns all available datasets. This can lead to hundreds or even thousands of data values, especially for larger law firms. Therefore, it may also make sense to use only the second endpoint. Here, however, the customer must then be given an input option in the 3rd party app for the consultant and client number.

MUST: One of the two endpoints for querying permissions for a dataset must be used. If the first endpoint is used, we expect a scrollable display (paging) of the available client holdings. Furthermore, the client must be shown the company name and the consultant & client number. If the second endpoint is used, it must be shown where the customer makes his specifications for the data stock.

Important note: Getting the long term token for a {client-id} does not mean that the customer actually has permissions for the {client-id}. That is, the 3rd party app gets the token and then immediately addresses the GET clients with it. Authentication is not to be indicated to the client as successfully connected until the GET Clients has confirmed the correct assignment of permissions.

Challenges:

• Consultant issues a token with access to a test set of several hundred test sets
• Consultant enters an invalid consultant, client and base number

Get metadata & create if necessary

Get tax year(s)

GET https://mytax-income-tax-documents.../clients/{client-id}/tax-years

Use this endpoint to retrieve the available tax years from the client database. Tax years that do not yet exist can be created via endpoint (see below). Using tax years that have not been created will result in a 400 error on submission.

MUST: The endpoint must be used and the information must be transparently displayed to the customer. Ensure tax years are unchanged prior to any data transmission. A one-time query on the day of the data transfer is sufficient.
MUST: Show in the review how the transition between the tax years from your app and DATEV Meine Steuern is done.
DONT: Check the available tax years before every single transfer of a document.

Query folder

GET https://mytax-income-tax-documents.../clients/{client-id}/tax-years/{tax-year}/folders

Use this endpoint to retrieve the available folders from the client set. Using uncreated folders will result in a 400 error on submission.

MUST: The endpoint must be used and the information must be transparently displayed to the client. Ensure tax years are unchanged prior to any data transmission. A one-time query on the day of the data transfer is sufficient.
MUST: Show in the review how the transition between the folders from your app and DATEV Meine Steuern takes place.
DONT: Check the available folders before every single transfer of a document.

Create tax year

POST https://mytax-income-tax-documents.../clients/{client-id}/tax-years

This endpoint is used to create a new tax year Existing tax years or invalid entries will result in a 400 error. Tax years can only be created once. Existing tax years cannot be deleted.

SHOULD: Implementation is recommendet. New tax years should be created automatically if required.

Transfer document(s)

POST https://mytax-income-tax-documents.../clients/{client-id}/tax-years/{tax-year}/folders/documents

This endpoint is used for the single transmission of a document. For each document, a metadata object (JSON) named "metadata" must also be submitted.

MUST: Show a successful submission of at least two documents, each with a different file format. Send the documents to different folders
MUST: The document must arrive in DATEV Meine Steuern with a good readable quality. Customers expect documents that are easy to read and at the same time have a low storage volume. Higher storage volumes not only cause costs at DATEV, but above all also (loading) time when calling up the documents via the DATEV apps. Show which compression methods are used for documents in your 3rd party app. For more information and recommendation, see DATEV Help Center Document No. 1034754, [Tips for digitizing documents via scanner](https://apps.datev.de/help-center/documents/1034754).

CHANGELOG