Shopware 6 API valkuilen: cheatsheet uit een brouwerij

Vrijdagmiddag in Eindhoven. De marketing lead van de brouwerij pingt ons: de product-discovery pagina gooit 500s voor de helft van de biervarianten, de nieuwe gift-box landingspagina flikkert tussen 'op voorraad' en 'uitverkocht' bij refresh, en de staging API gooit al twee dagen VIOLATION::FORMAT_NOT_SUPPORTED. Black Friday is over negen weken. Ze wilden faceted filters, snelle search, en een schone storefront API voor de nieuwe headless front-end. Wat ze kregen was een stack trace.

We hadden ze de maand ervoor naar Shopware 6.6 gemigreerd, en de meeste zichtbare bugs leidden terug naar één hoofdoorzaak: de officiële PHP SDK serialiseert een lange lijst productvelden als nullable, terwijl de store API diezelfde velden bij rendertijd als verplicht behandelt. De ORM laat je nulls schrijven. De klantgerichte API weigert ze te lezen. Voeg een handvol eigenaardigheden rond varianten, context tokens en aggregatievormen toe, en je eindigt met de cheatsheet hieronder.

Zeventien items, gerangschikt naar welke de SDK het hardst over liegt. Terwijl de rest van het internet las over een AI-agent die op hol sloeg in een Fedora-installatie, gooide de checkout van de brouwerij stilletjes 500s op cover image rendering. Beide verhalen hebben dezelfde moraal: schemas zijn belangrijk, en 'nullable' is een contract, geen suggestie.

Waarom de PHP SDK en de store API het oneens zijn

Shopware 6 levert drie API-oppervlakken. De admin API praat OAuth en geeft je directe toegang tot de Data Abstraction Layer. De store API is token-based, customer-scoped, en haalt elke payload door de rendering pipeline. Een legacy sales-channel API wordt nog altijd meegeleverd voor backwards compatibility, en je bent een ochtend kwijt om die uit één of twee plugins te slopen die niemand sinds 2022 heeft aangeraakt.

De PHP SDK in shopware/core modelleert entities voor het admin-pad. Dat betekent nullable PHP-types, optionele associaties en heel veel ?string in de Doctrine annotations. De store API verwacht echter een resolved cover image, een berekende prijs, een non-null productnaam en een navigatiecategorie. Als je sync job één van die velden null laat, accepteert de admin API het, slaat de database het op, en de storefront geeft 500s terug. Of, erger, hij geeft een entity terug met lege strings en nul-euro prijzen, het soort bug dat je pas vangt als een klant er een screenshot van maakt.

De zeven nullable-maar-verplichte boosdoeners, gerangschikt

1. cover op de product entity. De DAL markeert coverId als nullable. De store API resolved cover via de product-media junction en de entity hydrator. Zet 'm op null bij een zichtbaar product en de listing endpoint valt om met een FormatNotSupportedException zodra de thumbnail service een ontbrekend mediabestand probeert te schalen. Fix bij de bron door coverId af te dwingen in je importschema, niet door de thumbnail service te patchen.

// admin API write that the SDK happily accepts and the storefront cannot render
$repository->upsert([[
    'id' => $productId,
    'productNumber' => 'BR-IPA-330-6PK',
    'name' => 'Tripel six-pack',
    'stock' => 120,
    'taxId' => $taxId,
    'price' => [['currencyId' => $eur, 'gross' => 17.95, 'net' => 14.83, 'linked' => true]],
    // missing: coverId, manufacturerId, visibilities, categories
]], $context);

2. price als lege array. De SDK accepteert price: [] bij upsert. De store API gooit op de calculated-price stap omdat de afrondingsstrategie minstens één currency match nodig heeft. Kun je geen prijs per currency garanderen op write time, gate dan de visibility flag in plaats van een lege array productie te laten halen.

3. name op varianten. Varianten erven hun naam van de parent. Krijgt de parent een nieuwe naam en heeft de variant een verouderde, non-null override, dan serveert de store API de override. Is de variant override null, dan erft hij. Tot zover prima. De bug verschijnt wanneer een migratiescript de variant name op een lege string zet in plaats van null. De SDK behandelt lege string als valide; de store API rendert een lege productkaart.

4. visibilities voor het sales channel. Een product is niet zichtbaar voor een sales channel tenzij er een row bestaat in product_visibility voor dat channel. De SDK dwingt dit niet af bij write. De store API filtert het product stil uit elke listing en search response. De brouwerij had 280 SKU's in de database en 41 zichtbaar op de storefront, drie dagen lang voordat iemand het opmerkte.

5. categories associatie. Faceted navigation joint via product_category. Een product zonder categorie wordt teruggegeven bij een directe /store-api/product/{id} lookup maar verschijnt nooit in /store-api/product-listing/{categoryId}. De gift boxes van de brouwerij stonden in geen enkele categorie omdat de import 'Gift' als tag behandelde, niet als navigatiecategorie. Twee regels fix in het importscript. Zes uur om te vinden.

6. manufacturerId. Nullable in de DAL, verplicht voor de manufacturer filter aggregation als je wilt dat die rendert. Heeft de helft van je producten een manufacturer en de andere helft niet, dan geeft de aggregation een 'geen manufacturer' bucket terug met een null key, en de storefront-componenten gooien op het ontbrekende label. Backfill manufacturers voor elk product, of strip de aggregation uit de criteria.

7. customFields shape. De DAL slaat customFields op als JSON-kolom. De SDK type't het als ?array. De storefront-componenten lezen specifieke keys. Verwacht een typed component custom_brewery_abv en is het veld null (niet een leeg object, null), dan rendert de component letterlijk de string 'null' in de productkaart. Default naar {}, nooit null.

Context, tokens en de sw-context-token foot-gun

De store API authentiseert met een access key in de sw-access-key header. State (cart, customer session, taal, currency) wordt meegedragen in sw-context-token. Het token roteert bij login, bij currency switch en soms bij cart mutation. Naïeve clients cachen het eerste token dat ze ontvangen en sturen het voor altijd door. De store API geeft dan een context terug die niet meer matcht met wat de gebruiker drie kliks geleden deed, en de cart lijkt leeg bij checkout.

// always read the response header back into the client
const res = await fetch(`${baseUrl}/store-api/cart/line-item`, {
  method: 'POST',
  headers: {
    'sw-access-key': accessKey,
    'sw-context-token': ctx.token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ items: [{ referencedId: productId, quantity: 1, type: 'product' }] }),
});

const next = res.headers.get('sw-context-token');
if (next && next !== ctx.token) ctx.token = next; // do not skip this

total-count-mode en de stille pagination bug

De total-count-mode query parameter heeft drie waarden: 0 geeft geen totaal, 1 geeft een exact totaal, 2 geeft een 'next page exists' boolean terug. De default wisselde tussen Shopware 6.4 en 6.5 op bepaalde endpoints. Pagineert je front-end door Math.ceil(total / limit) te berekenen en geeft de API total: 0 terug omdat de mode 0 is, dan render je één pagina ook al telt de catalogus 4.000 SKU's. Geef de mode expliciet mee op elke request.

Varianten, parentId en de cover-image inheritance valkuil

Varianten erven bijna alles van het ouderproduct. Bijna. De cover image erft alleen als de variant geen eigen productMedia rows heeft. De brouwerij wilde variant-specifieke flesfotografie voor het 75cl-formaat en niet voor de 33cl. De importer hing een 75cl-foto aan elke variant en liet de 33cl-varianten met de parentfoto staan. De store API erfde correct voor 33cl. Maar serveerde ook ten onrechte de 75cl-foto als cover voor varianten waar de flesfoto bedoeld was als gallery shot, omdat coverId niet expliciet was gezet en de hydrator de eerste geassocieerde mediarij op sorteervolgorde pakte.

De fix: zet coverId expliciet op elke variant die eigen media heeft. Vertrouw nooit op de impliciete eerste-mediarij-regel. De Shopware Data Abstraction Layer docs beschrijven de inheritance graph in detail; print de relevante pagina en hang 'm aan de muur.

Aggregations zien er hetzelfde uit. Ze zijn het niet.

Beide API's accepteren een Criteria object met een aggregations key. De admin API geeft aggregations terug genest binnen het entity-search resultaat. De store API geeft aggregations terug als top-level aggregations object naast elements. Schreef je een gedeelde TypeScript-type voor de twee responses, dan kom je erachter dat één van je filter-sidebars een undefined pad leest en stilletjes nul buckets rendert. Split de types. Ze hebben niet dezelfde vorm.

De overige tien, in één adem

• 8. productNumber uniqueness strekt zich uit tot soft-deleted rows. Een nummer hergebruiken van een verwijderde SKU gooit bij upsert.
• 9. seoUrls hebben de SEO URL indexer nodig voordat de storefront de mooie URL serveert. Nieuwe producten tonen de technische URL totdat de queue worker bijbeent.
• 10. availableStock wordt berekend uit stock minus openstaande orders. Schrijf er nooit direct naartoe. De DAL laat het toe. De volgende stock recalculation overschrijft je.
• 11. price.linked: true herberekent gross uit net telkens als het tax rate wijzigt. Zet linked: false als je gross-first prijzen importeert.
• 12. De sw-access-key is gebonden aan een sales channel. Eén key per channel. Ze mixen filtert de catalogus stil naar het verkeerde channel.
• 13. Criteria::addAssociation('cover.media') werkt in de admin SDK maar is een no-op in de store API, waar cover media al voorgeladen is. Toevoegen schaadt niet, maar code lezen die de twee mixt is pijnlijk.
• 14. releaseDate verbergt een product uit listings totdat de datum voorbij is, ook wanneer active: true. De seizoensbieren van de brouwerij waren onzichtbaar omdat de importer de releasedatum per ongeluk zes weken vooruit had gezet.
• 15. Product properties (propertyIds) drijven de filter facets. Een product zonder properties verschijnt nooit in property-based filters. Hops, ABV, IBU, style. Backfill ze of de filter-sidebar is dood gewicht.
• 16. De store API rate limit is per token, niet per IP. Een buggy retry loop op één tab throttlet andere klanten niet, maar zet die buggy tab wel buitenspel voor de cool-down window.
• 17. Guest customer sessions verlopen na een instelbaar interval. De default is korter dan de meeste teams verwachten. Cart-abandonment metrics zien er slecht uit totdat je 'm afstemt.

Wat we hebben gebouwd om de brouwerij rustig te houden

De fix was niet glamoureus. We schreven een Symfony console command die door elk product in de catalogus loopt, alle zeventien checks draait, en een CSV uitspuugt met één rij per SKU en één kolom per valkuil. Groen voor pass, rode hex voor fail, met de naam van het overtredende veld in de cel. De marketing lead draait 'm nu vóór elke campagne-push. Dezelfde command draait in CI tegen de staging-import, zodat de deploy faalt voordat klanten van de brouwerij een 500 zien, de volgende keer dat een feed-wijziging stil een cover nullt.

De headless storefront ging drie weken vóór Black Friday live. De product-discovery pagina rendert nu in 180ms p95 op één VPS. De marketing lead heeft ons al zes weken niet meer gepingt over een 500.

Toen we vorig jaar dezelfde audit draaiden op een andere legacy migratie, hield het patroon stand: de meeste productiebugs in de storefront zijn geen Shopware-bugs. Het zijn mismatches tussen een permissieve write API en een strikte read API, en de fix zit in de import job, niet in de storefront. Draai de audit voordat de storefront live gaat, niet erna.

Vijf-minutenactie voor vandaag: grep je importcode op elke veld-assignment van null op een Shopware-product, en vraag jezelf af of de storefront 'm kan renderen. Kun je daar geen 'ja' in één zin op geven, dan is het antwoord nee.