MKG logo
Inloggen

Hoe werken MKG API-aanroepen?

In deze handleiding lees je in detail over aanroepen via de MKG API. We behandelen onder andere de opbouw van URL's, hoe je meerdere of specifieke records aanroept en hoe je filters gebruikt.

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

 

Voor informatie over HTTP-statuscodes, zie 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.

De maximale lengte van de URL is 8000 karakters na de encoding.

 

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 Data dictionary in de MKG Client voor het achterhalen van endpoints, velden, primary keys, verzamelingen en services.

 

Voor informatie over endpoints, velden en acties, zie onze Data dictionary.

 

Datatypes

In de Data dictionary zijn bij de velden van een endpoint de volgende datatypen (kolom: Type) terug te vinden.

Type Omschrijving Formaat Voorbeeld
aantal Elk getal, met of zonder decimalen. Negatief mogelijk. ->>>>>9.99 1000.15 of -1500
integer Alleen hele getallen, dus geen decimalen en niet negatief. * 120
bedrag Elk getal, met of zonder decimalen. Negatief mogelijk. ->>>,>>>,>>9.99 1000.15 of -1500
percentage Elk getal, met of zonder decimalen. Negatief mogelijk.  ->>9.99 80.15 of -22
logical True of false true/false true of false
datum Jaar, maand, dag, gescheiden door een liggend streepje. YYYY-MM-DD "2025-03-25"
character Kan uit cijfers, letters en speciale tekens bestaan.  x(*) "Voorbeeld tekst!"
omschrijving Kan uit cijfers, letters en speciale tekens bestaan. Maximaal 40. x(40) "Voorbeeld tekst!"
memo Kan uit cijfers, letters en speciale tekens bestaan. Maximaal 2500. x(2500) "Voorbeeld tekst!"

*In de data dictionary vind je meer informatie bij de velden van een endpoint in de kolom 'Formaat'.

 

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

 

Postman-collectie

 

Voor voorbeelden van API-aanroepen, zie onze Postman API-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
FieldList Door komma's gescheiden lijst met velden, waarvan de waarde wordt teruggegeven.
Filter Filter dat wordt toegepast op de data.
NumRows Aantal regels dat maximaal als resultaat mag worden teruggegeven.
SkipRows Aantal regels dat moet worden overgeslagen.

Sort

 Door komma's gescheiden lijst met velden waarop moet worden gesorteerd. Met een minteken voor het veld wordt er aflopend gesorteerd.

 

Specifiek record

Een 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 ander 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:

Operator Filter
= gelijk aan opgegeven waarde
< kleiner dan opgegeven waarde
> groter dan opgegeven waarde
<= kleiner dan of gelijk aan opgegeven waarde
>= groter dan of gelijk aan opgegeven waarde
in een met een opgegeven komma gescheiden lijst met waardes
NotIn een met 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 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.

Voorbeeld voor het ophalen van verkooporderregels welke zijn aangemaakt in de afgelopen 30 dagen en nog niet geleverd zijn:

GET {{restUrl}}/Documents/vorh?Filter=sys_dat_aanm >= Today(-30) AND vorr_leveren_afgewerkt = false

 

Paginasering (NumRows & SkipRows)

Bij een GET aanroep met meer dan 1000 resultaten zullen alleen de eerste 1000 resultaten getoond worden. Door gebruik te maken van NumRows en SkipRows kunnen de volgende 1000 records opgehaald worden.

Indien geen NumRows wordt meegegeven zal MKG NumRows=100 toepassen.

Voorbeeld:

Eerste 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=0

Volgende 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=1000

Volgende 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=2000

 

Na de resultaten zal een voorstel aanroep gedaan worden voor de volgende 1000 records of de vorige 1000 records indien er meer records beschikbaar zijn:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=2000

[...]
    "next": "[...]/Documents/rela?NumRows=1000;SkipRows=3000",
    "prev": "[...]/Documents/rela?NumRows=1000;SkipRows=1000"
[...]

 

Sort

Met de sortering parameter kan een lijst sortering meegegeven worden. Standaard is deze oplopend. Door er een - voor de veldnaam te zetten wordt de sortering aflopend toegepast.

GET {{restUrl}}/Documents/rela?Sort=rela_naam,-rela_num

 

Zoeken

Met de zoeken parameter kan een zoekfunctie meegegeven worden. Hierdoor zullen enkel de records die voldoen aan de zoekfunctie worden meegenomen in de resultaten.

GET {{restUrl}}/Documents/rela/?Filter=Search = "Search text"&FieldList=rela_num,rela_naam

 

PUT-aanroep

Voor het aanpassen van gegevens wordt gebruik gemaakt van een PUT-aanroep. Hiermee kunnen records gewijzigd worden maar kunnen ook services mee worden aangeroepen.

Specifiek record:

Een specifiek record van een endpoint kan worden aangepast 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. Met het aanpassen is het ook mogelijk om een body in te vullen met de informatie die je wil aanpassen van de record.

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

Body:

{
    "request": {
        "InputData": {
            "{{Tabel}}": [
                {
                    "{{Field}}": "{{information to change to}}"
                }
            ]
        }
    }
}

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

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

Body:

{
    "request": {
        "InputData": {
            "vorh": [
                {
                    "vorh_ref_onze": "Changed our reference"
                }
            ]
        }
    }
}

 

POST-aanroep

Voor het aanmaken van een nieuwe record wordt gebruik gemaakt van een POST-aanroep. Hiermee kunnen records aangemaakt worden.

Record:

Een record van een endpoint kan worden aangemaakt door een endpoint op te geven en hierbij een body in te vullen met de informatie die aangemaakt moet worden. In de module Data dictionary in MKG kunnen de endpoints, velden en ook de primary key worden opgevraagd.

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

Body:

{
    "request": {
        "InputData": {
            "{{Tabel}}": [
                {
                    "{{Field}}": "{{information}}"
                }
            ]
        }
    }
}

Voorbeeld voor het aanmaken van een verkooporder in administratie 1 voor debiteur 30002:

POST {{restUrl}}/Documents/vorh/

Body:

{
    "request": {
        "InputData": {
            "vorh": [
                {
                    "admi_num": 1,
                    "debi_num": 30002,
                    "vorh_ref_onze": "Our reference",
                    "vorh_ref_uw": "Customer reference",
                    "vorh_bestelcode_extern": "Customer order code"
                }
            ]
        }
    }
}

 

Profielen
In MKG kun je gebruikmaken van profielen om standaardwaarden vooraf in te vullen bij het aanmaken van nieuwe records, zoals artikelen of verkooporders. Dit is vooral handig bij herhalende invoer of veelgebruikte instellingen, omdat het aanmaken van nieuwe gegevens hiermee sneller, consistenter en minder foutgevoelig verloopt. Ook via de API kunnen deze profielen worden toegepast. Door bij een POST-aanroep een Profile-parameter mee te geven, worden de bijbehorende standaardinstellingen automatisch geladen. Je hoeft dan niet handmatig alle veldwaarden mee te geven, omdat de meeste gegevens al vooraf zijn ingevuld op basis van het profiel.

Beschikbare profielopties:

  • Profile=0: Er wordt géén profiel toegepast (leeg profiel).
  • Profile=-1: Het standaard MKG-profiel wordt toegepast.
  • Profile=1 en hoger: Een zelf aangemaakt profiel, waarbij het nummer overeenkomt met de profielkeuze zoals ingericht in MKG.

Een voorbeeld van het aanmaken van een artikel met een profiel via de API:

POST {{restUrl}}/Documents/arti/?Profile=-1

 

DEL-aanroep

Voor het verwijderen van een record wordt gebruik gemaakt van een DEL-aanroep. Hiermee kunnen records verwijderd worden.

Specifiek record:

Een specifiek record van een endpoint kan worden verwijderd 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.

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

Voorbeeld voor het verwijderen van verkooporder 30250018 uit administratie 1:

DEL {{restUrl}}/Documents/vorh/1+30250018

 

Services

Binnen MKG kunnen verschillende services worden gebruikt. Deze services bootsen processen binnen MKG na zoals het factureren of een pakbon aanmaken. Voor het uitvoeren van services is wordt gebruik gemaakt van een PUT-aanroep. De services die je kan uitvoeren zijn te vinden in de Data dictionary module, als je hier een tabel selecteert kan je navigeren naar API acties. Hier staan alle services die op deze tabel kunnen worden uitgevoerd inclusief uitleg hoe ze moeten worden opgebouwd. Standaard geef je met de PUT de endpoint en primary key mee, sommige services hebben echter ook een body nodig.

PUT {{restUrl}}/Documents/{{endpoint}}/{{Primay Key}}/Service/{{Service}}

Voorbeeld voor het uitvoeren van de service plannen van productieorder 60250059 met productieorderregel 1 in administratie 1:

PUT {{restUrl}}/Documents/prdr/1+60250059+1/Service/s_actie_plannen

Voorbeeld voor het backflushen van verkooporder 30250018 met verkooporderregel 1 in administratie 1:

PUT {{restUrl}}/Documents/vorr/1+30250018+1/Service/CreateBackflush

Body:

{
    "request": {
        "InputData": {
            "StockBackFlush": [
                {
                    "t_afgewerkt": true,
                    "t_dat_backflush": "2025-12-27",
                    "t_ingave_aantal": 1,
                    "t_ingave_eenheid": "st.",
                    "RowKey": 1
                }
            ]
        }
    }
}

 

Algemene aanroepen

 

Gebruiker, administratie & boekjaar

Er zijn een aantal calls aanwezig die gebruikt kunnen worden om informatie te controleren, zoals welke gebruiker ingelogd is met de api. Hiervan zijn onderstaand een aantal voorbeeldcalls die gebruikt kunnen worden:

Voor het controleren van de gebruiker wordt deze call gebruikt:

GET {{restUrl}}/User?FieldList=gebr_code,gebr_naam

Voor het nakijken in welke administratie en boekjaar de API ingelogd is wordt deze call gebruikt:

GET {{restUrl}}/Settings?Settings=Administration,FiscalYear,Language

 

Autorisatie gebruiker opvragen

Het opvragen van autorisaties werkt vergelijkbaar met de autorisatieoverzicht‑module in MKG. In de DocumentList geef je op voor welke autorisaties je een controle wilt uitvoeren.

  • Alleen toegang tot een tabel controleren:
    Geef enkel de tabelnaam mee, bijvoorbeeld:
    "rela"
  • Controleren of de gebruiker ook mutaties mag uitvoeren:
    Voeg dan de service Maintenance toe. Dit wordt dan:
    "rela,Maintenance"

Meerdere tabellen kun je opgeven door deze met een puntkomma (;) te scheiden. Zo kun je eenvoudig naar een volgende tabel doorgaan.
Daarnaast kun je ook services meegeven om te controleren of de gebruiker daar rechten op heeft, bijvoorbeeld:
s_term_plan.

Voor het opvragen van welke autorisatie een gebruiker heeft wordt deze call gebruikt:

GET {{restUrl}}/Authorization?DocumentList=rela,Maintenance;vorh,Maintenance,s_term_plan

 

Meta gegevens opvragen

Voor het opvragen van de metagegevens van een veld gebruik je de volgende call:

GET {{restUrl}}/Meta/{{Document}}/{{Field}}