Akeneo koppeling met je webshop: productdata per taal en kanaal, zonder handwerk

Wat is Akeneo en welke editie heb je?

Akeneo is een PIM-systeem: één plek waar productinformatie wordt verzameld, aangevuld, vertaald en gecontroleerd voordat hij naar webshops, marktplaatsen en catalogi gaat. Het wordt gebruikt door fabrikanten, merken en groothandels met duizenden artikelen in meerdere talen. Wat een PIM doet en waar hij naast het ERP staat, lees je in wat is een PIM-systeem.

Akeneo bestaat in meerdere edities. Voor een koppeling verschillen ze op twee punten: of Akeneo wijzigingen zelf meldt, en of Asset Manager en Reference Entities beschikbaar zijn.

Zonder Event Platform vraagt de koppeling op een vast interval de producten op met een filter op updated. Bij een SaaS-editie staan die tijden in UTC.

Wat je met Akeneo koppelt

Akeneo is leidend voor wat een product is: naam, omschrijving, attributen, categorieën, varianten en beelden. Het ERP is leidend voor het artikelnummer, de prijs en de voorraad. Die verdeling bepaalt de stromen.

Een product gaat pas naar de webshop als het voor dat kanaal en die taal compleet is. Akeneo rekent die volledigheid zelf uit per kanaal en per locale, en de koppeling filtert erop met completeness. Een half ingevuld product blijft dus in Akeneo tot het team het afmaakt. Hoe die stromen samen een productdatalandschap vormen staat op productdata.

Hoe Akeneo data vrijgeeft

REST API met een connection

Akeneo heeft een REST API met JSON. Toegang loopt via een connection die je in Akeneo aanmaakt. Die levert vier gegevens: een client ID, een secret, een gebruikersnaam en een wachtwoord. Het wachtwoord toont Akeneo maar één keer, direct na het aanmaken. Daarmee vraagt de koppeling een access token op dat 1 uur geldig is, met een refresh token van 14 dagen (1.209.600 seconden).

De limieten

De volledige regels staan in Akeneo's good practices voor de API. De limiet van 10 gelijktijdige verzoeken geldt voor de hele instantie. Draait er naast onze koppeling ook een marktplaatskoppeling en een feedtool op dezelfde PIM, dan delen ze die 10. De koppeling houdt zich aan 4 tegelijk en wacht bij een 429 het aantal seconden uit Retry-After.

De rekensom voor een catalogus van 40.000 producten. Met pagina's van 100 zijn het 40.000 / 100 = 400 verzoeken. Met de standaardpagina van 10 zouden het er 4.000 zijn. Met page-paginering stopt Akeneo na pagina 100 met een 422, want 100 x 100 = 10.000. De koppeling bladert daarom met search_after, en haalt na de eerste ronde alleen producten op die sinds de vorige ronde zijn gewijzigd.

Producten met een UUID

Sinds november 2022 heeft een product in Akeneo een UUID en is de identifier niet meer verplicht. Het endpoint /api/rest/v1/products-uuid geeft alle producten. Het oude /products slaat producten zonder identifier over. Een koppeling die nog op /products draait, mist dus stil elk product dat zonder artikelnummer is aangemaakt.

Events

Het Event Platform meldt een wijziging met een event als com.akeneo.pim.v1.product.updated. Per PIM zijn er 20 subscribers mogelijk, elk met 20 subscriptions. De oudere Events API blijft ondersteund tot 31 december 2026. Een event bevat de verwijzing naar het product; de koppeling haalt het product daarna op en controleert de volledigheid voordat het doorgaat.

Waar het bij Akeneo op vastloopt

Elke waarde heeft een taal en een kanaal

In Akeneo is een waarde nooit één veld. Elke waarde hangt aan een locale, een scope (het kanaal) of beide:

{
  "family": "werkschoenen",
  "parent": "WS-200",
  "values": {
    "name": [
      {"locale": "nl_NL", "scope": null, "data": "Werkschoen S3 laag"},
      {"locale": "de_DE", "scope": null, "data": "Arbeitsschuh S3 niedrig"}
    ],
    "description": [
      {"locale": "nl_NL", "scope": "ecommerce", "data": "<p>Neus van composiet.</p>"}
    ],
    "color": [{"locale": null, "scope": null, "data": "black"}],
    "weight": [{"locale": null, "scope": null,
      "data": {"amount": "1.2000", "unit": "KILOGRAM"}}]
  }
}

Drie dingen vallen op. De kleur staat er als code, black, en niet als "Zwart"; het label komt uit een aparte aanroep op de opties van het attribuut. Het gewicht is een bedrag met een eenheid, en de webshop wil meestal kilo's als getal. En de omschrijving bestaat alleen voor kanaal ecommerce: een tweede webshop op kanaal b2b krijgt een andere tekst, of geen. De koppeling legt per webshop vast welk kanaal en welke locales hij leest. Zie wat is veldmapping.

Productmodellen en varianten

Een productmodel in Akeneo heeft 1 of 2 variantniveaus, met maximaal 10 assen per niveau en 20 in totaal. Een werkschoen kan dus variëren op kleur, dan op maat en breedte. Webshops zijn strakker: Shopify heeft 3 opties per product, WooCommerce variabele producten met attributen, Magento configureerbare producten met eigen attribuutsets. Per familie leggen we vast hoe twee niveaus en meerdere assen worden platgeslagen. Per platform staat dat op de pagina van de combinatie.

Opties en afbeeldingen

Een attribuut van het type keuzelijst levert codes. Nieuwe opties aanmaken gaat met 3 per seconde, dus een import die 1.200 nieuwe kleurcodes vanuit een leveranciersfeed aanmaakt, staat 1.200 / 3 = 400 seconden te wachten. Afbeeldingen staan in een afbeeldingsattribuut als code van een mediabestand, niet als publieke URL. De koppeling downloadt elk bestand via /media-files/{code}/download met het token en uploadt het naar de webshop.

Platformen die we aan Akeneo koppelen

De koppeling wordt gebouwd op jouw Akeneo: je families, kanalen, locales en completeness-regels. Per combinatie staat op een eigen pagina wat er specifiek speelt:

• Akeneo Shopify koppeling
• Akeneo Magento koppeling
• Akeneo WooCommerce koppeling

De platformen zelf staan op Shopify koppeling, Magento koppeling en WooCommerce koppeling. Voor de bouw- en installatiebranche, waar productdata uit een databank als EZ-base komt, staan de standaarden op ETIM en GS1. Het overzicht van alle stromen staat op koppelingen.

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 product welke titel, opties en afbeeldingen er in de webshop zouden komen, zonder dat er iets wordt gepubliceerd. Vertel welke editie van Akeneo en welke webshop je hebt, dan hoor je welke kanalen en talen er mee kunnen.