Asperion API

Asperion webservice beschrijving van de REST API

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: 

 

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

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

Techinsche documentatie

 

HTTP Methods

GET /objects

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:

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.