Magento Business Central koppeling

Wat je tussen Magento en Business Central koppelt

Business Central is de bron voor artikelen, prijzen, voorraad en de boekhouding. Magento toont de catalogus en vangt de order. De koppeling verbindt zes stromen, elk met een vaste richting en aan beide kanten een vast endpoint.

Een Magento-order heeft twee nummers. entity_id is het nummer in elk API-pad. increment_id is het nummer dat de klant ziet, bijvoorbeeld 000010482. Het increment_id gaat naar externalDocumentNumber op de verkooporder: dat veld is in Business Central 35 tekens lang. Het entity_id bewaart de koppeling zelf, om later de zending terug te kunnen boeken. De algemene opzet van zo'n koppeling staat op ERP koppeling met je webshop.

Welk systeem is leidend, per gegeven

De verkoopbare voorraad is de enige regel waar Magento rekent en Business Central alleen aanlevert. Daar komen de meeste voorraadverschillen in deze combinatie vandaan.

Wat Magento en Business Central anders bewaren

Artikelvarianten en configurable products

In Business Central is een werkjas één artikel met een number van maximaal 20 tekens. Elke kleur en maat is een itemVariant met een code van maximaal 10 tekens en een omschrijving. Kleur en maat zijn geen aparte velden: ze zitten samen in die code, bijvoorbeeld BL-M.

In Magento is elke variant een eigen simple product met een eigen SKU, en het model een configurable product. Kleur en maat zijn attributen met een optie-ID per waarde. Die ID's verschillen per installatie, dus de koppeling leest ze uit jouw Magento en zoekt bij BL het ID van Blauw. Een kleurcode die in Magento nog niet bestaat komt op een controlelijst en wordt niet stil overgeslagen.

Het koppelen van een variant aan het model gaat per stuk: het endpoint POST /V1/configurable-products/{sku}/child neemt één childSku aan. Een jas in 4 kleuren en 6 maten is 24 varianten. Dat zijn 24 simple products, 1 configurable product, 2 aanroepen voor de opties kleur en maat en 24 koppelaanroepen: 51 verzoeken voor één model. Een collectie van 300 modellen is 15.300 verzoeken. De simple products gaan in bulk, de koppelaanroepen lopen uit een wachtrij. Meer over de keuzes staat op varianten koppelen.

Attribuutsets

Elk Magento-product heeft een attribute_set_id nodig. Business Central kent geen attribuutsets, alleen een itemCategoryCode. De koppeling houdt daarom een vertaaltabel bij: categorie WERKKLEDING hoort bij attribuutset 9. Een artikel met een categorie die niet in de tabel staat wordt niet onder de standaardset aangemaakt. Het wacht tot de tabel is aangevuld.

Voorraad: één totaal tegenover bronnen

Het veld inventory op een artikel in Business Central is één getal: de voorraad over alle locaties, alleen-lezen. De standaard-API geeft geen aantal per locatie. Magento rekent met bronnen en reserveringen. De verkoopbare voorraad is de som van de bronnen min de openstaande reserveringen, en een reservering vervalt pas als de zending in Magento staat.

De rekensom. Business Central heeft 20 stuks. Een order van 4 wordt geplaatst: Magento reserveert 4 en toont 16. De levering wordt geboekt en Business Central zakt naar 16. Schrijft de koppeling die 16 naar de bron voordat de zending in Magento staat, dan rekent Magento 16 min 4 en toont 12. De koppeling boekt daarom eerst de zending en schrijft daarna pas de voorraad. Heb je meer dan één locatie, dan komt het aantal per locatie uit een query die je in Business Central als OData-webservice publiceert. Zie voorraad over meerdere magazijnen.

Boekingsgroepen die Magento niet kent

Een klant in Business Central heeft een bedrijfsboekingsgroep en een klantboekingsgroep op de klantenkaart, een artikel een productboekingsgroep en een voorraadboekingsgroep. Magento stuurt geen van alle mee. De customers-resource van de API heeft er ook geen velden voor. Ze komen uit een sjabloon op de pagina API Setup, dat lege velden vult bij het aanmaken van een klant.

Eén sjabloon geeft elke webklant dezelfde groepen. Een Belgische zakelijke klant met verlegde btw heeft een andere btw-bedrijfsboekingsgroep nodig dan een Nederlandse. Dat onderscheid maakt de koppeling op land en btw-nummer uit het factuuradres en hij zet de klant via een eigen API-pagina in de juiste groep. Het algemene probleem staat in verplichte velden die de bron niet heeft.

De order zelf

Magento levert de straat als lijst van regels, het land als tweeletterige code in country_id. Business Central heeft shipToAddressLine1 van 100 tekens en shipToAddressLine2 van 50. Een adres met drie of vier straatregels wordt samengevoegd, en de koppeling controleert de lengte voordat de order wordt aangeboden.

POST /v2.0/{tenant}/Production/api/v2.0/companies({id})/salesOrders HTTP/1.1
Host: api.businesscentral.dynamics.com
Authorization: Bearer eyJ0eXAi...
Content-Type: application/json

{
  "externalDocumentNumber": "000010482",
  "orderDate": "2026-10-03",
  "customerNumber": "D00412",
  "shipToName": "Bakker Installatie B.V.",
  "shipToAddressLine1": "Industrieweg 12",
  "shipToPostCode": "3542 AD",
  "shipToCountry": "NL",
  "salesOrderLines": [
    { "lineType": "Item", "lineObjectNumber": "10482",
      "quantity": 4, "unitPrice": 89.50 }
  ]
}

Kop en regels gaan in één verzoek. Een variant gaat mee als itemVariantId op de regel, een locatie als locationId.

De technische werkelijkheid van deze combinatie

De twee API's zijn op een tegengestelde manier begrensd. Business Central online telt verzoeken per gebruiker. Voor Magento op een eigen server documenteert Adobe geen algemene limiet op de REST API: de grens is de server, en een koppeling die te veel tegelijk leest maakt de winkel traag.

De getallen zijn op 3 oktober 2026 nagelezen in de documentatie van Microsoft en Adobe. De invoerlimieten van Magento, 20 regels per synchroon verzoek en 5.000 per asynchroon verzoek, staan standaard uit.

Voorraad, doorgerekend. 18.000 SKU's met één bron zijn 18.000 voorraadregels. Uit Business Central is dat één pagina: de limiet is 20.000 records. Naar Magento zijn het bij 20 regels per synchroon verzoek 900 verzoeken, en via het bulk-endpoint bij 5.000 regels per verzoek 4. Na de eerste ronde gaan alleen gewijzigde artikelen mee.

Het bulk-endpoint hangt aan een consumer. Een bulkverzoek geeft direct een bulk_uuid terug en het werk gebeurt in de message queue, waarvoor Adobe RabbitMQ voorschrijft. Draait de consumer async.operations.all niet, dan blijft elke bewerking op status 4, Open, zonder foutmelding. De koppeling leest na elke batch GET /V1/bulk/{uuid}/status en meldt het als bewerkingen open blijven.

Webhooks van Business Central verlopen na drie dagen. Een abonnement moet binnen die tijd verlengd worden, met dezelfde handshake als bij het aanmaken. De koppeling verlengt elke twee dagen. Wijzigen er binnen 30 seconden meer dan 1.000 records, dan stuurt Business Central één melding van het type collection met een filter, en haalt de koppeling de records met dat filter op.

Zendingen komen niet via een webhook. salesShipments staat niet op de lijst met entiteiten die een webhook ondersteunen, en de resource heeft geen veld voor het trackingnummer of de vervoerder. De koppeling haalt nieuwe zendingen op met een filter op lastModifiedDateTime en leest het trackingnummer uit een gepubliceerde webservice. Daarna gaat de zending met track_number, title en carrier_code naar Magento. De rekensom voor je eigen aantallen maak je met doorvoer berekenen.

Wat een standaardkoppeling hier niet doet

Standaardkoppelingen en koppelplatformen voor dit paar beschrijven hun eigen grenzen.

• Een eigen extensie in Business Central. De leverancier installeert een app die velden en endpoints toevoegt. De mapping volgt die extensie en niet jouw inrichting.
• Boekingsgroepen als één vaste waarde. De verplichte groepen worden als standaardwaarde aan elke order toegevoegd. Een tweede btw-regime of een eigen groep per kanaal past daar niet in.
• Klantherkenning op e-mailadres. Bestaat het e-mailadres niet, dan komt er een nieuwe debiteur, ook als het bedrijf al onder een ander adres in Business Central staat. Zie dubbele klanten en debiteuren.
• Deelzendingen. Voor gesplitste zendingen staat in de documentatie van zo'n koppeling een waarschuwing voor onverwacht gedrag.

Microsoft levert zelf een koppeling met Shopify mee, alleen voor Business Central online. Voor Magento staat er in de documentatie van Microsoft geen. Een gebouwde koppeling heeft geen van deze vaste punten: de vertaaltabel voor attribuutsets, de regel voor boekingsgroepen en de match op debiteuren worden geschreven op hoe jouw Business Central en jouw Magento zijn ingericht.

Als het misgaat

Een order die blijft falen, bewaart de koppeling met de oorspronkelijke inhoud en biedt hij opnieuw aan zodra de oorzaak is opgelost. Elke poging gebruikt het increment_id als sleutel, zodat een herhaling geen tweede verkooporder aanmaakt. Een controleronde vergelijkt de Magento-orders van de laatste dagen met de externalDocumentNumber in Business Central, zodat een order die een ronde heeft gemist alsnog aankomt.

Voor livegang draait de koppeling als dry run: hij leest beide kanten en laat zien welke producten, prijzen en orders hij zou schrijven, zonder te schrijven. Daarna laat elke run per record zien wat er is gewijzigd. Hoe dat werkt staat op dry run en goedkeuring. Wij hosten en bewaken de koppeling en passen hem aan als Adobe of Microsoft een interface wijzigt. De systeemkant staat op Business Central koppeling, de platformkant op Magento koppeling, en alle stromen op koppelingen. Verwante combinaties: WooCommerce Business Central koppeling en Shopify Business Central koppeling. Vertel welke Magento-versie en welke Business Central je draait.