Magento 2 koppeling met ERP, PIM, magazijn en leveranciers

Wat is Magento en wie gebruikt het?

Magento 2 bestaat in twee uitvoeringen. Magento Open Source is gratis en draait op je eigen server of bij je hostingpartij. Adobe Commerce is de betaalde versie, op eigen hosting of op Adobe Commerce Cloud, met extra modules voor B2B. Allebei zijn ze uitbreidbaar met modules. Een module voegt vaak eigen velden toe aan producten of orders, en die moet een koppeling dan ook lezen of vullen.

De koppelingen die wij voor Magento bouwen draaien om drie dingen: veel SKU's met varianten, prijzen per klantgroep en voorraad uit meer dan één magazijn.

Wat je met Magento koppelt

Magento is leidend voor orders en webklanten. Artikelen, prijzen en voorraad komen uit het ERP, het PIM of het magazijnsysteem.

Een order heeft twee nummers. entity_id staat in elk API-pad, increment_id is het nummer dat de klant ziet, zoals 000010482. De koppeling zet het increment_id in het ERP als extern ordernummer en bewaart het entity_id om later de zending te boeken. Een creditnota kan met return_to_stock_items regels terugzetten in de voorraad; of dat moet, beslist het ERP of het magazijn, niet Magento. De stromen in het algemeen staan op voorraad en beschikbaarheid en orders, klanten en verzending.

Hoe Magento data vrijgeeft

REST voor de beheerkant

Magento heeft een REST API en een GraphQL API. Adobe positioneert GraphQL voor storefronts en mobiele apps. Wat een koppeling doet, zoals bronaantallen schrijven, prijzen zetten, zendingen boeken en bulkverzoeken indienen, loopt via REST. Wij bouwen de beheerkant op REST.

Toegang met een Integration

Toegang loopt via een Integration die de beheerder aanmaakt onder System, Extensions, Integrations. Daar kies je per resource wat de koppeling mag: alleen producten en voorraad, of ook orders en klanten. Na het activeren geeft Magento vier waarden: consumer key, consumer secret, access token en access token secret. Dat token verloopt niet tot het wordt ingetrokken.

Sinds 2.4.4 werkt dat access token niet meer los als Bearer-token. Requests worden met OAuth 1.0a ondertekend, met HMAC-SHA256. Het terugzetten van het oude gedrag kan met één instelling, maar Adobe raadt het af en wij doen het niet. Een admin-token is het alternatief; dat verloopt standaard na 4 uur.

Geen limiet, wel een server

Adobe documenteert geen algemene limiet op de REST API van een zelf gehoste Magento. De ingebouwde invoerlimieten staan standaard uit.

Een zoekopdracht zonder pageSize geeft alle treffers terug. Op een catalogus van 40.000 producten is dat één antwoord met 40.000 producten, en dat vraagt de server van je winkel. De koppeling vraagt daarom altijd in pagina's en leest buiten de piekuren van de shop.

De rekensom voor een volledige voorraadronde van 12.000 SKU's over 2 bronnen: 24.000 bronregels. Met de synchrone grens van 20 regels per verzoek zijn dat 24.000 / 20 = 1.200 verzoeken. Via het bulk-endpoint met 5.000 regels per verzoek zijn het er 24.000 / 5.000 = 4,8, dus 5. Na de eerste ronde gaan alleen gewijzigde regels mee. Je eigen aantallen reken je door met doorvoer berekenen.

Bulk-endpoints en de consumer

Een verzoek op /async/bulk/V1/... krijgt direct een bulk_uuid terug. Het werk zelf doet een consumer uit de message queue, async.operations.all. Draait die niet, dan blijven alle bewerkingen op status 4, Open, zonder foutmelding. De koppeling vraagt na elke batch GET /V1/bulk/{uuid}/status op en meldt bewerkingen die open blijven.

POST /rest/async/bulk/V1/inventory/source-items HTTP/1.1
Authorization: OAuth oauth_consumer_key="...", oauth_signature_method="HMAC-SHA256", ...
Content-Type: application/json

[{"sourceItems": [
  {"sku": "10482-BL-M", "source_code": "magazijn", "quantity": 20, "status": 1},
  {"sku": "10482-BL-M", "source_code": "winkel", "quantity": 6, "status": 1}
]}]

Wijzigingen melden

Adobe I/O Events en Adobe Commerce Webhooks melden een nieuwe order direct, maar ze vragen Adobe Commerce 2.4.4 of hoger en bestaan niet voor Open Source. Op Open Source vraagt de koppeling elke paar minuten orders op met updated_at groter dan de vorige ronde.

Waar het bij Magento op vastloopt

Bronnen, reserveringen en verkoopbare voorraad

Met Multi-Source Inventory heeft een SKU een aantal per bron. Wat de klant kan kopen is de verkoopbare voorraad. Magento telt per bron het aantal min de drempel voor uitverkocht op, en trekt daar de reserveringen van open orders af. Een reservering ontstaat bij de order en verdwijnt pas als de zending in Magento geboekt is.

De rekensom: magazijn 20 en winkel 6, drempel 1 per bron, 4 stuks in open orders. (20 - 1) + (6 - 1) - 4 = 20 verkoopbaar. Schrijft de koppeling niet het fysieke aantal maar de vrije voorraad uit het ERP, 26 - 4 = 22, dan trekt Magento de 4 nog een keer af en toont 16. De koppeling schrijft dus fysieke aantallen per bron en boekt de zending in Magento voordat de volgende voorraadronde loopt. Zie welke voorraad toon je in je webshop.

Configurable products

Elke variant is in Magento een simple product met een eigen SKU. Het model is een configurable product, en 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. Het koppelen van een variant aan het model gaat per stuk: het child-endpoint neemt één childSku aan.

Een shirt in 3 kleuren en 5 maten is 15 simple products, 1 configurable product, 2 verzoeken voor de opties en 15 koppelverzoeken: 33 verzoeken. Een collectie van 400 modellen is 13.200 verzoeken bij de eerste import. Een kleur die in Magento nog geen optie heeft, komt op een controlelijst. Meer op varianten.

Attribuutsets en prijsbereik

Elk product heeft een attribute_set_id nodig, en het ERP kent geen attribuutsets. De koppeling houdt een vertaaltabel bij van artikelgroep naar attribuutset. Het prijsbereik staat standaard op Global: één prijs voor alle websites. Heb je per website een andere prijs, dan moet het bereik op Website staan voordat de koppeling per website prijzen kan zetten.

Adressen

Magento bewaart de straat als lijst van 1 tot 4 regels, afhankelijk van de instelling, en het land als tweeletterige code in country_id. Een ERP met straat, huisnummer en toevoeging als drie velden krijgt een gesplitst adres; de koppeling splitst op het huisnummer en zet regels die niet te splitsen zijn op de controlelijst. Zie adresvelden mappen.

Systemen die we aan Magento koppelen

Per combinatie staat op een eigen pagina wat er specifiek speelt:

• Magento Business Central koppeling
• Magento AFAS koppeling
• Magento Exact Online koppeling
• Akeneo Magento koppeling

De systemen zelf: Business Central koppeling, AFAS webshop koppeling en Exact Online koppeling. Andere platformen: Shopify koppeling en WooCommerce koppeling. Alle stromen en systemen staan op koppelingen.

Wij bouwen de koppeling voor een vaste prijs op jouw Magento, jouw modules en jouw systemen, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor livegang draait hij als dry run: je ziet per SKU en per bron welk aantal en welke prijs er in Magento zou komen, zonder dat er iets wijzigt. Vertel welke Magento-versie je draait en welke systemen erachter staan.