Kort antwoord. Via de Retailer API van bol automatiseer je prijzen, voorraad, levertijd, orders, zendingen en facturen. Versie 10 was de laatste keer dat de hele API een nieuwe versie kreeg; sindsdien versioneert bol per onderdeel. Schrijfacties zijn asynchroon: je krijgt een 202 met een process-status-id en vraagt daarna op of het gelukt is. Automatiseer wat je kunt meten en terugdraaien; laat content en annuleringen bij een mens.
Wat de Retailer API is
De Retailer API is de officiële koppeling waarmee verkopers (en de tools die zij gebruiken) met hun verkoopaccount praten. Elke verkoper maakt eigen API-sleutels aan in het verkoopaccount. Een tool die voor jou werkt, gebruikt jouw sleutels en handelt dus namens jou; bewaar ze daarom versleuteld en geef ze nooit door via e-mail.
Versies: v10 was de laatste "grote" versie
Volgens de migratiegids van bol was v10 de laatste keer dat de volledige API als nieuwe versie uitkwam. Sindsdien gebeurt versiebeheer per resource: orders, offers, shipments en de andere onderdelen krijgen elk hun eigen versie en eigen einddatum. De lifecycle-pagina van bol noemt vaste momenten voor nieuwe versies, 1 april en 1 oktober, al is die pagina niet overal actueel. Twee gevolgen:
- Wie zelf een koppeling bouwt, moet per onderdeel bijhouden welke versie hij gebruikt en wanneer die stopt. De Accept- en Content-Type-headers dragen de versie (
application/vnd.retailer.v10+json). - Wie een tool gebruikt, kijkt of de leverancier de migraties bijhoudt. Een tool die in november 2024 nog op v9 zat, lag eruit.
Asynchroon: 202 en daarna de process status
Een prijs- of voorraadwijziging wordt niet direct verwerkt. De API antwoordt met een 202 en een process-status-id; de daadwerkelijke verwerking volgt later, en pas in de process status zie je of de wijziging is doorgevoerd of met een validatiefout is afgewezen. Een koppeling die alleen naar de 202 kijkt, denkt dat alles gelukt is. Elke serieuze automatisering slaat het id op, haalt de status op en legt het resultaat vast per artikel.
Wat je automatiseert
| Onderdeel | Wat je ermee doet | Let op |
|---|---|---|
| Offers | Prijs, voorraad, levertijd en of een artikel te koop is | Bodemprijs en plafond in je eigen systeem; nooit een prijs schrijven zonder die controle |
| Orders en shipments | Orders ophalen, zendingen aanmelden (meerdere artikelen per zending, meerdere zendingen per orderregel) | Track-&-trace meesturen; de norm telt mee in je kwaliteitsscore |
| Commissions | Commissie per EAN en per prijs opvragen | Gebruik dit voor je bodemprijs in plaats van een categoriegemiddelde |
| Insights en competing offers | Concurrerende aanbiedingen, koopblokstatus, prijssterren | Rate limits; per land apart opvragen (NL en BE) |
| Invoices | Facturen en specificaties ophalen voor je boekhouding | Maandelijks, niet dagelijks |
| Returns en customer questions | Retouren verwerken, vragen ophalen | Ophalen automatiseren, afhandelen door een mens |
Rate limits: wacht vóór de limiet, niet erna
bol geeft per onderdeel een limiet voor het aantal verzoeken. Wie erover gaat, krijgt een 429 en moet wachten; onder load betekent dat vertraagde prijzen en verouderde marktdata. De praktische regel: houd zelf bij hoeveel ruimte er nog is en wacht al vóór de limiet, met een marge van zo'n twintig procent. Een koppeling die bij een 429 "gewoon opnieuw probeert", maakt het probleem groter. Bij meerdere verkoopaccounts in één systeem houd je per account een eigen budget bij, zodat één drukke klant niet de rest blokkeert.
Wat je beter niet automatiseert
- Productcontent. Titels en specificaties automatisch overschrijven vanuit een feed klinkt handig, tot een lege kolom in de feed je beste titel wist. Content wijzigen met controle vooraf.
- Annuleringen. Een automatische annulering bij "voorraad 0" kost kwaliteitsscore. Liever: voorraad op nul zetten vóór de order binnenkomt, en een order die toch binnenkomt handmatig beoordelen.
- Prijzen zonder bodem. Elke prijsregel zonder bodemprijs per artikel is een verliespost die wacht op een concurrent zonder bodem.
- Antwoorden op klantvragen. Ophalen en toewijzen is prima; het antwoord zelf schrijft een mens, binnen 24 uur.
Zelf bouwen of een tool gebruiken
Zelf bouwen loont als je een eigen systeem (ERP, webshop) hebt dat de bron van waarheid is en je ontwikkelcapaciteit hebt om per resource-versie te migreren. In alle andere gevallen is een tool goedkoper: de leverancier draagt de migraties, de rate limits en de process-status-afhandeling. Vraag bij de keuze drie dingen: op welke API-versie per onderdeel de tool zit, of je prijsvoorstellen in dry-run kunt zien voordat ze worden geschreven, en of elke schrijfactie wordt gelogd met het resultaat uit de process status.
Checklist voor een veilige koppeling
- Eigen API-sleutels per verkoopaccount, versleuteld opgeslagen.
- Elke schrijfactie gelogd: wat, wanneer, process-status-id, resultaat.
- Bodemprijs en plafond per EAN vóór elke prijswijziging gecontroleerd.
- Rate-limit-budget per onderdeel en per account, met wachten vóór de limiet.
- Dry-run-stand waarin niets naar bol wordt geschreven.
- Een overzicht van de gebruikte resource-versies en hun einddata.