In dit artikel wordt uitgelegd hoe je gebruik kunt maken van de vPlan API voor het in- of uitlezen van data of het maken van een integratie met een externe applicatie. Dit artikel is bedoeld voor een snel overzicht van alle mogelijkheden en hoe je moet starten. De volledige technische documentatie vind je op docs.api.vplan.com

Overzicht

Wil je vPlan data gebruiken voor analytics, of vPlan connecten met een eigen app? Dan kun je gebruik maken van de vPlan API. vPlan's API biedt een middel voor software en scripts om informatie uit vPlan te lezen, informatie van buiten vPlan in te voeren en automatisch te reageren wanneer zaken veranderen. Dit kunnen zijn:

Rapporten en dashboards maken over de status van de planning
Gelijktijdig synchroniseren met andere ERP systemen of boekhoudsoftware zoals Exact Online of Moneybird, die in uw organisatie worden gebruikt
Nieuwe functies toevoegen aan vPlan, zoals tijdschrijven
vPlan aanpassen aan de processen en workflows van jouw team

Authenticatie

Elk verzoek naar deze API moet altijd een Authorization Header bevatten, tenzij anders is aangegeven. De vPlan API gebruikt JWT als verificatiemechanisme en de tokens worden geleverd met OAuth 2.0.

JWT Token

Een JWT (JSON Web Token) bestaat uit drie delen, een header, een payload en een signature (handtekening). De signature wordt op de server gemaakt met een specifiek geheim. Een gebruiker kan een JWT token niet zelf genereren. De header bevat informatie over het token (type en handtekeningalgoritme). De payload bevat informatie over de gebruiker en de geldigheid van het token (gebruikersnaam, vervaldatum, uitgever). De signature is een hash, gegenereerd met het gedefinieerde algoritme in de header.

OAuth 2.0

OAuth is een van de meest gebruikte methoden voor authenticatie. In de kern is OAuth een mechanisme voor applicaties om toegang te krijgen tot de vPlan API op basis van een gebruiker, zonder dat de applicatie toegang heeft tot de gebruikersnaam en wachtwoord. In plaats daarvan krijgen applicaties een token. Met deze token kunnen ze eigen toepassingenreferenties gebruiken om API-aanroepen te doen.

Tip

Als je nog niet bekend bent met OAuth, neem dan een moment om het hier te leren.

API key

API-keys zijn alleen beschikbaar in Proef, Basis en Professional pakketten van vPlan. Als je toegang nodig hebt tot de vPlan API en je hebt Admin rechten in je account, dan kun je API-keys aanmaken en inzien:

In vPlan, ga naar Configuratie in de linker menubalk, en klik daarna op het menu Ontwikkelaars.
Als je nog geen API-key hebt aangemaakt, klik dan op het plus-icoontje naast het kopje API-keys.
Geef je API-key een naam en klik op Opslaan. Er verschijnt een pop-up scherm waarin je API-key eenmalig volledig getoond wordt. Kopieer de API-key met de daarvoor bestemde knop en sla deze veilig op.
Om een API-key te verwijderen kun je op een later moment altijd weer terug gaan naar het menu Ontwikkelaars. In dat menu klik je op de naam van je API-key en in het scherm wat volgt klik je op Verwijderen.

Let op

Een API key is een statisch gegeven en geeft toegang tot je hele vPlan database. We adviseren om met regelmaat je API-key te veranderen. vPlan zal je hier automatisch eens per zes maanden over berichten.

Creëer een OAuth app

Technische informatie over OAuth kun je vinden in onze API documentatie. Onderstaande, wordt daar ook in uitgelegd, alleen vanuit een technisch oogpunt. Daar word je onder andere verwezen naar een technisch vereenvoudigde uitleg.
In dit artikel leggen we de volgende handelingen uit:

Registreren van een applicatie
Eenmalig verbinding maken
Herhalende verbinding

Registreren applicatie

Om via OAuth met vPlan verbinding te maken moet een developer zich eerst bekend maken bij vPlan.

Ga naar https://developer.vplan.nl/
Klik op de knop Create oAuth App.
Vul alle velden op de pagina in.
Let op App Base Redirect URI en App Logo URL worden gebruikt in het OAuth proces bij het verbinding maken.
Klik op de knop Signup en een blok zoals onderstaand voorbeeld wordt weergegeven:
Zorg ervoor dat de client_id en client_secret veilig opgeslagen wordt. De Client secret wordt eenmalig getoond.

Eenmalig verbinding maken (per klant)

Bij OAuth wordt er vaak vanuit gegaan dat er twee applicaties zijn, die met elkaar integreren. Om deze reden is het niet voldoende om alleen een app te registreren, maar zal een vPlan gebruiker de applicatie moeten autoriseren in zijn vPlan omgeving.

Als developer faciliteer je voor de vPlan gebruiker binnen je applicatie een knop om te koppelen met vPlan.
De vPlan gebruiker klikt op de knop, waarna de gebruiker verwezen wordt naar bijvoorbeeld:
https://developer.mostwanted.io/api/v1/oauth/authorize?client_id=90e1af5b-40ee-4d15-9b15-643b0360c581&redirect_uri=http:%2F%2Flocalhost:8080%2Foauth&response_type=code
De client_id en redirect_uri in bovenstaande voorbeeld URL vervang je met de gegevens die je hebt gehad bij het registreren in voorgaande hoofdstuk. De redirect_uri mag eventueel verlengd worden voor latere doeleinden.
Tip
De opbouw van de url is beschreven in Get authorization in de API documentatie.
vPlan stuurt de gebruiker door naar het inlog scherm.
De gebruiker logt nu in met zijn vPlan credentials.
Gebruiker geeft antwoord op de vraag of deze de integratie wil autoriseren voor vPlan. Voorbeeld:
vPlan verwijst de gebruiker door naar de redirect pagina die bij de oAuth registratie is opgegeven.
Aangezien de authorization_code +/- 10 minuten geldig is, wisselt je als developer de code in voor een token.
Tip
Zie Token Exchange in de API documentatie voor meer details.
Als developer sla je de refresh_token encrypted op bij de klant. Deze refresh_token is op dit moment één jaar geldig.

Herhalende verbinding

Nu de refresh_token is opgeslagen, kan deze gebruikt wordt om een access token op te halen en de normale koppeling te laten verlopen.
Er zijn een aantal momenten denkbaar wanneer er verbinding gemaakt zal worden:

Er wordt in de gekoppelde app een actie uitgevoerd die informatie van vPlan vereist, of informatie naar vPlan stuurt.
Via een geplande interval wordt er periodiek data naar vPlan gestuurd of uit vPlan opgehaald.

Door de refresh token is er geen gebruiker interactie meer nodig om de verbinding met vPlan op te zetten.
Wanneer er data van of naar vPlan nodig is, zijn er de volgende stappen:

Als developer wissel je de refresh_token in voor een access token
Let op
Een refresh_token is maar één keer bruikbaar.
vPlan stuurt een access token en een nieuwe refresh token
Je slaat de nieuwe refresh token encrypted op bij de klant.
Je maakt verbinding met de vPlan API om de benodigde acties uit te voeren.

API key

In vPlan kun je als gebruiker met de Administrator rechten eenvoudig een API key aanmaken. Een API key geeft je snel toegang tot de API van vPlan.
Om een API key aan te maken volg je de volgende stappen in vPlan.

In de linker menubalk in vPlan ga je naar Configuratie.
In de configuratie, klik je in de linker menubalk op Ontwikkelaars.
Rechts naast het kopje API keys klik je op het plus icoontje.
Geef je API key een naam en klik op Opslaan.
Er verschijnt een pop-up scherm waarin je API key eenmalig volledig getoond wordt. Kopieer de API key met de daarvoor bestemde knop en sla deze veilig op.
Om een API key te verwijderen kun je op een later moment altijd weer terug gaan naar het menu Ontwikkelaars. In dat menu klik je op de naam van je API key en in het scherm wat volgt klik je op Verwijderen.

Tip

In het Ontwikkelaars menu kun je tijdens het gebruik van de API altijd zien hoeveel API requests je per dag gebruikt.

Vervang regelmatig je API key

API keys zijn statische sleutels die toegang geven tot de gegevens in vPlan. We raden daarom aan om, net als bij wachtwoorden, regelmatig een API key te vervangen. Daarnaast is het verstandig om niet gebruikte API keys te verwijderen.

Let op

Een API key wordt gebruikt door een integratie die door jou zelf, of door een partner van vPlan is ontwikkeld. Zorg dat de beheerder van de integratie met de juiste kennis en kunde de API key vervangt.

Hieronder wordt uitgelegd welke stappen je kunt volgen om een API key te vervangen.

Geef bij de beheerder of partner aan dat je de API key wil gaan veranderen
Ga in vPlan naar Configuratie
Ga naar het kopje Ontwikkelaars </>
Voeg een nieuwe API key toe via het plus icoontje
Geef de nieuwe sleutels door aan de beheerder of partner
Wacht op het akkoord van de beheerder of partner
Wacht vervolgens nog één of twee dagen
Controleer of de datum en het tijdstip van de 'laatst gebruikt' kolom bij de oude API key niet meer bijgewerkt is
Verwijder de oude API key