Schnittstellenvorgaben für Belegbilderservice ESt

Mit dem DATEV Belegbilderservice Steuern können Sie digitale Belegbilder nach DATEV Meine Steuern übertragen. Nachfolgend wird der API Workflow für die API my-tax:income-tax-documents aufgezeigt.
 

API WORKFLOW

1. Prüfung der Berechtigungen für den Datenservice
2. Abfrage der Metadaten (z.B. Steuerjahre, Ordner) und ggf. Anlage eines Steuerjahres für DATEV Meine Steuern
3. Übertragung einzelner Dateien/Dokumente - manuell (per Klick über 3rd-Party App) oder automatisiert (regelbasiert)
4. (wiederkehrend) Überprüfung der Berechtigungen & Metadaten unmittelbar vor einer Übertragung

MUST: Übermittelte Dokumente (PUT/POST) und lesende API-Requests (GET) sollten in einem gesunden Verhältnis sein. Auf ein  erfolgreich übermitteltes Dokument weitere 30 GET-Requests zu produzieren, zeugt nicht von einer effizienten Integration.

ONLINE API & ENDPUNKTE für SANDBOX & PRODUKTION

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

Berechtigungen prüfen

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

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

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen hat. Die 3rd-Party App kann dabei für sich selbst festlegen, welche der beiden Endpunkte sie nutzt. Wird der erste Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. Dies kann insbesondere bei größeren Kanzleien zu hunderten oder gar tausenden von Datenwerten führen. Daher kann es auch sinnvoll sein nur den zweiten Endpunkt zu nutzen. Hier muss dann der Kunde aber eine Eingabemöglichkeit in der 3rd-Party-App für die Berater- und Mandantennummer bekommen.

MUST: Ein der beiden Endpunkte zur Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Wird der erste Endpunkt genutzt, erwarten wir eine blätterbare Anzeige (Paging) der verfügbaren Mandantenbestände. Weiterhin muss dem Kunden der Unternehmensname und die Berater- & Mandantennummer angezeigt werden. Bei Verwendung des zweiten Endpunkts ist aufzuzeigen, wo der Kunde seine Angaben für den Datenbestand macht.

Wichtiger Hinweis: Das Erhalten des Langzeittokens für eine {client-id} bedeutet noch nicht, dass der Kunde tatsächlich Berechtigungen für die {client-id} besitzt. D.h. die 3rd-Party App holt sich das Token und spricht danach unmittelbar die GET Clients damit an. Die Authentifizierung ist erst dann dem Kunden als erfolgreich verbunden anzuzeigen, wenn der GET Clients die korrekte Rechtevergabe bestätigt hat.

Challenges:

• Berater erteilt ein Token mit Zugriff auf einen Testbestand mit mehreren hundert Testbeständen
• Berater trägt eine ungültige Berater-, Mandanten- und Basisnummer ein

Metadaten holen & ggf. anlegen

Steuerjahr(e) abfragen

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

Nutzen Sie diesen Endpunkt, um die verfügbaren Steuerjahre aus dem Mandantenbestand abzufragen. Noch nicht existierende Steuerjahre können per Endpunkt angelegt werden (siehe unten). Das Verwenden nicht angelegter Steuerjahre führt bei der Übermittlung zu einem 400er-Fehler.

MUST: Der Endpunkt ist zu nutzen und die Informationen sind dem Kunden transparent anzuzeigen. Versichern Sie sich vor jeder Datenübertragung, dass die Steuerjahre unverändert bestehen. Ein einmaliges Abfragen am Tag der Datenübertragung ist ausreichend.
MUST: Zeigen Sie im Review auf, wie die Überleitung zwischen den Steuerjahren aus Ihrer App und DATEV Meine Steuern erfolgt.
DONT: Vor jeder einzelnen Übertragung eines Dokuments die verfügbaren Steuerjahre prüfen.

Ordner abfragen

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

Nutzen Sie diesen Endpunkt, um die verfügbaren Ordner aus dem Mandantenbestand abzufragen. Das Verwenden nicht angelegter Ordner führt bei der Übermittlung zu einem 400er-Fehler.

MUST: Der Endpunkt ist zu nutzen und die Informationen sind dem Kunden transparent anzuzeigen. Versichern Sie sich vor jeder Datenübertragung, dass die Steuerjahre unverändert bestehen. Ein einmaliges Abfragen am Tag der Datenübertragung ist ausreichend.
MUST: Zeigen Sie im Review auf, wie die Überleitung zwischen den Ordnern aus Ihrer App und DATEV Meine Steuern erfolgt.
DONT: Vor jeder einzelnen Übertragung eines Dokuments die verfügbaren Ordner prüfen.

Steuerjahr anlegen

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

Dieser Endpunkt dient der Neuanlage eines Steuerjahres. Bereits existierende Steuerjahre oder ungültige Eingaben führen zu einem 400er-Fehler. Steuerjahre können nur einmalig angelegt werden. Bereits existierende Steuerjahre können nicht mehr gelöscht werden.

SHOULD: Die Umsetzung des Endpunkts wird empfohlen. Neue Steuerjahre sollten bei Bedarf automatisiert angelegt werden können.

Dokument(e) übertragen

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

Dieser Endpunkt dient der einzelnen Übermittlung eines Dokuments. Für jedes Dokument ist zusätzlich ein Metadaten-Objekt (JSON) Namens "metadata" zu übermitteln.

MUST: Zeigen Sie eine erfolgreiche Übertragung von mindestens zwei Dokumenten mit jeweils unterschiedlichem Dateiformat. Senden Sie die Dokumente an unterschiedliche Ordner
MUST: Das Dokument muss mit einer gut lesbaren Qualität in DATEV Meine Steuern ankommen. Die Kunden erwarten gut lesbare Dokumente, die gleichzeitig ein geringes Speichervolumen aufweisen. Höhere Speichervolumen verursachen nicht nur Kosten bei DATEV, sondern vor allem auch (Lade-)Zeit beim Aufruf der Dokumente über die DATEV Apps. Zeigen Sie auf, welche Komprimierungsverfahren für Dokumente in Ihrer 3rd-Party App angewendet werden. Weitere Informationen und Empfehlung finden Sie im DATEV Hilfe-Center Dokument Nr. 1034754, [Tipps zur Digitalisierung der Belege per Scanner](https://apps.datev.de/help-center/documents/1034754).

CHANGELOG