Hoe werken MKG API-aanroepen?

Voor deze handleiding gaan we ervan uit dat de MKG API is geïnstalleerd, de MKG Exchange-licentie is afgenomen, een API-key is aangemaakt en een gebruiker met de benodigde rechten is aangemaakt. Ga voor meer informatie naar de Getting Started.

Basis-URL

De basis-URL voor de MKG API v3 is op de volgende manier opgebouwd:

{{basisUrl}} = https://{{server}}:{{port}}/{{root}}

Voorbeeld: https://mkgapi.domeinnaam.nl:443/mkg

De server of de domeinnaam en de poort waarop de MKG API beschikbaar is, zijn binnen MKG op te vragen. Ga hiervoor binnen MKG links bovenin naar het Help-icoon (?) en kies vervolgens voor MKG API. Hier staan de API-servernaam en het API-poortnummer.

De poort is over het algemeen 443 of 8443, maar hier kan bij on-premise-installaties van afgeweken zijn.

Met de root kan worden gekozen voor de live omgeving of de oefenomgeving van MKG.

On-premise

Live omgeving: {{basisUrl}} = https://{{server}}:{{port}}/mkg
Oefenomgeving: {{basisUrl}} = https://{{server}}:{{port}}/mkgoefenclient

MKG Cloud

Live omgeving: {{basisUrl}} = https://saas*.mkg.eu:443/mkg
Oefenomgeving: {{basisUrl}} = https://saas*-oefen.mkg.eu:443/mkgoefenclient

Inloggen

Voor het inloggen met de MKG API is de volgende URL benodigd:

{{authUrl}} = {{basisUrl}}/static/auth

Om in te loggen gebruiken we de volgende aanroep:

POST {{authUrl}}/j_spring_security_check

Voorbeeld-URL: https://mkgapi.domeinnaam.nl:443/mkg/static/auth/j_spring_security_check 

Headers:
Accept: application/json
Content-Type: application/x-www-form-urlencoded 

Body:
j_username:{{username}}
j_password:{{password}}

Bij een succesvolle aanroep (HTTP-statuscode 200) zal in de response header een JSESSIONID worden teruggeven.

Set-Cookie: "JSESSIONID=[...].mkg"

Deze JSESSIONID zal bij elke vervolgaanroep moeten worden meegegeven in de header als:

Cookie: "JSESSIONID=[...].mkg"

Sessie

Als je succesvol bent ingelogd, wordt een sessie-ID teruggegeven. Deze sessie kan worden hergebruikt tot deze verlopen is. Over het algemeen verloopt een sessie 30 minuten na het laatste gebruik. Een verlopen sessie zal resulteren in een HTTP-statuscode 401.

HTTP-statuscodes

Opbouw aanroep

De URL voor een aanroep begint als volgt:

{{restUrl}} = {{basisUrl}}/web/v3/MKG

Aan de restUrl kan vervolgens het endpoint worden toegevoegd.

{{restUrl}}/Documents/{{endpoint}}

Een specifiek record van een endpoint kan worden opgevraagd door na het endpoint de primary key van het record toe te voegen.

{{restUrl}}/Documents/{{endpoint}}/{{Primary Key}}

Wanneer de primary key meerdere velden bevat, worden deze aan elkaar gekoppeld met het +-teken. Als alternatief kan de RowKey van het specifieke record worden gebruikt in plaats van de primary key. De RowKey is alleen op te vragen via de API en is niet bekend bij de gebruiker of in de MKG Client.

{{restUrl}}/Documents/{{endpoint}}/{{RowKey}}

URL Percent-Encoding

Voor verschillende gedeeltes van de URL gelden verschillende regels.

Voorbeeld URL:

https://{{server}}:{{port}}/mkg/web/v3/MKG/Documents/vorh/1+30240258?Fieldlist=vorh_num

path = /mkg/web/v3/MKG/Documents/vorh/1+30240258
query = Fieldlist=vorh_num

Path
Bij het opgeven van een primary key voor een specifiek record mag de alleen gebruik worden gemaakt van alfanumerieke tekens, spaties, koppeltekens en underscores ( [a-z] [A-Z] [0-9] SPACE - _ ). Het +-teken wordt gebruikt om de primary key op te bouwen.

Query
Voor het querygedeelte van de URL dient Percent-Encode te worden gebruikt, waarbij een spatie vertaald dient te worden naar een %20.

Headers

Bij elke aanroep moet in de headers de cookie worden gevuld met de sessie-ID. Daarnaast dient X-CustomerID te worden gevuld met de API-key uit MKG.

Cookie:  "JSESSIONID=[...].mkg"
X-CustomerID: {{APIKey}}
Accept: application/json
Content-Type: application/json

Voorbeeld GET-aanroep:

Voorbeeld voor het ophalen van verkooporder 30240258 uit administratie 1:

GET {{restUrl}}/Documents/vorh/1+30240258

Headers:

Cookie:  "JSESSIONID=1050E02F91B6EA25933ADDBE86B5B2955D7DF77FB53E.mkg"
X-CustomerID:  "ced6600c-e15a-eabd-8414-35844cd10b34"
Accept: application/json
Content-Type: application/json

Verzamelingen

Vanuit een endpoint zijn soms ook verzamelingen aanwezig. Met een verzameling kan vanuit het endpoint in een onderliggende tabel informatie worden opgehaald die behoort bij het endpoint.

GET {{restUrl}}/Documents/{{endpoint}}/{{primary_key}}/{{verzameling}}

Voorbeeld: Vanuit het endpoint Verkooporders (vorh) geeft de API door middel van de verzameling vorh_vorr alle aan deze verkooporder gekoppelde regels uit de Verkooporderregels (vorr) terug.

GET {{restUrl}}/Documents/vorh/1+30240258/vorh_vorr/

Om een specifieke regel vanuit de verzameling te selecteren, kan de volgende aanroep worden gebruikt:

GET {{restUrl}}/Documents/{{endpoint}}/{{primary_key}}/{{verzameling}}/{{key}}

Voorbeeld: Vanuit het endpoint Verkooporders (vorh) geeft de API door middel van de verzameling vorh_vorr met toevoeging van het regelnummer, verkooporderregel 2 uit de Verkooporderregels (vorr) terug behorend bij de verkooporder.

GET {{restUrl}}/Documents/vorh/1+30240258/vorh_vorr/2

Data dictionary

Ga naar onze Data dictionary in de MKG Client voor het achterhalen van endpoints, velden, primary keys, verzamelingen en services.

Veldnaam opvragen in MKG

Binnen de MKG Client kun je een veldnaam ophalen door in een veld van een formulier te gaan staan en op  Ctrl+F11  te klikken.

Postman-collectie

GET-aanroep

Voor het opvragen van gegevens wordt gebruikgemaakt van een GET-aanroep. Het is mogelijk om meerdere records op te halen of één specifiek record.

Parameters

Specifiek record

Specifiek record van een endpoint kan worden opgevraagd door na het endpoint de primary key of de RowKey van het record toe te voegen. In de module Data Dictionary in MKG kunnen de endpoints, velden en ook de primary key worden opgevraagd.

GET {{restUrl}}/Documents/{{endpoint}}/{{Primary Key}}

Voorbeeld voor het ophalen van verkooporder 30240258 uit administratie 1 met een aantal velden:

GET {{restUrl}}/Documents/vorh/1+30240258?FieldList=vorh_num,debi_num,vorh_ref_onze,vorh_ref_uw,vorh_dat_levering

FieldList

Met de FieldList-parameter worden de gewenste velden van het betreffende endpoint opgegeven waarvan de waarde moet worden teruggegeven. Wanneer geen FieldList wordt meegegeven, zal deze alleen de primary-key-velden teruggeven.

Het is mogelijk om door te punten naar een veld van een andere gekoppeld endpoint.

Voorbeeld voor het doorpunten vanuit de verkooporder (vorh) naar de debiteur (debi) om de debiteurnaam op te halen:

GET {{restUrl}}/Documents/vorh/1+30240258?FieldList=vorh_num,debi_num,debi_num.debi_naam

Filter

Met een fiter is het mogelijk om meerdere records van een endpoint op te vragen die aan een voorwaarde voldoen.

De volgende operators zijn mogelijk bij het gebruik van de Filter-parameter:

Functies bij het gebruik van de Filter-parameter op een datumveld:

* Optioneel kun je hier een plus- of min-aantal opgeven. Voorbeeld: sys_dat_aanm = Today(3) --> vandaag plus 3 dagen.

Meerdere filters kunnen worden gekoppeld door middel van de operators AND en OR.