Getting started

Voordat je met de MKG API aan de slag kunt, zul je een aantal voorbereidende klussen moeten doen. Zo zal eerst de technische installatie afgerond moeten zijn en moet je beschikken over de juiste licentie. Daarna kun je van start. Dit artikel helpt je op weg met een stappenplan en bevat een lijst met de belangrijkste aanroepen.

 


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.

  • De gebruiker dient 'actief' te zijn, een complex wachtwoord te hebben en toegang te hebben tot een administratie en een boekjaar.
  • Zorg ervoor dat de MKG gebruiker voldoende rechten heeft om de gewenste aanroepen uit te voeren.

 

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:

  • {{protocol}}://{{server}}:{{poort}}/mkg/web/v3/MKG

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: