API

Asperion REST API Description

Asperion REST API

Asperion has made an API available for third party software developers that intend to connect their commercial applications to the Asperion accounting software platform.

If you want to be an API partner with Asperion, then sign up via: https://www.asperion.nl/partners/api/ 

Your application will be evaluated and, if succesfull, you’ll receive the details for a test account (sandbox) and a client ID. This ID gives you access to the sandbox environment and the needed support and documentation to make your app a real success!

Do you have questions or need help with the integration of Asperion? Contact the API support team via: api-support@asperion.nl

 

The following documentation helps with the implementation of the REST API.

For more information about the available EndPoints, use this link : API Endpoints


SSL

All connections with Asperion go via HTTPS. Minimum level is TLS1.3. Unencrypted traffic is not allowed. 

Authorization

In order to use the API, access must be validated. The API partner requires the Client-ID for this.
This is released upon request by our API-support department.

For the authorization of the user data, Asperion API uses the protocol oAuth 2.0.
oAuth is a authentication standard in the industry. For more information, take a look at: https://oauth.net/

Api authentication

All API requests must contain an authorization header.
This header must contain a Bearer token (access token). This accesstoken kan be requested using the Asperion authentication service.
You can retrieve the data of an administration (Tenant) by adding a parameter X-Tenant-Id in the header.

Authentication endpoint is available via: 

 

Authentication process

The oAuth2 Authorization Code Flow is used

 oauth-flow

  1. The user will be redirected to a login page (Authorize Endpoint)
  2. The user will be authenticated.
  3. User will be send back to the client, with an authorization code.
  4. This authorization code will be validated by the authentication server (Token Endpoint)
  5. An access_token (and refresh_token) will be send back to the client

 

An access_token has a limited validity and it’s possible to request a new access_token (without the interference of a user) with the help of a refresh_token.

 

 

Endpoints

Authorize Endpoint

The user will be redirected by the client application to this url to start an authentication. If all parameters are correct, the user will be able to login.

GET /connect/authorize?
    client_id=client&
    scope=asperion-api offline_access&
    response_type=code&
    redirect_uri=https://myapp/callback

Parameters

Token Endpoint (authorization_code)

POST /connect/token

   CONTENT-TYPE application/x-www-form-urlencoded

    client_id=client
    &client_secret={secret}
    &grant_type=authorization_code
    &code={received code}
    &redirect_uri=https://myapp.com/callback


(Form-encoding removed and line breaks added for readability)

Parameters

Response

If all parameters are correct and valid, the POST request above will result in an access_token and a refresh_token

Token Endpoint (refresh_token)

POST /connect/token
    client_id=client&
    client_secret=secret&
    grant_type=refresh_token&
    refresh_token=token

Parameters

Response

If all parameters are correct and valid, the POST request above will result in a new, valid access_token and refresh_token.

 

 

Asperion API

The Asperion API is a way to get access to the data from the Asperion accounting application for external software.

The API is based on REST (REpresentational State Transfer)

Structure

Technical documentation (Swagger)

 

HTTP Methods

GET /objects

GET /countries?page=1&pageSize=2
{
  "_data": [
    {
      "id": 1,
      "name": "The Netherlands",
      "code": "NL ",
      "_meta": {
        "self": "https://api.asperion.nl/v1/countries/1"
      }
    },
    {
      "id": 2,
      "name": "Belgium",
      "code": "BE ",
      "_meta": {
        "self": "https://api.asperion.nl/v1/countries/2"
      }
    }
  ],
  "_meta": {
    "previousPage": null,
    "nextPage": "https://api.asperion.nl/v1/countries?pageSize=2&page=2",
    "totalCount": 246,
    "pageCount": 123,
    "self": "https://api.asperion.nl/v1/countries?pageSize=2&page=1",
    "administrationId": 1234,
    "administrationName": "Test",
    "profileName": "UserName"
  }
}

* Sorting
Sorting can be done on the field of preference by filling in the parameter orderby.

Example:
/v1/debtor/?page=1&pagesize=1&orderby=id
By using the "-" sign, you can switch between ASC and DESC sorting.
Example: 
orderby= id is asc, orderby= -id is desc


* Filtering 

You can filter multiple fields at once by doing the following: GET /v1/articles?Id=563418&Id=563419
By using the same query string parameter multiple times, you can retrieve multiple records at once.
​This way, an “OR” is placed in the middle of the same field, and if you’re filtering other fields you can place an “AND” in this place.

* MetaOnly
With GET, you’re getting the opportunity to impart a MetaOnly (bool) property. 
With the MetaOnly bool, only the de _meta data will be returned, so only the numbers will be returned and the data object will be left out.
 

GET /objects/{id}

Retrieving a single object based on the Identifier, the parameters here are:

GET /countries/1
{
  "id": 1,
  "name": "The Netherlands",
  "code": "NL ",
  "_meta": {
    "self": "https://localhost:44366/v1/countries/1",
    "administrationId": 1234,
    "administrationName": "Test",
    "profileName": "UserName"
  }
}


POST /objects

POST /countries
{
  "name": "The Netherlands",
  "code": "NL "
}

If the object is succesfully created, it will be returned via the response body with a status code 201. A location header will be available with the url of the newly created object.
A 400 (Bad Request) will be brought up if the validation rules and standards of the object aren’t met (together with the reasons why).

PUT /objects/{id}

POST /countries/1
{
  "name": "Nederland",
  "code": "NL "
}

PATCH /object/{id}

PATCH /countries/1
{
  "name": "Nederland"
}

DELETE /objects/{id}

DELETE /countries/1

API Endpoints overview

API Endpoints

 

Tags API English REST API
Disclaimer:
De voor u beschikbare functies worden bepaald door het type abonnement dat is afgesloten. Sommige hier beschreven functies kunnen voor u dus niet beschikbaar zijn en/of soms iets anders werken dan zoals hier beschreven.

Hoewel bij de totstandkoming van de informatie in dit document de uiterste zorg is betracht en er naar gestreefd is om deze informatie zo compleet en volledig mogelijk te maken en te houden, kan Asperion noch de juistheid, noch de volledigheid, noch een specifieke toepasselijkheid van de gepubliceerde en/of gevraagde informatie in dit document garanderen. Asperion wijst iedere aansprakelijkheid af voor enige directe, indirecte of gevolgschade, schade in de vorm van gemiste winst of van bedrijfsonderbreking welke het gevolg zou zijn van het gebruik van dit document. Het ontlenen of gebruik van informatie uit dit document geschiedt te allen tijde op eigen risico van de gebruiker. Teksten kunnen, zonder kennisgeving vooraf, veranderd worden.

Niets uit deze uitgave mag worden verveelvoudigd, opgeslagen in een geautomatiseerd gegevensbestand, of openbaar gemaakt in enige vorm, op enige wijze, hetzij door middel van druk, fotokopieën, microfilm of op welke andere wijze dan ook, zonder voorafgaande schriftelijke toestemming van Asperion

© Copyright - Asperion® en het Asperion logo zijn zowel handelsnaam als geregistreerde handelsmerken van Asperion Software B.V.