Overview

The DATEV online APIs uses the standard procedure OAuth 2.0 to authorize a third-party mobile app with the DATEV data center. The DATEV Cloud Authentication Library (DCAL) is a framework for authenticating the user and authorizing the mobile app with the DATEV data center. DCAL is compatible with native Android and iOS apps. For authentication purposes, the user requires the DATEV authentication medium SmartLogin.

API endpoints

Name	Description	Endpoints
<resourceServer>	Destination address for the application-specific calls of DATEVconnect online	Production environment:<br/>https://api.datev.de/ <br/><br/>Sandbox environment:<br/>https://sandbox-api.datev.de/

Download DCAL mobile

There is only one DCAL for the production and for the sandbox environment.

DCAL mobile	Type	Description
Download Version 2.4.4	iOS Framework	Framework for the sandbox/production environment. Minimum iOS Version: 11.0
Download Version 2.4.4	Android Framework	Framework for the sandbox/production environment. TargetSDK-Version: 31 CompileSDK-Version: 31

Registration of a third-party App

Please prepare the following information for DATEV:

Name	Type	Description
third-party app name	string	Name of the third-party app in the consent page.
vendor name	string	Company name of the provider of the third-party app.
redirect_URI	<URI>	A defined URI as destination address is necessary, that is used to call up the app.

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)	The client_id is a unique ID assigned by DATEV for the third party app.
client_secret	string (max. 60 characters)	The client_secret is a unique ID assigned by DATEV for the third party app.
scope	string	Blank separated List of Scopes used by the third party app.
redirect_URI	<URI>	URI used by the SmartLogin App to call up the app.
use_Sandbox	Bool	Boolean if the DCAL should use the Sandbox environment endpoint for authentication.
context *	Context	The Android-Application Context

**Only necessary for an Android application*

Implementation Information - Embedding the library

iOS

The DCAL mobil for iOS is distributed as a XCFramework. The DCAL XCFramework must be embedded in the iOS app project.

To enable the DCAL to verify the redirect when logging in using the OAuth procedure, the UIApplicationDelegate function handleOpenURL must be extended as follows:

//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

To enable the DCAL to verify the redirect when logging in using the OAuth procedure, the MainActivity function onNewIntent must be extended as follows:

//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 States

DCAL can be in the following states:

Initialized
Uninitialized
LoggedIn
LoggedOut

DCAL API

Initialize DCAL

DCAL can either be initialized when starting the app or prior to the authentication of the user with the DATEV data center.

We recommend that initialization is performed when starting the app.

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

Returns the current state of the DCAL (DCAL_State). The DCAL is initialized using the information from the parameters.

Return values

State	Description
initialized	DCAL is initialized.
uninitialized	DCAL could not be initialized because, for example, the configuration file could not be found.
initialized \|\| loggedIn	DCAL is already initialized, and the user is already logged in with DATEV.
initialized \|\| loggedOut	DCAL is already initialized, and the user is not logged in with DATEV.

Login

# iOS & Android #
DCAL.requestLogin()

The authentication of the user and the authorization of the app with the DATEV data center are initiated in an asynchronous process.

When the log-in class is registered for DCAL authDelegate, then the log-in class will be informed of a DCAL state change via the delegate method dcalAuthStateChanged. The method may contain the following parameters:

Parameter	Value	Description
state	initialized \|\| loggedOut	DCAL is initialized, and the user is not logged in with DATEV.
state	initialized \|\| loggedIn	DCAL is initialized, and the user is successfully logged in with DATEV.
state	uninitialized	DCAL is not initialized.
error	...	...

Example of registering a log-in class for the DCAL authDelegate:

# iOS #
DCAL.authDelegate = self

# Android #
DCAL.authDelegate = this

Log-out user

DCAL.requestLogout()

The user is logged out of the DATEV data center in an asynchronous process. Therefore, the app is not authorized to conduct data interchange with the DATEV data center.

When the log-in class is registered for DCAL authDelegate, then the log-in class will be informed of a DCAL state change via the delegate method dcalAuthStateChanged.

The method may contain the following parameters:

Parameter	Value	Description
state	initialized \|\| loggedOut	DCAL is initialized, and the user is not logged in with DATEV.
state	initialized \|\| loggedIn	DCAL is initialized, and the user is successfully logged in with DATEV.
state	uninitialized	DCAL is not initialized.
error	...	...

Example of registering a log-in class for the DCAL authDelegate:

# iOS #
DCAL.authDelegate = self

# Android #
DCAL.authDelegate = this

Create a URLSession in iOS

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

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

This function creates a URLSession with adjustments to enable secure communication with the DATEV data center.

Android networking (reqires DCAL Version >= 2.0.0)

For networking with DATEV APIs the DCAL is customizing the nativ Android Volley-API (https://developer.android.com/training/volley).

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);

Create a URLConnection in Android (deprecated since DCAL Version 2.0.0)

DatevUrlConnection([Parameter]) -> DatevUrlConnection

This function creates a DatevUrlConnection with adjustments to enable secure communication with the DATEV data center.

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) {
...
}

Periodically informs the delegate of the progress of sending/receiving content to/from the server.

Get the DCAL state

DCAL.getState() -> DCAL_State

Returns the current DCAL state.

Reset DCAL

DCAL.clean() -> DCAL_State

Resets the DCAL to the state “uninitialized”.

Is SmartLogin available

Check if the SmartLogin App is available on the device.

DCAL.isSmartLoginAvailable() -> Bool

Returns a Boolean if the SmartLogin app is available

** iOS only: You must declare the URL scheme 'DATEVSmartLogin'. Do this by adding the LSApplicationQueriesSchemes key to your app's Info.plist file. If you call this methode without the declared DATEVSmartLogin URL scheme, this method always returns false, wether or not the SmartLogin app is installed.

Changelog

The DCAL library has different versions. The changes in each version are listed here.

iOS

DCAL Version	Changes	Date
2.4.4	Aktualisierung OpenSSL, LibCURL und NGHTTP	2024-04-26
2.4.3	Bugs fixed + 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.4	Aktualisierung OpenSSL, LibCURL und NGHTTP	2024-04-26
2.4.3	Bugs fixed	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 for iOS & Android

Overview

API endpoints

Download DCAL mobile

Registration of a third-party App

Implementation Information - Embedding the library

iOS

Android

DCAL States

DCAL API

Initialize DCAL

Return values

Login

Log-out user

Create a URLSession in iOS

Android networking (reqires DCAL Version >= 2.0.0)

Create a URLConnection in Android (deprecated since DCAL Version 2.0.0)

SessionDelegate

Get the DCAL state

Reset DCAL

Is SmartLogin available

Changelog

iOS

Android