API

Asperion webservice beschrijving van de REST API

[Nederlands / NL]   |   [English / EN]

Asperion REST API (NL)

Asperion heeft voor de ondersteuning van software van partners een API beschikbaar.
Deze API en documentatie is bedoeld voor software ontwikkelaars die hun commerciële 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 eerst beoordeeld en als deze wordt gehonoreerd, ontvang je de gegevens van een test-account (sandbox) en een client-id, waarmee je aan de slag kunt in de sandbox omgeving. Daarnaast ontvang je de benodigde 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.

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: 

 

Authenticatie process

Er wordt gebruik gemaakt van de oAuth2 Authorization Code Flow

 oauth-flow

  1. De gebruiker worden geredirect naar een login pagina (Authorize Endpoint)
  2. De gebruiker wordt geauthenticeerd.
  3. Gebruiker wordt teruggestuurd naar de client, met een authorizatiecode.
  4. Deze authorizatiecode wordt gevalideerd door de authenticatie server (Token Endpoint)
  5. 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. 

Endpoints

Authorize Endpoint

De gebruiker wordt door de client applicatie ge-redirect naar deze url om de authenticatie te starten.
Als alle parameters correct zijn kan er ingelogd worden.

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

Parameters

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

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

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

Technische documentatie

 

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"
  }
}

* 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
* MetaOnly
Bij de GET is er tevens de optie om een MetaOnly (bool) property mee te geven.
Bij de MetOnly bool, zal alleen de _meta data worden regetourneerd, dan worden alleen de aantaalen teruggegeven en niet het dataobject zelf.
 

GET /objects/{id}

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

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 "
}

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}

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

PATCH /object/{id}

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

DELETE /objects/{id}

DELETE /countries/1

API Endpoints overzicht

API Endpoints

 

Tags API REST WebService
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.