Een PIM koppelen aan je webshop

Hoe koppel je een PIM aan je webshop?

De koppeling leest de producten uit het PIM, zet ze om naar de opbouw van de webshop en schrijft ze weg. Daarna volgt hij de wijzigingen. Het lezen is het eenvoudige deel. Het omzetten vraagt per attribuut een besluit, omdat een PIM en een webshop een product anders opbouwen.

De voorbeelden op deze pagina gebruiken Akeneo als PIM, met de getallen uit de documentatie van Akeneo zoals die op 3 oktober 2026 was. Bij Pimcore, inriver of Salsify heten de begrippen anders en zijn de vragen dezelfde. Wat een PIM is en hoe een product erin is opgebouwd staat in wat is een PIM-systeem.

Dit is het eerste verzoek van een koppeling voor de Duitse webshop:

GET /api/rest/v1/products-uuid?scope=ecommerce&locales=de_DE
    &pagination_type=search_after&limit=100
    &search={"completeness":[{"operator":"GREATER OR EQUALS THAN ON ALL LOCALES",
             "value":100,"locales":["de_DE"],"scope":"ecommerce"}]}

In dat ene verzoek zitten drie van de vier keuzes: het kanaal (scope), de taal (locales) en de eis dat het product voor die taal 100% volledig is. De vierde keuze, welk attribuut naar welk veld gaat, staat in de mapping.

Kanaal en taal: welke waarden gaan mee?

Een attribuut in Akeneo kan per taal en per kanaal een eigen waarde hebben. De titel bestaat in nl_NL en de_DE. De omschrijving bestaat per taal en ook per kanaal: een lange voor ecommerce, een korte voor marktplaats. De parameter scope kiest één kanaal, locales een of meer talen.

De parameter scope doet meer dan waarden filteren. Akeneo geeft dan alleen producten terug die in de categorieboom van dat kanaal staan. Een product zonder categorie komt met scope nooit mee, ook niet als alle teksten zijn ingevuld. Per verzoek kan er één kanaal in. Staan er 4.150 producten in het PIM en zijn er 150 nog niet ingedeeld, dan ziet de koppeling er 4.000.

Aan de kant van de webshop is een taal geen kolom maar een vertaling van het origineel. Bij Shopify schrijf je een vertaling met de mutatie translationsRegister:

{
  "resourceId": "gid://shopify/Product/8104512345601",
  "translations": [{
    "locale": "de",
    "key": "title",
    "value": "Arbeitshose Stretch schwarz",
    "translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9"
  }]
}

De translatableContentDigest is een controlegetal van de Nederlandse titel waar de vertaling bij hoort. Verandert de Nederlandse titel, dan verandert dat getal en zet Shopify de Duitse vertaling op outdated. De koppeling schrijft daarom eerst het origineel, haalt het nieuwe controlegetal op en schrijft dan de vertalingen. Een gewijzigde titel kost zo drie verzoeken per product in plaats van één: het origineel schrijven, het controlegetal ophalen en de vertalingen schrijven. Shopify staat 20 talen per winkel toe, 30 op Plus.

Er zijn standaardkoppelingen die één kanaal en één taal als bron ondersteunen. Voor een webshop in het Nederlands is dat genoeg. Voor de Duitse winkel niet: de vertalingen staan in het PIM en komen niet aan.

Attributen en eigenschappen: wat wordt een variant?

Een attribuut dat een variant uniek maakt, zoals kleur of maat, wordt in de webshop een keuze op de productpagina. Een eigenschap die voor alle varianten geldt, zoals het materiaal, wordt een regel in de specificaties. Elk systeem heeft daar een eigen plek voor:

Akeneo levert een model met twee niveaus als drie soorten records: het productmodel 10482, de submodellen per kleur zoals 10482-BLK, en de variantproducten per maat zoals 10482-BLK-048. Elk record verwijst met parent naar het niveau erboven. Shopify kent één product met varianten. De koppeling leest de modellen via /api/rest/v1/product-models en de varianten via /api/rest/v1/products-uuid, legt ze op parent bij elkaar en schrijft één product met twee opties.

Drie dingen gaan hier in de praktijk mis:

• De waarde is een code. Bij een keuzelijst geeft Akeneo de code van de optie terug, black, en niet het label. Het label per taal, Zwart en Schwarz, haalt de koppeling apart op. Een koppeling die de code doorzet, toont black als kleur in de webshop.
• De volgorde van maten. 048, 050, 052 sorteren goed als tekst. S, M, L en XL niet. De volgorde komt uit het veld sort_order van de opties in het PIM.
• Een as te veel. Kleur, maat en lengtemaat zijn drie assen en dat past in Shopify. Een vierde as past niet: het maximum is 3 opties per product. De koppeling splitst het model dan in meerdere producten of voegt twee assen samen tot één optie.

Afbeeldingen zijn in de waarde van het product alleen een verwijzing. Bij een afbeeldingsattribuut staat er een bestandscode in, en de koppeling haalt het bestand op via /api/rest/v1/media-files/{code}/download. Bij vijf foto's per product zijn dat vijf verzoeken extra.

Deze vertaling van attribuut naar veld heet veldmapping. Hoe varianten per platform worden opgebouwd staat bij kleuren en maten als varianten.

Volledigheid: wat doe je met een product dat niet af is?

Akeneo rekent per product uit welk deel van de verplichte attributen is ingevuld, per kanaal en per taal. Wat verplicht is, ligt per productfamilie vast. De API filtert daarop, zoals in het verzoek bovenaan. Daarmee is de regel te kiezen, en de som laat zien wat het verschil is.

Bij regel A staan er 3.640 min 2.900 is 740 producten wel in de Nederlandse winkel en niet in de Duitse. Bij regel B staan ze er allemaal, en leest een Duitse klant bij 740 producten een Nederlandse omschrijving. Regel A kost 3.640 gedeeld door 100 per pagina is 37 verzoeken voor het Nederlands en 29 voor het Duits. De 360 producten die ook in het Nederlands niet volledig zijn, komen in geen van beide winkels en staan op de controlelijst met het attribuut dat ontbreekt.

De regel kan per veld verschillen. Een ontbrekende Duitse omschrijving houdt het product tegen. Een ontbrekende Duitse naam van een materiaal valt terug op het Nederlands.

Alleen de wijzigingen: hoe blijft de webshop bij?

Na de eerste lading leest de koppeling alleen wat gewijzigd is. Akeneo heeft daar twee routes voor.

Bij het vragen spelen twee details. Het tijdstip in het filter leest Akeneo in de tijdzone van de server, en bij de cloudversie is dat UTC. Een ronde die om 06:00 Nederlandse zomertijd vraagt om alles sinds 00:00 en de tijd niet omrekent, krijgt alles sinds 00:00 UTC. Dat is 02:00 Nederlandse tijd: de wijzigingen van 00:00 tot 02:00 ontbreken. En de gewone paginering stopt bij 10.000 producten: pagina 101 met 100 per pagina geeft een fout met code 422. Voor een grotere set gebruikt de koppeling pagination_type=search_after, zoals in het verzoek bovenaan.

Bij het melden geldt wat voor elke webhook geldt. Akeneo levert een bericht minstens één keer af, dus soms twee keer, en garandeert de volgorde niet. Na drie mislukte nieuwe pogingen is het bericht weg. De ronde die de wijzigingen opvraagt, blijft daarom naast de meldingen draaien.

Een wijziging op een productmodel raakt alle varianten eronder. Past iemand de titel van model 10482 aan, dan geeft het filter op updated ook de 24 variantproducten terug, hoewel hun eigen datum ouder is. Voor de webshop is dat één product met één nieuwe titel. De koppeling vergelijkt daarom per veld wat er werkelijk veranderd is en schrijft één keer, niet 24 keer. Hoe je de duur van een ronde uitrekent staat in doorvoer berekenen.

Welke velden blijven van het ERP?

Het PIM levert de inhoud. Het artikelnummer, de prijs en de voorraad komen uit het ERP of het magazijnsysteem. In de webshop komen die stromen samen op één veld: de sku.

De volgorde telt. Het PIM maakt het product aan als concept. De prijs en de voorraad komen daarna binnen op dezelfde sku. Van de 3.640 volledige producten hebben er 3.590 een artikel met prijs in het ERP. De 50 andere blijven concept: een product zonder prijs in een webshop is een product van 0 euro. Ze staan op de controlelijst als "geen artikel in het ERP met deze code". Meestal is dat een tikfout in het artikelnummer of een verdwenen voorloopnul, zie SKU of EAN.

Wat betekent dit voor je koppeling?

Een PIM koppelen is voor het grootste deel beslissen: per kanaal, per taal en per attribuut. Wij leggen die besluiten met je vast en bouwen de koppeling daarop, voor jouw families, jouw talen en jouw webshop. De eerste lading draait droog, zodat je per taal ziet hoeveel producten klaar zijn en welke op de controlelijst staan voordat er iets in de webshop verandert. Daarna hosten, draaien en bewaken we de koppeling, en passen we hem aan als het PIM of de webshop een nieuwe API-versie uitbrengt.

Hoe de stroom is opgebouwd, met varianten, classificatie en de limieten per systeem, staat op productdata koppelen. Vertel welk PIM en welke webshop je hebt, en in welke talen je verkoopt.