• Overview
• Prerequisites
• Registration of your application
• Authentication
• Obtaining an Access Token
  • Authorization request
  • Exchange the authorization code for the access token
  • Error Handling

Overview

This page contains all the information and steps required to get started using the Sage Business Cloud Payroll Plus API. Once you have done all the heavy-lifting with registration and authentication setup, the Hello World example shows how to actually make it work and invoke a first set of API calls.

Please note that currently, as mentioned in the API overview, this API is only supported in the German product version, but you can still use it from anywhere (albeit the actual UI pages in the product are in German).

The API was initially designed for integration with partner products that would benefit from exchanging data with Sage Business Cloud Payroll Plus. It can be used for other use cases of course, for example for developers interested in getting experience with the API and the product to come up with new ideas that do not yet exist as a product to integrate with. So, for simplicity, this document refers to your application as the client integrating with the Sage Business Cloud Payroll Plus API.

The steps described will allow you to get up and running with the Sage Business Cloud Payroll Plus API.

Prerequisites

The following prerequisites must be met in order to be able to use the API of Sage Business Cloud Payroll Plus:

• Your application must use encrypted connections (HTTPS) to ensure confidentiality
• Your application must be registered with Sage (see below)
• A customer who wants to use the integration of your application and Sage Business Cloud Payroll Plus must be registered both in the your application as well as in Sage Business Cloud Payroll Plus

Registration of your application

To integrate the Sage Business Cloud Payroll Plus API into your application, the product must first be registered with Sage:

Send an email to [email protected]

The following data is required for registration:

• The name of the accountable company or person (as a individual developer, pick yourself)
• The name of your application (pick one if you’re working on a test client integration)
• The URL under which your application can be reached (if available)

Sage then assigns the product-specific API credentials:

• Client ID
• Client Secret

The Client Secret is to be treated confidentially and is known only to you and to Sage. In combination with the Client ID, the unique identification of your application takes place.

Authentication

This section explains how to use OAuth 2.0 to allow users to authorize your application (the client) to access their data without sharing their actual login details.

With every API request, you must supply a valid access token within the authorization header:

Authorization:  Bearer ‹Access Token›

Obtaining an Access Token

The steps outlined here explain how to obtain the access token and how to use the refresh token to get a new access token if the current one has expired.

Authorization request

Two cases need to be differentiated here:

Redirect to the chosen authorization server - in this example the production system via the API call https://app.sage-entgelt.de/api/v1/authorize - with the relevant URL query parameters:

Example redirect URL:

https://app.sage-entgelt.de/api/v1/authorize?client_id=4b64axxxxxxxxxx00710
        &state=4Whsv35d82bdbay6
        &redirect_uri=https://myapp.com/auth/callback

When this endpoint is hit, the user is prompted to sign in to Sage Business Cloud Payroll Plus and then is redirected to the callback URL along with an authorization code which can be read from the response:

GET /auth/callback?code=12a0f9c12cxxxxxxxxxxxxxxx92a48cc1f237ead
                  &state=...
                  &error_description=...
                  &error_uri=...

• code is the authorization code
• state is the state value, unchanged, sent during the authorization request

Error handling:

GET /auth/callback?error=...
                  &state=...
                  &error_description=...
                  &error_uri=...

• error_description is optional and a human-friendly error (as much as friendly can be an error).
• error_uri is optional too and URI zu einer Internetseite mit Fehlerdetails
• state is the state value, unchanged, sent during the authorization request

Possible errors:

Exchange the authorization code for the access token

To exchange the authorization code for an access token, you should now make a POST request to the token endpoint:

https://app.sage-entgelt.de/api/v1/token

Required parameters:

Example request:

POST https://app.sage-entgelt.de/api/v1/token
    ?code=...
    &client_id=...
    &client_secret=...
    &grant_type=authorization_code
    &redirect_uri=...

Example response :

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "...",
    "token_type": "Bearer"
}

The OAuth implementation in Sage Business Cloud Payroll Plus uses JSON-Web-Token (JWT).

The access token (access_token) and the token type (token_type) need to be securely stored within your application in connection with the customer account.

Please note that the token information is a piece of confidential information between Sage and your application. It must not be divulged to any third party as this does compromise the confidentiality and integrity of customer data.

Error Handling

Errors can occur when requesting an access token. Possible causes are:

• Invalid data (parameters) in the request
• Invalid client data (client ID, client secret)
• Invalid authorization code

The HTTP response sent by Sage Business Cloud Payroll Plus is structured like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    “error": “...",
    “error_description": “...",
    “error_uri": “..."
}

• error is always provided (see below for error codes)
• error_description is optional and a human-friendly error
• error_uri is optional, too, and (if available) points to a web page with more information and details

Possible error codes: