Overview

Die DATEV online APIs nutzen das Standardverfahren OAuth 2.0 zur Autorisierung einer mobilen App eines Drittanbieters gegenüber dem DATEV-Rechenzentrum. Die DATEV Cloud Authentication Library (DCAL) ist ein Framework zur Authentifizierung des Nutzers und Autorisierung der mobilen App mit dem DATEV-Rechenzentrum. DCAL ist kompatibel mit nativen Android- und iOS-Apps. Zur Authentifizierung benötigt der Nutzer das DATEV-Authentifizierungsmedium SmartLogin.

API endpoints

Name	Beschreibung	Endpoints
<resourceServer>	Zieladresse für die anwendungsspezifischen Aufrufe von DATEVconnect online	Production environment:<br/>https://api.datev.de/ <br/><br/>Sandbox environment:<br/>https://sandbox-api.datev.de/

Download DCAL mobile

Es gibt nur eine DCAL für die Produktions- und für die Sandbox-Umgebung.

DCAL mobile	Type	Description
Download Version 2.4.3	iOS Framework	Framework für die Sandbox/Production Umgebung. Minimum iOS Version: 11.0
Download Version 2.4.3	Android Framework	Framework für die Sandbox/Production Umgebung. TargetSDK-Version: 31 CompileSDK-Version: 31

Registrierung bei DATEV für 3rd-Party Apps

Bitte bereiten Sie die folgenden Informationen für DATEV vor:

Name	Typ	Beschreibung
Name der 3rd-Party App	string	Name der Drittanbieter-App auf der Zustimmungsseite.
Anbietername	string	Firmenname des Anbieters der Drittanbieter-App.
redirect_URI	<URI>	Eine definierte URI als Zieladresse, über die die App aufgerufen werden kann.

The details for registering the App with DATEV are specified below. These must be agreed upon with DATEV and passed in during initialization of the DCAL mobile.

Name	Type	Description
client_id	string (max. 60 characters)	Die client_id ist eine einzigartige ID, die von der DATEV für die 3rd-Party App vergeben wird.
client_secret	string (max. 60 characters)	Das client_secret wird nach Abschluss des Registrierungsprozesses von der DATEV vergeben.
scope	string	Durch Leerzeichen getrennte Liste der von der Drittanbieteranwendung verwendeten Scopes.
redirect_URI	<URI>	Eine definierte URI als Zieladresse, über die die App aufgerufen werden kann.
use_Sandbox	Bool	Boolescher Wert, wenn das DCAL den Endpunkt der Sandbox-Umgebung für die Authentifizierung verwenden soll.
context *	Context	Der Android-Anwendungskontext.

**Nur bei Android Apps erforderlich*

Implementation Information - Embedding the library

iOS

Das DCAL mobil für iOS wird als XCFramework verteilt. Das DCAL XCFramework muss in das iOS-App-Projekt eingebunden werden.

Damit das DCAL bei der Anmeldung über das OAuth-Verfahren den Redirect verifizieren kann, muss die UIApplicationDelegate-Funktion handleOpenURL wie folgt erweitert werden:

//URL-Scheme in Redirect-URI
func application(application: UIApplication, handleOpenURL url:NSURL)-> Bool {
    let isDcalUrl:Bool = DCAL.handleURL(url)
    …
}

// OR //

//Universal-Linking in Redirect-URI
override func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    if(userActivity.activityType == NSUserActivityTypeBrowsingWeb) {
        let url = userActivity.webpageURL!;
        let isDcalUrl:Bool = DCAL.handleURL(url: url);
    }
    ...
}

Android

Damit das DCAL den Redirect bei der Anmeldung über das OAuth-Verfahren verifizieren kann, muss die MainActivity-Funktion onNewIntent wie folgt erweitert werden:

//URL-Scheme handled by onNewIntent in the MainActivity
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    if (intent != null) {
        if (intent.data != null) {
            DCAL.handleUrl(intent.data)
        }
    }
}

DCAL Zustände

Das DCAL mobil kann folgende Zustände annehmen:

Initialized
Uninitialized
LoggedIn
LoggedOut

DCAL API

Initialisierung DCAL

DCAL kann entweder beim Start der App oder vor der Authentifizierung des Benutzers beim DATEV-Rechenzentrum initialisiert werden.

Wir empfehlen, die Initialisierung beim Starten der App durchzuführen.

# iOS & Android #
DCAL.initialize([Parameter]) -> DCAL_State

Gibt den aktuellen Zustand des DCAL (DCAL_State) zurück. Der DCAL wird mit den Informationen aus den Parametern initialisiert.

Rückgabewerte

State	Description
initialized	DCAL ist initialisiert.
uninitialized	DCAL konnte nicht initialisiert werden, weil z.B. die Konfigurationsdatei nicht gefunden werden konnte.
initialized \|\| loggedIn	DCAL ist bereits initialisiert, und der Benutzer ist bereits mit DATEV angemeldet.
initialized \|\| loggedOut	DCAL ist bereits initialisiert, und der Benutzer ist nicht mit DATEV angemeldet.

Login

# iOS & Android #
DCAL.requestLogin()

Die Authentifizierung des Nutzers und die Autorisierung der App beim DATEV-Rechenzentrum werden in einem asynchronen Prozess angestoßen.

Wenn die Anmeldeklasse für DCAL authDelegate registriert ist, wird die Anmeldeklasse über die Delegatenmethode dcalAuthStateChanged über eine DCAL-Zustandsänderung informiert. Die Methode kann die folgenden Parameter enthalten:

Parameter	Value	Description
state	initialized \|\| loggedOut	DCAL ist bereits initialisiert, und der Benutzer ist nicht mit DATEV angemeldet.
state	initialized \|\| loggedIn	DCAL ist bereits initialisiert, und der Benutzer ist erfolgreich mit DATEV angemeldet.
state	uninitialized	DCAL ist initialisiert.
error	...	...

Beispiel für die Registrierung einer Anmeldeklasse für das DCAL authDelegate:

# iOS #
DCAL.authDelegate = self

# Android #
DCAL.authDelegate = this

Logout

DCAL.requestLogout()

Der Benutzer wird in einem asynchronen Prozess aus dem DATEV-Rechenzentrum abgemeldet. Die App ist dann nicht mehr berechtigt, Datenaustausch mit dem DATEV-Rechenzentrum zu betreiben.

Parameter	Value	Description
state	initialized \|\| loggedOut	DCAL ist bereits initialisiert, und der Benutzer ist nicht mit DATEV angemeldet.
state	initialized \|\| loggedIn	DCAL ist bereits initialisiert, und der Benutzer ist erfolgreich mit DATEV angemeldet.
state	uninitialized	DCAL ist initialisiert.
error	...	...

Beispiel für die Registrierung einer Anmeldeklasse für das DCAL authDelegate:

# iOS #
DCAL.authDelegate = self

# Android #
DCAL.authDelegate = this

Erzeugen einer URLSession unter iOS

DCAL.createSession() throws -> URLSession //new

DCAL.session() -> URLSession  //deprecated since DCAL Version 2.1.1

Diese Funktion erstellt eine URLSession mit Anpassungen, um eine sichere Kommunikation mit dem DATEV-Rechenzentrum zu ermöglichen.

Android Kommunikation (Voraussetzung: DCAL Version >= 2.0.0)

Für die Kommunikation mit DATEV-APIs passt das DCAL die native Android Volley-API (https://developer.android.com/training/volley) an.

import com.android.volley.*
...
var datevConnection: DatevConnection? = DatevConnection.getInstance(this);

// GET-Request
datevConnection.getData(url: String, header:Map? = null, successListener:Response.Listener, errorListener: Response.ErrorListener);

// POST-Request
datevConnection.postData(url: String, data: ByteArray, header:Map?, successListener:Response.Listener, errorListener: Response.ErrorListener);

Erzeugen einer URLConnection unter Android (deprecated seit DCAL Version 2.0.0)

DatevUrlConnection([Parameter]) -> DatevUrlConnection

Diese Funktion erstellt eine DatevUrlConnection mit Einstellungen, die eine sichere Kommunikation mit dem DATEV-Rechenzentrum ermöglichen.

SessionDelegate

# iOS #
DCAL.sessionDelegate = self
func dcalSession(totalBytesExpectedToSend: Int, totalBytesSent: Int, totalBytesExpectedToReceive: Int, didReceive: Int) {
...
}

# Android #
DCAL.sessionDelegate = this
override fun dcalSession(totalBytesExpectedToSend: Long, totalBytesSent: Long, totalBytesExpectedToReceive: Long, totalBytesReceived: Long) {
...
}

Informiert den Delegarten regelmäßig über den Fortschritt des Sendens/Empfangens von Inhalten zum/vom Server.

Abfragen des DCAL States

DCAL.getState() -> DCAL_State

Gibt den aktuellen DCAL-Status zurück.

Reset DCAL

DCAL.clean() -> DCAL_State

Setzt das DCAL auf den Zustand “uninitialized” zurück.

Ist SmartLogin verfügbar

Prüfen Sie, ob die SmartLogin-App auf dem Gerät verfügbar ist.

DCAL.isSmartLoginAvailable() -> Bool

Gibt einen booleschen Wert zurück, wenn die SmartLogin-App verfügbar ist.

iOS only:
Sie müssen das URL-Schema "DATEVSmartLogin" deklarieren. Fügen Sie dazu den Schlüssel LSApplicationQueriesSchemes in die Datei Info.plist Ihrer Anwendung ein. Wenn Sie diese Methode ohne das deklarierte DATEVSmartLogin-URL-Schema aufrufen, gibt diese Methode immer false zurück, unabhängig davon, ob die SmartLogin-App installiert ist oder nicht.

Changelog

Die DCAL-Bibliothek gibt es in verschiedenen Versionen. Die Änderungen in jeder Version sind hier aufgeführt.

iOS

DCAL Version	Changes	Date
2.4.3	Fehlerbehebung + iOS Min Target 14	2024-01-31
2.4.0	Support new Format for Packaging Frameworks (xcframework); Upgrade OpenSSL to 1.1.1l; including bug and security fixes	2021-11-11
2.1.2	Swift 5.1.3 Support	2020-15-01

Android

DCAL Version	Changes	Date
2.4.3	Fehlerbehebung	2024-01-31
2.4.0	Upgrade OpenSSL to 1.1.1l; including bug and security fixes	2021-11-11
2.1.1	Fixed bug where access token is not being refreshed correctly	2019-11-21

SDK für iOS & Android

Overview

API endpoints

Download DCAL mobile

Registrierung bei DATEV für 3rd-Party Apps

Implementation Information - Embedding the library

iOS

Android

DCAL Zustände

DCAL API

Initialisierung DCAL

Rückgabewerte

Login

Logout

Erzeugen einer URLSession unter iOS

Android Kommunikation (Voraussetzung: DCAL Version >= 2.0.0)

Erzeugen einer URLConnection unter Android (deprecated seit DCAL Version 2.0.0)

SessionDelegate

Abfragen des DCAL States

Reset DCAL

Ist SmartLogin verfügbar

Changelog

iOS

Android