Payroll

Introduction

DATEVconnect is a RESTful API that can be used to read and write files from DATEV on-premises applications. The end point is structured according to the schema:

<scheme>://<ip-address>:<port>/datev/api/<domain>/<domain-version>/<resource-path>

The placeholders are to be defined as follows:

Authentication

DATEVconnect supports several authentication methods dependent on the transport protocol used. For every request sent to DATEVconnect the authentification will be excecuted, therefore there are no sessions. Anonymous requests will not be accepted.

Please note:

• Authentication is performed by the Windows system, hosting the DATEVconnect service. If necessary, the full user name, including the authority (domain or name of the computer), may be required, i.e. Domain \ username.
• The user is authorized by the user and rights management (Integrated Access Management - IAM).

Path specifications and identifying individual resources

It is possible to address either a list of resources or an individual resource. For a list resource, it is sufficient just to state the name of the resource in the URI. If just a single element on this list should be adressed, the URI segment, which defines the resource name, must be followed by a segment containing the ID of the desired element.

The addressing of the list resource “clients” could appear as follows:

http://localhost:58454/datev/api/master-data/v1/clients

A single element from this list could be addressed using the following URI, albeit with the placeholder {client-id} replaced by the ID of the element concerned

http://localhost:58454/datev/api/master-data/v1/clients/{client-id}

It is also possible to address resources that are subordinate to other resources:

http://localhost:58454/datev/api/master-data/v1/parent-resource/{parent-resource-id}/child-resource

Here, it is once again possible to address an individual element of the subresource by stating an ID. This hierarchy can be continued indefinitely.

Functional resources

In the case of certain resources, it is also possible to address functions. Instead of the usual read/write operations, these execute a function upon the resource involved. Functions can only be requested on lists. When doing so, the name of the function must be defined immediately after the resource name.

http://localhost:58454/datev/api/master-data/v1/clients/{function-name}

Using HTTP verbs

DATEVconnect makes it possible to read, add, and modify resources. First of all, the resource must be addressed in the manner described above. Depending on which HTTP verb is selected, a decision is made as to whether the addressed resource will be read, written, or modified. Resources are read using GET. POST is used to add resources. PUT makes it possible to modify existing resources.

HTTP-POST

HTTP-POST can be used to write new resources. A POST request must always be addressed to a list resource; in other words, no ID may be defined in the final segment of the URI. The object being written must always be placed individually in the body of the HTTP request message and may also not contain an ID. A list of objects cannot be transmitted. The HTTP response message does not contain the written object. The URI via which the written object can be addressed is found in the HTTP response header. Instead, notifications may be contained in the HTTP body of the response.

HTTP-PUT

HTTP-PUT can be used to modify existing resources. A PUT request must always be addressed to an individual resource; in other words, the ID must always be defined in the final segment of the URI. The object being written must always be placed individually in the body of the HTTP request message, and the ID has to match the ID in the URI. A list of objects cannot be transmitted. The HTTP response message does not contain the modified object. The URI via which the modified object can be addressed is found in the HTTP response header. Instead, notifications may be contained in the HTTP body of the response.

HTTP-Request-Header

For every request sent to DATEVconnect, certain fields should be included in the HTTP request header. All possible fields are described in the table below. In the event that a field is not included, the default value will be used.

Therefore, a request using the fields listed in this table may appear as follows:

GET http://localhost:58451/datev/api/v1/clients
  Content-Type: application/json
  Accept: application/json
  Client-Application: My Application
  Client-Version: 1.0
  If-None-Match: "3", "4"

HTTP response header

Every response message returned by DATEVconnect contains multiple fields in the HTTP header.

Whether or not links are contained in the response header depends on the request made.

• If a “read” request is performed using HTTP-GET including paging, links to other pages will be contained in the response header.
• If a “write new” request is performed using HTTP-POST, a link may be returned via which the resource written can be read. Whether or not a link of this kind is present depends on whether or not the resource is readable in the first place. If this is not the case, this is described in the API documentation.
• If a resource is modified via HTTP-PUT, a link is always returned via which the resource can be reread.

All links are structured in accordance with RFC5988. The meaning of the link can be interpreted using the link relation type provided. The following link relation types are used by DATEVconnect:

The link is separated from the link relation type by a semicolon. If multiple links are contained within a response, these are separated by commas. The following example is designed to illustrate this point:

HTTP/1.1 200 OK
Link: <https://localhost:58452/datev/api/master-data/v1/clients?top=10&skip=30>;rel="self",
<https://localhost:58452/datev/api/master-data/v1/clients?top=10&skip=0>;rel="first",
<https://localhost:58452/datev/api/master-data/v1/clients?top=10&skip=20>;rel="prev",
<https://localhost:58452/datev/api/master-data/v1/clients?top=10&skip=40>;rel="next",
<https://localhost:58452/datev/api/master-data/v1/clients?top=10&skip=80>;rel="last"

Troubleshooting and notifications

DATEVconnect returns three types of response message, with each type distinguished by the HTTP status code.

• Everything OK → HTTP status code 2xx
• Client error → HTTP status code 4xx
• Server error → HTTP status code 500

If DATEVconnect returns a status code that is not within the 2xx range, the request has not been processed by the server. The client may assume that there has been no change to the situation. In addition to a status code, DATEVconnect may also return additional information in the HTTP response message. This information will be shown in line with the following schema:

{
    "error" : "Fehler-ID",
    "error_description" : "Beschreibung des Fehlers",
    "error_uri" : "URI zu weiterführenden Informationen zum Fehler",
    "request_id" : "ID des HTTP Requests",
    "additional_messages" : […]
}

The meaning and possible values of the errors are explained in more detail in the table below:

If several errors have occured within a request or additional information is available, these are available within additional_messages. This information is structured according to the following schema:

{
    "id" : "Fehler-ID",
    "description" : "Beschreibung des Fehlers",
    "severity" : Information|Warning|ValidationFault|Error,
    "help_uri" : "URI zu weiterführenden Informationen zum Fehler"
}

In the event that multiple errors have occurred within a request or if additional information is available, this information can be accessed within additional_messages. This information is structured in accordance with the following schema:

In order to ensure that the notifications in the HTTP body are transferred along with the payload in an HTTP-GET response, the client must ensure that the “Accept” field contains at least application/json and multipart/mixed. This makes it possible to distinguish between payload and messages. A response message is shown below that contains both payload data and notifications.

--b2138be2-9fc5-4459-93b8-1b70abb18881
Content-Type: application/json; charset=utf-8
[
  {
    <content...>
  }
]
--b2138be2-9fc5-4459-93b8-1b70abb18881
Content-Type: application/json; charset=utf-8
{
  "id":"DCOxxxxx",
  "message":"This is a message",
  "help_link":"http://www.datev.de",
  "ticket":"139ebc57-f1ec-4f57-af21-e1c305404995",
  "messages":
  [
    {
      "id":"DCO12345",
      "description":"This is a message",
      "severity":"Information",
      "help_link":"http://www.datev.de"
    }
  ]
}
--b2138be2-9fc5-4459-93b8-1b70abb18881--

By contrast, the notifications are always transferred in the case of HTTP-POST and -PUT responses, regardless of the “Accept” header. This is possible, as payload data is never contained in the answer messages.

URI-Parameter

Additional parameters can be defined for each HTTP request. These must always be defined after the URI in line with the following schema: http://localhost:58454/datev/api/v1/clients?key1=value1&key2=value2. The number of possible parameters depends on the HTTP method used and the resource. For HTTP-GET, the following minimum parameters are always permissible: filter, top, skip, select. For all other parameters, please refer to the API description.

Filter

The query parameter filter can be used to select data sets whose fields satisfy the defined conditions. The operators listed in the table below are available for filtering purposes. The order of operations corresponds to the order of the list, starting with the highest priority.

Availability of the filter parameter

The filter parameter is only supported for HTTP-GET-requests.

Observing API-specific implementation

Depending on the resource, filters cannot be applied for all resource fields. On the other hand, filtering by the available fields delivers better performance. The filterable fields are listed in the API documentation. If no information can be found on a resource, all fields and all operators are supported.

Paging

Using the query parameters top and skip, the data sets can be scanned on a page-by-page basis.

Select

All fields of a resource are loaded and transferred via HTTP as standard. With respect to large objects, however, not all fields are always relevant. In this case, it is possible to define the relevant fields using the query parameter select. The fields entered are to be separated from each other by commas. A corresponding request in which only the field ID and field name is queried could appear as follows:

http://localhost:58454/datev/api/master-data/v1/clients?select=id,name

Expand

With an aggregation, links to other resources are eliminated, and the representation of the referenced resource is embedded in the resource requested. This can be used as an opportunity to reduce the number of request–response cycles between client and server. The resource NaturalPerson serves as an example. A NaturalPerson may have one or more addresses. For the sake of simplification, only minimal attributes are present.

Request for a natural person:

GET /natural-persons/1234
{
    "id" : "1234",
    "name" : "Mustermann"
}

The requested representation of NaturalPerson now contains values for id and name but not for addresses, as the addresses are modeled as a subresource. In order to receive the addresses as well, a second request has to be composed.

GET /natural-persons/1234/addresses
[
    {"id" : "1"},
    {"id" : "2"}
]

Now, in order to receive a natural person and their addresses, it is always necessary to submit two requests. Using an aggregation, access to the use case “Reading a natural person including addresses” could now be simplified.

GET /natural-persons/1234?expand=addresses
{
    "id" : "1234",
    "name" : "Mustermann",
    "addresses" : [
        {"id" : "1"},
        {"id" : "2"}
    ]
}

Special data types

Some data types have to be available in a certain format to enable DATEVconnect to interpret them correctly. By the same token, DATEVconnect will always return these data types in the same format.

Special characters within the URI

As a rule, no special or reserved characters are required in the URI. It may, however, be necessary to use special characters within URI parameters such as the filter. In accordance with RFC 3986 (http://tools.ietf.org/html/rfc3986#section-2), only ASCII characters are used within URIs. However, these guidelines also specify how to enter special and reserved characters. Both types must be entered in encoded form using the percentage sign. Characters not included within the ASCII character set must also be entered in UTF-8-encoded form using the percentage sign. For instance, the German character “ö” is represented by “%C3%B6”.

Notes on working with DATEV

Licenses

After importing the DATEVconnect license in the first place or as an update, make sure to restart the DATEVconnect service.
This can be done via "windows services" or by applying Configuration.