[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:
- 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
- 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.
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
- 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.
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)
Technische 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://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" } }
Voorbeeld:
orderby= id is asc, orderby= -id is desc
* Filtering
* 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:
- 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