Getting started
Inhoudsopgave |
Inleiding tot de MKG API
Met behulp van de MKG API is het mogelijk om externe programma's of software te koppelen aan MKG. In dit artikel leggen we uit hoe de MKG API werkt, waar je deze voor kunt gebruiken en welke ondersteuning je mag verwachten. Lees meer
Stappenplan voorbereiding MKG API
Stap 1. MKG API setup Voordat je met de MKG API kunt werken dient eerst de setup te zijn afgerond. Deze setup bestaat uit de installatie van Tomcat, de configuratie van de API met een nieuw of bestaand SSL-certificaat en de ontsluiting van de nieuwe functionaliteit. Deze handleiding bevat tevens enkele probleemoplossingen. Lees meer |
Stap 2. MKG Exchange licentie. Voor het kunnen verbinden met de MKG API heb je de MKG Exchange licentie nodig. Deze licentie kan als read only (R) of als full control (CRUD) worden afgenomen. Heb je nog geen licentie? Neem dan contact op met de afdeling Verkoop. |
Stap 3. API applicaties. In MKG dient in de module API applicaties minimaal één nieuwe applicatie aangemaakt te worden. Ons advies is om per applicatie een eigen API applicatie aan te maken. Per API applicatie wordt een sleutel gegenereerd, een API key. |
Stap 4. MKG gebruikers. We adviseren om per API applicatie minimaal één aparte gebruiker aan te maken binnen MKG, zodat je hierop later eenvoudig de autorisatie kunt wijzigen. Ook zijn aangemaakte en gewijzigde records met behulp van de API makkelijker te identificeren.
|
Stap 5. Controle bereikbaarheid. Controleer voordat er met de MKG API begonnen wordt of deze vanuit de browser benaderbaar is zonder certificaatfouten. Dit doe je door in de browser de basis-url in te voeren:
Het resultaat dient een inlogformulier te zijn, waarbij de browser geen certificaatfouten teruggeeft. |
Aanroepen
Om onderstaande aanroepen te testen adviseren we je om gebruik te maken van het API platform Postman. |
1. API login
Met deze aanroep kan aangemeld worden op de MKG API. In geval van een succesvolle aanmelding (HTTP status 200) geeft de aanroep een cookie met een JSESSIONID terug. Deze zal in vervolgaanroepen moeten worden meegegeven in de header.
POST {{protocol}}://{{server}}:{{poort}}/mkg/static/auth/j_spring_security_check
Headers
- Content-Type = application/x-www-form-urlencoded
- Accept = application/json
Body (x-www-form-urlencoded)
j_username:{{username}}
j_password:{{password}}
2. Basis-url
{{restUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/web/v3/MKG
3. Een record ophalen (GET)
Zodra er is ingelogd, kan er een gegevensaanvraag gedaan worden door middel van een GET request. Dit maken we duidelijk aan de hand van een voorbeeld: het uitlezen van de relatietabel met een parameter, waardoor het resultaat slechts 10 records zal bevatten.
GET {{restUrl}}/Documents/rela/?NumRows=10
In de header van deze aanroep dienen de volgende waardes meegegeven te worden:
- De cookie inhoud met de JSESSIONID. Deze wordt aangeboden na een succesvolle aanmelding.
Cookie: JSESSIONID=[...]
- De sleutel van de API applicatie uit MKG.
X-CustomerID: {{apikey}}
Het resultaat is HTTP statuscode 200 met een JSON beginnende met:
{
"response": {
"ResultData": [
{
"rela": [
{
4. Een record wijzigen (PUT)
Met een PUT request is het mogelijk om bestaande gegevens te wijzigen. Dit maken we duidelijk aan de hand van een voorbeeld: het aanpassen van het memoveld van een relatie.
PUT {{restUrl}}/Documents/rela/1/
In de header van deze aanroep dienen de volgende waardes meegegeven meegegeven te worden:
Cookie: JSESSIONID=[...]
X-CustomerID: {{apikey}}
In de body van deze aanroep dienen de te wijzigen velden op de volgende manier meegegeven te worden:
{
"request":{
"InputData":{
"rela":[
{
"rela_memo":"Nieuwe memotekst"
}
]
}
}
}
Het resultaat is HTTP statuscode 200 met een JSON met de key en het gewijzigde veld met de gewijzigde waarde:
[...]
"rela_num": 1,
"rela_memo": "Nieuwe memotekst"
[...]
5. Een record toevoegen (POST)
Met een POST request is het mogelijk om nieuwe gegeven op te voeren. Dit maken we duidelijk aan de hand van een voorbeeld: het aanmaken van een relatie.
POST {{restUrl}}/Documents/rela/
In de header van deze aanroep dienen de volgende waardes meegegeven meegegeven te worden:
Cookie: JSESSIONID=[...]
X-CustomerID: {{apikey}}
In de body van deze aanroep dienen de te vullen velden op de volgende manier meegegeven te worden:
{
"request": {
"InputData": {
"rela": [
{
"rela_naam": "Naam relatie",
"rela_www": "www.domeinnaam.eu"
}
]
}
}
}
Het resultaat is HTTP statuscode 200 met een JSON met de key en het gewijzigde veld met de gevulde velden:
[...]
"rela_num": *,
"rela_naam": "Naam relatie",
"rela_www": "www.domeinnaam.eu"
[...]
6. Een record verwijderen (DEL)
Met een DEL request kan een record verwijderd worden. Dit maken we duidelijk aan de hand van een voorbeeld: het verwijderen van een relatie.
DEL {{restUrl}}/Documents/rela/1
In de header van deze aanroep dienen de volgende waardes meegegeven meegegeven te worden:
Cookie: JSESSIONID=[...]
X-CustomerID: {{apikey}}
Het resultaat is HTTP statuscode 200.
Voorbeelden van aanroepen
Diverse voorbeeld aanroepen
Basisurl:
{{authUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/static/auth
{{restUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/rest/v1/MKG
Inloggen:
POST {{authUrl}}/j_spring_security_check?j_username={{gebruikersnaam}}&j_password={{wachtwoord}}
Uitloggen:
POST {{authUrl}}/j_spring_security_logout
Aangemelde gebruiker:
GET {{restUrl}}/User
Aangemelde administratie, boekjaar en taal:
GET {{restUrl}}/Settings?Settings=Administration,FiscalYear,Language
GET requests
Voor elke van onderstaande aanroepen zal in de header de volgende waardes meegeven moeten worden:
Cookie: JSESSIONID=[...]
X-CustomerID: {{apikey}}
Mogelijke GET parameters:
FieldList: | Komma gescheiden lijst van velden, waarvan de waarde teruggegeven wordt. |
Filter: | Filter dat toegepast wordt op de data. |
NumRows: | Aantal regels dat maximaal als resultaat teruggegeven mag worden. |
Sort: | Komma gescheiden lijst van velden waarop gesorteerd moet worden. met een min teken voor het veld zal er aflopend gesorteerd worden. |
Uitlezen endpoint.
GET {{restUrl}}/Documents/rela/
Uitlezen specifiek endpoint met de waarde van de key bekend.
GET {{restUrl}}/Documents/rela/1/
Uitlezen endpoint met beperking van het aantal resultaten (parameter NumRows).
GET {{restUrl}}/Documents/rela/?NumRows=10
Uitlezen specifiek endpoint met waarde van specifiek veld (parameter Filter).
GET {{restUrl}}/Documents/rela?Filter=rela_naam = "MKG Nederland bv"
Uitlezen specifiek endpoint met waarde van meerdere specifieke velden (parameter Filter).
GET {{restUrl}}/Documents/rela?Filter=rela_actief = true AND rela_plaats = "HENGELO"
Uitlezen endpoint met beperking aantal velden in het resultaat (parameter FieldList).
GET {{restUrl}}/Documents/rela?FieldList=rela_num,rela_naam
Uitlezen endpoint met sortering op specifiek veld (parameter Sort).
GET {{restUrl}}/Documents/rela?Sort=rela_naam
Uitlezen endpoint met diverse parameters.
GET {{restUrl}}/Documents/rela?Filter=rela_actief = true AND rela_plaats = "HENGELO"&NumRows=10&FieldList=rela_num,rela_naam,rela_plaats&Sort=rela_naam
Uitlezen onderliggende verzameling vanuit een specifiek endpoint.
GET {{restUrl}}/Documents/rela/1/rela_adrs
Uitlezen onderliggende verzameling vanuit een specifiek endpoint met waarde van de key bekend.
GET {{restUrl}}/Documents/rela/1/rela_adrs/1
Operators bij het gebruik van de Filter parameter:
Operator | Filter |
---|---|
= | gelijk aan opgegeven waarde |
< | kleiner dan opgegeven waarde |
> | groter dan opgegeven waarde |
<= | kleiner gelijk dan opgegeven waarde |
>= | groter gelijk dan opgegeven waarde |
in | een van een opgegeven komma gescheiden lijst met waardes |
NotIn | niet een van een opgegeven komma gescheiden lijst met waardes |
startswith | begint met opgegeven waarde |
endswith | eindigt op opgegeven waarde |
contains | bevat opgegeven waarde |
Functies bij het gebruik van de Filter parameter op een datumveld:
Functie | Filter |
---|---|
= Yesterday | gelijk aan gisteren |
= Today | gelijk aan vandaag * |
= Tomorrow | gelijk aan morgen |
= GreaterThanToday | in de toekomst * |
= LessThanToday | in het verleden * |
= Prev7Days | in de afgelopen 7 dagen |
= Next7Days | in de komende 7 dagen |
= PrevDays() | in de afgelopen # dagen |
= NextDays() | in de komende # dagen |
= PrevWeek | in de vorige week |
= ThisWeek | in de huidige week |
= NextWeek | in de komende week |
= PrevWeeks() | in de afgelopen # weken |
= NextWeeks() | in de komende # weken |
= PrevMonth | in de afgelopen maand |
= ThisMonth | in de huidige maand |
= NextMonth | in de komende maand |
= PrevMonths() | in de afgelopen # maanden |
= NextMonths() | in de komende # maanden |
= PrevQuarter | in het afgelopen kwartaal |
= ThisQuarter | in het huidige kwartaal |
= NextQuarter | in het komende kwartaal |
= PrevQuarters() | in de afgelopen # kwartalen |
= NextQuarters() | in de komende # kwartalen |
= PrevYear | in het afgelopen jaar |
= ThisYear | in het huidige jaar |
= NextYear | in het komende jaar |
= PrevYears() | in de afgelopen # jaren |
= NextYears() | in de komende # jaren |
= PrevFiscalYear | in het afgelopen boekjaar |
= ThisFiscalYear | in het huidige boekjaar |
= NextFiscalYear | in het komende boekjaar |
= PrevFiscalYears() | in de afgelopen # boekjaren |
= NextFiscalYears() | in de komende # boekjaren |
* Optioneel kan hier een plus of min aantal opgegeven worden. Voorbeelden: sys_dat_aanm = Today(3) --> vandaag plus 3 dagen
Meerdere filters kunnen gekoppeld worden doormiddel van de operators AND en OR.
PUT requests
Voor elke van onderstaande aanroepen zal in de header de volgende waardes meegeven moeten worden:
Cookie: JSESSIONID=[...]
Content-Type: application/json
X-CustomerID: {{apikey}}
Aanpassen meerdere waardes van een record.
PUT {{restUrl}}/Documents/rela/1/
{
"request":{
"InputData":{
"rela":[
{
"rela_memo":"Nieuwe memotekst"
}
]
}
}
}
Aanpassen meerdere waardes van een record van een onderliggende verzameling.
PUT {{restUrl}}/Documents/vorh/30220001/vorh_vorr/1
Body:
{ "request":{ "InputData":{ "vorr":[ { "vorr_oms_1":"Gewijzigde omschrijving", "vorr_order_aantal":99, "vorr_bruto_prijs_ov":23.45, "vorr_op_nacalculatie":false } ] } } }
POST requests
Voor elke van onderstaande aanroepen zal in de header de volgende waardes meegeven moeten worden:
Cookie: JSESSIONID=[...]
Content-Type: application/json
X-CustomerID: {{apikey}}
Aanmaken van een record.
POST {{restUrl}}/Documents/rela/
Body:
{ "request":{ "InputData":{ "rela":[ { "rela_naam":"Nieuwe bedrijfsnaam", "rela_memo":"Nieuwe memotekst" } ] } } }
Aanmaken van een record.
POST {{restUrl}}/Documents/vorr/
Body:
{ "request":{ "InputData":{ "vorr":[ { "vorh_num":"30220001", "vorr_oms_1":"Nieuwe omschrijving", "vorr_order_aantal":99, "vorr_bruto_prijs_ov":23.45, "vorr_op_nacalculatie":false } ] } } }
Aanmaken record bij een onderliggende verzameling.
POST {{restUrl}}/Documents/vorh/30220001/vorh_vorr/
Body:
{ "request":{ "InputData":{ "vorr":[ { "vorr_oms_1":"Nieuwe omschrijving", "vorr_order_aantal":99, "vorr_bruto_prijs_ov":23.45, "vorr_op_nacalculatie":false } ] } } }
DEL requests
Voor elke van onderstaande aanroepen zal in de header de volgende waardes meegeven moeten worden:
Cookie: JSESSIONID=[...]
X-CustomerID: {{apikey}}
Verwijderen record.
DEL {{restUrl}}/Documents/rela/1
Kenniscentrum | Gerelateerd: |
- Gepubliceerd:22 dec 2021 12:49
- TypeHandleidingen
- Categorie
- Product
- BeschikbaarheidOpenbaar