Asperion REST API

Asperion heeft voor de ondersteuning van software van partners een API beschikbaar.
Deze API en documentatie is bedoeld voor software ontwikkelaars die hun software willen koppelen met Asperion.

Ook API partner worden van Asperion? Meld je dan aan via: https://www.asperion.nl/partners/api/

Je aanvraag wordt beoordeeld en vervolgens ontvang je een de gegevens van een test-account (sandbox)

Je ontvangt dan een client-id, waarmeer je aan de slag kunt in de sandbox omgeving en de benodigde support en documentatie om jouw app tot een succes te maken! Vragen of hulp nodig bij de integratie met Asperion. Contacteer het API support team via: api-support@asperion.nl

Onderstaande documentatie helpt bij de implementatie van de REST API.

Meer informatie over de beschikbare EndPoints zie: API Endpoints

SSL

Alle verbindingen met Asperion zijn via HTTPS. Onversleuteld verkeer wordt niet toegestaan.

Autorisatie

Om gebruik te maken van de API moet de toegang worden gevalideerd. De API partner heeft hiervoor de client-id nodig.
Deze wordt op verzoek uitgegeven door onze api-support afdeling.

Voor de autorisatie van de gebruikersgegevens gebruikt de Asperion API het protocol oAuth 2.0.
oAuth is een industrie standaard voor authenticatie. Voor meer informatie zie: https://oauth.net/

Api authenticatie

Elke request naar de API moet worden voorzien van een authorization header.
In deze header wordt een Bearer token meegegeven (access_token). Deze access_token kan worden opgvraagd via de Asperion authenticatie service.

Autenticatie Endpoint is beschikbaar via:

https://identity-sandbox.asperion.nl (SandBox/test omgeving)
https://identity.asperion.nl (Productie)

Authenticatie process

Er wordt gebruik gemaakt van de oAuth2 Authorization Code Flow

oauth-flow

De gebruiker worden geredirect naar een login pagina (Authorize Endpoint)
De gebruiker wordt geauthenticeerd.
Gebruiker wordt teruggestuurd naar de client, met een authorizatiecode.
Deze authorizatiecode wordt gevalideerd door de authenticatie server (Token Endpoint)
Een access_token (en refresh_token) worden teruggestuurd naar de client

Een access_token heeft een gelimiteerde geldigheid, en het is mogelijk om zonder tussenkomst van een gebruiker een nieuwe access_token op te vragen met behulp van een refresh_token.

Access Token

In de access_token wordt opgeslagen voor welke administratie de request gedaan wordt.

Dit betekent dat dit niet direct wordt meegegeven bij de parameters van de end-point, maar dat dit via het access_token geregeld wordt.
Dit betekent ook dat als er een request gedaan moet worden voor een andere administratie, dat er een ander access_token aangevraagd moet worden.

Voorkeursadministratie(id) meegeven via het authenticatieprocess (zie: Authorize Endpoint, acr_values)

Endpoints

Authorize Endpoint

De gebruiker wordt door de client applicatie gerdirect naar deze url om een authenticatie te starten. Als alle parameters correct zijn krijgt de gebruiker de mogelijkheid om in te loggen.

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

Parameters

client_id
Unieke identifier van de client (wordt uitgegeven door Asperion)
scope
Een of meedere scopes, voor toegang tot de api, zal de scope: asperion-api moet worden opgevraagd.
Om ook de beschikking te hebben over een refresh_token, moet ook de scope offline_access worden opgevraagd.
response_type
Dit moet zijn code, dit komt overeen met de Authorization Code Flow
redirect_uri
De uri waarnaar moet worden geredirect worden nadat de gebruiker is ingelogd, dit moet een uri zijn welke bij Asperion is opgegeven.
acr_values
Extra waardes die kunnen mee worden gegeven, er kan hier worden opgegeven voor welke administratie het token moet zijn (indien de id van de administratie bekend is). Dit wordt gedaan met de tenant property.

Token Endpoint (authorization_code)

POST /connect/token
    client_id=client&
    client_secret=secret&
    grant_type=authorization_code&
    code=hdh922&
    redirect_uri=https://myapp.com/callback

Parameters

client_id
unieke identifier van de client (naam wordt uitgegeven door Asperion)
client_secret
Geheime string om de client te valideren. (Wordt uitgegeven door Asperion)
grant_type
Beschrijving van manier om de token op te halen.
Om een access_token op te halen met een authorizatie code, wordt hier authorization_code verwacht.
code
De code zoals geleverd via de redirect_uri van Authorize Endpoint
redirect_uri
Dezelfde redirect uri als bij de Authorize Endpoint

Response

Indien alle parameters correct en valide zijn, zal de bovenstaande POST request resulteren in een access_token en een refresh_token

Token Endpoint (refresh_token)

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

Parameters

client_id
Unieke identifier van de client (wordt uitgegeven door Asperion)
client_secret
Geheime string om de client te valideren. (wordt uitgegeven door Asperion)
grant_type
Beschrijving van manier om de token op te halen. Om een access_token op te halen met een refresh_token
refresh_token
De door het token endpoint (authorization_code) uitgegeven refresh_token.

Response

Indien alle parameters correct en valide zijn, zal de bovenstaande POST request resulteren in een nieuwe geldige access_token en een refresh_token

Asperion API

De Asperion API is een manier voor externe software om toegang te krijgen tot de gegevens uit de Asperion boekhoud applicatie.
De Asperion API is gebasseerd op REST (REpresentational State Transfer)

Structuur

REST based, via HTTPS
Met behulp van endpoints en de HTTP methods kunnen objecten worden opgevraagd en aangepast worden.
- GET - Opvragen
- PUT / PATCH - Aanpassen
- POST - Toevoegen
- DELETE - Verwijderen
De API is beschikbaar op de volgdende url's (endpoints)
- https://api.asperion.nl (productie omgeving)
- https://api-sandbox.asperion.nl (sandbox/test omgeving)

Techinsche documentatie

Er is technische documentatie aanwezig. (zie: https://api-sandbox.asperion.nl/swagger/v1/swagger.json )
Deze documentatie is gegenereerd op basis van de beschikbare endpoints op basis van Swagger
Dit maakt het mogelijk om code te genereren in elke programmeertaal waar dit voor beschikbaar is (zie: https://swagger.io/tools/swagger-codegen/ )
Ook is er een swagger UI aanwezig: (zie: https://api-sandbox.asperion.nl/swagger/index.html )

HTTP Methods

GET /objects

Sortering (volgorde van resultaat aanpassen)
Filtering (specifieke queries uitvoeren)
Velden (welke velden van het object worden er opgevraagd)
Paginering (paginanummer en paginagrootte opgeven)

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

* Sortering

Sorteren kan op het veld naar keuze door de parameter orderby op te geven.

Voorbeeld:

/v1/debtor/?page=1&pagesize=1&orderby=id

Door een "-" teken te gebruiken kan er worden gewisseld tussen ASC en DESC sortering.

Voorbeeld:
orderby= id is asc, orderby= -id is desc

* Filtering

Er kan op meerdere velden tegelijk filteren door deze manier te hanteren: GET /v1/articles?Id=563418&Id=563419

Door dezelfde querystring parameter meerdere keren te gebruiken, kunnen er meer records in een keer worden opgehaald.

Dan wordt er tussen de filter van hetzelfde veld een "OR" gedaan, en als je andere velden filtert, dan wordt er een "AND" gedaan

GET /objects/{id}

Ophalen van een enkel object op basis van de Identifier, de parameters hier zijn:

Velden (welke velden van het object worden er opgevraagd)

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 is om een object toe te voegen
De body van de request wordt voorzien van het geupdate object
Welke velden er zijn is beschikbaar via de swagger documentatie.

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

Indien het object successvol is aangemaakt, zal deze worden teruggegven via de response-body met een statuscode 201. Er zal een location header beschikbaar zijn met de url van het nieuw aangemaakte object.
Een 400 (Bad Request) zal worden teruggegeven indien er niet worden voldaan aan de validatieregels van het object (met de reden waarom)

PUT /objects/{id}

Bestaand object wijzigen
De url verwijst naar een bestaand object
De body van de request wordt voorzien van het geupdate object

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

PATCH /object/{id}

Bestaand object gedeeltelijk verwijderen
De url verwijst naar een bestaand object
De body van de request wordt voorzien van geupdate velden van het object
Alleen de opgegeven velden worden aangepast, de rest blijft de bestaande waardes houden.

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

DELETE /objects/{id}

Object verwijderen
Dit zal het object verwijderen, (mits er wordt voldaan aan de validatieregels)

DELETE /countries/1

API Endpoints overzicht

API Endpoints