Business Central koppeling met je webshop: ook als je nog op Navision draait

Wat is Business Central en wie gebruikt het?

Dynamics 365 Business Central is het ERP-pakket van Microsoft voor het mkb: financieel, verkoop, inkoop, voorraad, magazijn en productie. Het is de opvolger van Dynamics NAV, dat daarvoor Navision heette. In Nederland draait het bij veel groothandels en productiebedrijven, en op de werkvloer heet het vaak nog steeds Navision.

Voor een koppeling zijn er twee varianten. Business Central online draait bij Microsoft; de API staat er altijd aan en wordt maandelijks bijgewerkt. Business Central on-premises en Navision draaien op een eigen server of bij een hostingpartij; daar bepaalt de beheerder wat er openstaat. Eén omgeving kan meerdere bedrijven bevatten, online maximaal 300, en elke aanroep noemt het bedrijf waar hij voor bedoeld is.

Wat je met Business Central koppelt

Business Central is in de meeste koppelingen leidend voor artikelen, voorraad, prijzen en facturen. De webshop is leidend voor de order en voor nieuwe klanten.

Een order gaat in één verzoek naar binnen, met de regels erin. Dit is order 10482 van Bakker Installatie B.V.:

POST /v2.0/production/api/v2.0/companies(b18aed47-c385)/salesOrders
Host: api.businesscentral.dynamics.com
Authorization: Bearer eyJ0eXAi...
Content-Type: application/json

{
  "customerNumber": "10432",
  "externalDocumentNumber": "WEB-10482",
  "orderDate": "2026-10-02",
  "shipToAddressLine1": "Dorpsstraat 12 A",
  "shipToPostCode": "1234 AB",
  "shipToCity": "Utrecht",
  "salesOrderLines": [
    { "lineType": "Item", "lineObjectNumber": "KB-2210",
      "quantity": 12, "unitPrice": 17.08 }
  ]
}

Het webshopordernummer gaat in externalDocumentNumber. Dat veld komt terug op de verzending en de factuur, zodat de koppeling een levering aan de juiste webshoporder kan hangen. Welke velden per stroom meegaan staat op orders, klanten en verzending.

Voor facturen aan overheden en grote afnemers heeft Business Central het PEPPOL-formaat voorgeconfigureerd; zie Peppol koppeling. Voor Shopify levert Microsoft een eigen Shopify Connector mee, alleen voor Business Central online. Wat die wel en niet doet staat op Shopify Business Central koppeling.

Hoe Business Central data vrijgeeft

API v2.0, een eigen API-pagina of webservices

De standaard-API heet API v2.0 en telt 87 resources. Het adres voor Business Central online is https://api.businesscentral.dynamics.com/v2.0/{omgeving}/api/v2.0, on-premises is het https://{server}:7048/{instantie}/api/v2.0. On-premises staat de API standaard uit en moet de poort door de firewall bereikbaar zijn.

Wat er niet in zit, komt via een eigen API-pagina: een pagina in een extensie, geschreven in AL, met een eigen adres onder /api/{uitgever}/{groep}/{versie}. Uitbreiden van de standaard-API met extra velden kan volgens Microsoft niet. Navision en oudere installaties bieden SOAP- en OData-webservices op pagina's en codeunits. Microsoft kondigt aan SOAP in Business Central op termijn uit te faseren, dus nieuwe koppelingen bouwen wij op de API.

Inloggen via Microsoft Entra ID

Business Central online accepteert alleen OAuth 2.0 via Microsoft Entra ID. Inloggen met een webservicesleutel (basic authentication) wordt online sinds oktober 2022 niet meer ondersteund. Een koppeling die zonder mens draait gebruikt de client credentials flow: een app-registratie in Entra ID met de permissie API.ReadWrite.All, die in Business Central op de pagina Microsoft Entra applications rechten krijgt. Voor zo'n applicatiegebruiker is geen gebruikerslicentie nodig. De rechten in Business Central bepalen wat de koppeling mag lezen en schrijven, dus die houden we zo smal als de stromen toelaten.

De limieten van Business Central online

De volledige lijst staat in de operationele limieten van Business Central online. On-premises gelden de instellingen van je eigen server.

In de praktijk bepaalt het aantal gelijktijdige verzoeken de doorvoer, niet de 6.000. De rekensom voor een achterstand van 3.000 orders na een storing, als het aanmaken van één order 0,8 seconde duurt (een aanname; het hangt af van het aantal regels en de extensies in je omgeving). Met 5 verzoeken tegelijk zijn dat 5 / 0,8 = 6,25 orders per seconde, dus 375 per minuut. De 3.000 orders zijn in 8 minuten verwerkt en gebruiken 1.875 verzoeken per 5 minuten, ruim onder de 6.000. Stuurt de koppeling er 20 tegelijk, dan gaat het niet sneller: 15 wachten in de rij. Voor meer doorvoer raadt Microsoft aan het werk over meerdere applicatiegebruikers te verdelen. Lezen gaat de andere kant op snel: 40.000 artikelen passen in 2 pagina's van 20.000.

Webhooks die na drie dagen verlopen

Business Central verstuurt een melding als een record wijzigt. De melding bevat alleen welk record het is; de gegevens haalt de koppeling daarna op. Een abonnement verloopt na drie dagen en moet voor die tijd met een PATCH verlengd worden. Bij het aanmaken en bij elke verlenging stuurt Business Central een validationToken dat de ontvanger moet terugsturen. Een koppeling die het verlengen één keer mist, krijgt geen meldingen meer en geen foutmelding. Daarom draait er naast de webhooks een controleronde met een filter op lastModifiedDateTime. Zie wat is een webhook.

Waar het bij Business Central op vastloopt

Verplichte boekingsgroepen die de webshop niet kent

Business Central boekt een verkoop op basis van boekingsgroepen. De combinatie van de bedrijfsboekingsgroep van de klant en de productboekingsgroep van het artikel bepaalt de omzetrekening; de klantboekingsgroep bepaalt de debiteurenrekening. Een webshop levert geen van die waarden, en de resource customer heeft er geen velden voor. Een klant die zonder boekingsgroepen is aangemaakt, levert een order op die niet geboekt kan worden.

De oplossing zit in Business Central zelf. Op de pagina API Setup koppel je een configuratiesjabloon aan de klanten-API, met een voorwaarde erbij. Velden die de aanroep leeg laat worden uit het sjabloon gevuld. Een Nederlandse zakelijke klant, een klant in een ander EU-land en een consument krijgen elk een eigen sjabloon. Het patroon staat in verplichte velden die de bron niet heeft.

Prijzen en voorraad: wat de API weglaat

Een artikel heeft in de API één unitPrice. Prijslijsten per klant of klantprijsgroep, met minimumaantal en geldigheidsdatum, staan wel in Business Central en niet in de standaard-API. Voor een B2B-webshop is dat de kern, dus daar komt een eigen API-pagina voor. Zie klantspecifieke prijzen.

Hetzelfde geldt voor voorraad. Het veld inventory is alleen-lezen en geeft één totaal over alle locaties. Tellen een buitenmagazijn of een showroom niet mee voor de webshop, dan is dat getal te hoog. Welke locaties meetellen en of gereserveerde voorraad eraf gaat, wordt per koppeling vastgelegd; zie meerdere magazijnen.

Varianten, adressen en GUID's

Een variant is in Business Central een itemVariant met een eigen code onder een artikel. De webshop kent één SKU per variant. De koppeling legt vast hoe artikelnummer en variantcode samen de SKU vormen, bijvoorbeeld KB-2210-ZW met een scheidingsteken, en splitst hem bij een order weer.

Een adres heeft twee regels, addressLine1 en addressLine2, en geen los veld voor het huisnummer. Dat is omgekeerd aan systemen die straat en huisnummer scheiden; zie adresvelden mappen.

Elke resource heeft een GUID als sleutel. Een orderregel verwijst naar het artikel met itemId, of met lineType en lineObjectNumber als je het artikelnummer gebruikt. Bij een wijziging stuurt de koppeling de versie van het record mee in de header If-Match. Is het record intussen door een medewerker gewijzigd, dan weigert Business Central de aanroep en haalt de koppeling eerst de nieuwe stand op.

Platformen die we aan Business Central koppelen

De koppeling wordt gebouwd op jouw Business Central, met jouw extensies en boekingsgroepen. Per combinatie staat op een eigen pagina wat er specifiek speelt:

• Magento Business Central koppeling
• WooCommerce Business Central koppeling
• Shopify Business Central koppeling

De platformen zelf staan op WooCommerce koppeling en Shopify koppeling. Andere ERP-systemen: Exact Online koppeling en AFAS webshop koppeling. Het overzicht van alle stromen staat op koppelingen, de ERP-kant in het algemeen op ERP koppeling met je webshop.

Wij bouwen de koppeling voor een vaste prijs, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor de livegang draait hij als dry run: je ziet per order welke klant, boekingsgroepen en regels in Business Central zouden ontstaan, zonder dat er iets wordt aangemaakt. Vertel welke versie je draait en welke webshop je hebt, dan hoor je welke gegevens via de standaard-API kunnen en waar een eigen API-pagina voor nodig is.