Payroll

Preface

In this how-to guide, we will describe how to generate a C# client.

Using the swagger documentation, which is available in the markup language YAML, a client can be generated in various programming languages. Generation is performed using the online swagger editor, which can be accessed at http://editor.swagger.io. The required swagger YAML can be found in each "API Reference" (click “Open API”).

Generation

The documentation can be imported into the editor by clicking on "File | Import File" in the editor menu.

The documentation can be selected and added in the resulting window. The desired programming language can now be selected under “Generate Client,” and the client code can be downloaded. In the ZIP file downloaded, the following important folders can be found under the path src\IO.Swagger:

• API - this folder contains classes with functions that enable interaction with the end points of the DATEVconnect service.
• Client - coveres the classes for the actual HTTP call and for configuring the client.
• Model - generated model classes can be found in this directory.

Client example

The generated classes can now be used to generate a client. There are two possibilities in this regard:

1. Open IO.Swagger.sln and build; the library generated can be found under src\IO.Swagger\bin\Debug\Swagger Library.dll.
2. Use the supplied build.bat (Windows) or build.sh (Linux) to automatically generate a client library. The file generated will be stored as Swagger Library.dll in the bin folder and must then be referenced in your own C# project. An Internet connection is required to execute build.bat/build.sh, as the packages RestSharp.dll and Newtonsoft.Json.dll will be loaded at a later stage via NuGet.

In the project, references to RestSharp, Newtonsoft.Json and System.Runtime.Serialization need to be added.

In the event that the DATEVconnect end point does not match the one stored in swagger (host name/IP), this can be amended with a new ApiClient instance.

The end point will be transferred to the constructor:

ApiClient apiClient = new ApiClient("http://localhost:58454/datev/api");

This new client must be presented to the default configuration that is used for every call:

Configuration.Default.ApiClient.RestClient = apiClient.RestClient;

The desired authentication method will then be determined by the Configuration class:

• HTTPS: basic authentication.

Configuration.Default.ApiClient.RestClient.Authenticator = new HttpBasicAuthenticator("username", "password");

• HTTP: NTLM-based authentication.

Configuration.Default.ApiClient.RestClient.Authenticator = new NtlmAuthenticator();

In order to be able to interact with DATEVconnect, an object has to be generated that is suitable for the use case. When, for example, working with clients, the class MandantenAbrufenApi is a suitable choice. All available classes for interacting with DATEVconnect:

• Business partners:

var BusinessPartnerApi = new BusinessPartnerApi();

With the object generated, the corresponding API path can now be addressed with the corresponding verb. It is also possible to transfer the query parameters select, top, skip, filter, expand or other necessary parameters to the methods.

Furthermore, requests can also be send asynchronously; this is available with all methods that contain “Async” in their name. Functions with “WithHttpInfo” can be used to receive status codes and header information.

The methods are structured using the same schema as the corresponding URL: DomainDomainversionResourcepathVerb()

GET

Example of GET (get clients) with select and filter parameters:

var clients = MandantenApi.AccountingV1ClientsGet("Name", "startswith(Name, Küche)");

Result:

List of all client names (CoreV1Clients) that begin with “Küche.”

POST

Example of POST (generate business partner/creditor) with object body and HttpInfo:

var creditorPost = GeschaeftspartnerApi.AccountingV1ClientsClientIdCreditorsPostWithHttpInfo
("55039", new Creditor
{
    ShortName = "ShortName",
    Salutation = "Herr",
    LegalEntityType = Creditor.LegalEntityTypeEnum.Legalperson,
    LegalPerson = new DatevLegalPerson()
    {
        LegalName = "TestName"
    },
    AccountingInformation = new DatevCreditorAccountingInformation 
    {
        IsVariousAccount = false,
        Language = DatevCreditorAccountingInformation.LanguageEnum.German,
        OutputDestination = DatevCreditorAccountingInformation.OutputDestinationEnum.Notspecified,
        IsInsolvent = false,
    },
    CorrespondenceTitle = "Firma",
    IsBusinessPartnerActive = true
});

Result:

Business partner of client with ID 55039 is generated. With a successful POST with HttpInfo, only the HTTP status code (204 – request successful, no content) and the header are returned. Without the HttpInfo suffix, no data is returned.

PUT

Example of PUT (overwrite business partner/creditor) with object body and HttpInfo:

var creditorPut = GeschaeftspartnerApi.AccountingV1ClientsClientIdCreditorsCreditorIdPutWithHttpInfo
("55039", "700010000", new Creditor(Id: "700010000")
{
    ShortName = "ShortNameNew",
    Salutation = "Herr",
    LegalEntityType = Creditor.LegalEntityTypeEnum.Legalperson,
    LegalPerson = new DatevLegalPerson()
    {
        LegalName = "TestName"
    },
    AccountingInformation = new DatevCreditorAccountingInformation 
    {
        IsVariousAccount = false,
        Language = DatevCreditorAccountingInformation.LanguageEnum.German,
        OutputDestination = DatevCreditorAccountingInformation.OutputDestinationEnum.Notspecified,
        IsInsolvent = false,
    },
    CorrespondenceTitle = "Firma",
    IsBusinessPartnerActive = true  
});

Result:

The creditor with ID "700010000" of the client with ID 55039 is overwritten (ShortName was changed, see POST example). With a successful PUT with HttpInfo, only the HTTP status code (204 – request successful, no content) and the headers are returned as a result. Without HttpInfo, no data is returned.