bol koppeling: je webshop en ERP koppelen aan bol

Wat is bol en hoe verkoop je er via een koppeling?

bol is een online warenhuis en marktplaats voor Nederland en België. Als verkoper (retailer) zet je een aanbod op een bestaand product, herkend aan de EAN, met je eigen prijs, voorraad en levertijd. Je beheert dat in het verkopersdashboard of via de Retailer API.

Voor een koppeling telt vooral wie de voorraad heeft en wie verzendt. bol kent drie vormen, en elk vraagt een andere stroom:

Bij zelf verzenden en VVB is je ERP of magazijn de bron van de voorraad en moet de koppeling orders binnen de levertermijn afmelden. Bij Logistiek via bol, in de API FBB, ligt de voorraad bij bol en komen orders alleen ter informatie binnen: voor je boekhouding en je voorraadadministratie.

Wat je met bol koppelt

Een bol-order bestaat uit orderregels met elk een eigen orderItemId. Je verzendt, annuleert en retourneert per orderregel, niet per order. Een order met drie artikelen kan dus in twee zendingen gaan, en de koppeling houdt per regel quantityShipped en quantityCancelled bij. Hoe dat in je ERP landt staat op orders, klanten en verzending.

Hoe bol data vrijgeeft

OAuth2 met client credentials

Je maakt een client-id en client-secret aan in het verkopersdashboard, onder Instellingen, API instellingen. bol vraagt eerst de gegevens van een technisch contactpersoon; zonder die gegevens krijg je geen toegang, en bol neemt via dat contact op bij verkeerd gebruik van de API. Met de credentials vraag je een token op bij https://login.bol.com/token.

{
  "access_token": "eyJraWQiOiJyc2Ey...",
  "token_type": "Bearer",
  "expires_in": 299,
  "scope": "retailer"
}

Een token is 299 seconden geldig en moet hergebruikt worden tot hij verloopt. bol schrijft dat wie per aanroep een nieuw token vraagt de inlogdienst overbelast en een IP-blokkade krijgt; de limieten van die dienst liggen veel lager dan die van de API. De koppeling leest de vervaltijd uit het token en vernieuwt hem kort daarvoor.

Limieten per endpoint

bol stelt geen limiet per account in maar per endpoint en methode, en publiceert de actuele waarden op een openbaar endpoint met rate limits. Op 3 oktober 2026:

Boven de limiet geeft bol een 429, en elke response bevat headers met het resterende budget en het moment waarop het weer aanvult. bol houdt een groot aantal 429's bij en neemt dan contact op, dus de koppeling remt af op de headers in plaats van door te gaan tot de fout.

De rekensom voor voorraad: 15.000 aanbiedingen bijwerken met 50 aanroepen per seconde is 15.000 / 50 = 300 seconden, 5 minuten. bol vraagt uitdrukkelijk om dat niet elk uur te doen, maar alleen de aanbiedingen te sturen waarvan voorraad of prijs echt veranderd is, op het moment dat het verandert. De koppeling stuurt daarom alleen wijzigingen en draait de volledige vergelijking één keer per nacht.

Pushberichten en asynchrone verwerking

De Subscriptions API levert berichten als webhook, naar Google Pub/Sub of naar Amazon SQS. Voor orders zijn dat ORDER_CREATED en ORDER_ITEM_CANCELLATION_REQUEST, voor zendingen UPDATE_TRANSPORT_EVENT. Een webhook moet binnen 5 seconden een 2xx geven. bol probeert een mislukt bericht 10 keer in 10 minuten, gooit het daarna weg en zet het abonnement uit als het adres al die tijd onbereikbaar was. Berichten komen minstens één keer, soms dubbel en soms in de verkeerde volgorde. Zie wat is een webhook.

Daarom vraagt de koppeling naast de berichten elke paar minuten de orderlijst op met change-interval-minute, iets ruimer dan het interval: elke 10 minuten opvragen met een venster van 12 minuten, zoals bol zelf aanraadt. Het maximum van dat venster is 60 minuten.

Zendingen en annuleringen zijn asynchroon. bol antwoordt met 202 en een processStatusId, en pas de processtatus SUCCESS zegt dat de zending is vastgelegd. FAILURE of TIMEOUT betekent dat de zending niet bestaat, ook al gaf de eerste aanroep geen fout.

Waar het bij bol op vastloopt

Orders die de koppeling niet ziet

GET /retailer/orders geeft zonder parameter alleen open orders met fulfilment-method FBR. Een koppeling die de parameter niet op ALL zet, mist alle orders van Logistiek via bol in de boekhouding. Afgehandelde orders staan 48 uur in de lijst; daarna zijn ze alleen nog per order-id op te vragen, tot drie maanden terug. Een koppeling die een paar dagen heeft stilgelegen, moet dus met latest-change-date per dag terugzoeken, een parameter die bol alleen voor noodgevallen bedoeld heeft.

Voorraad: amount, correctedStock en Logistiek via bol

Je stuurt amount: de voorraad in je eigen magazijn. bol rekent daaruit correctedStock, je voorraad min open en verwerkte orders. Bij nul gaat het aanbod offline. Hoe bol rekent hangt af van managedByRetailer: op false trekt bol alle open orders af, op true alleen de orders die na je laatste update binnenkwamen. Een ERP dat zijn eigen reserveringen al heeft afgetrokken, met de vlag op false, laat bol dezelfde orders dubbel aftrekken. Dan gaat een artikel offline terwijl het nog op voorraad ligt.

Bij Logistiek via bol telt amount niet mee: die voorraad lees je uit GET /retailer/inventory. Wie zowel uit eigen magazijn als via bol verkoopt, houdt per artikel twee getallen bij. Een buffer per kanaal tegen oververkoop staat op veiligheidsvoorraad.

Annuleringen en de servicenorm

Een klant kan annuleren tot de order verzonden is; de orderregel krijgt dan cancellationRequest true. Ligt er een nacht tussen ophalen en verzenden, dan vraagt de koppeling de order vlak voor de zending opnieuw op. Zo'n verzoek bevestig je met reden REQUESTED_BY_CUSTOMER en dat telt niet mee in je score. Dezelfde reden zonder verzoek van de klant telt wel mee. Annuleer je zelf, bijvoorbeeld bij een voorraadfout, dan telt dat mee in de servicenorm Annuleringen: maximaal 2% van de bestelde artikelen per week. Een order die op de derde dag na de beloofde leverdatum nog open staat, annuleert bol zelf, ook met gevolgen voor de norm.

Klantgegevens en adres

unitPrice en totalPrice zijn inclusief btw, met de commissie per orderregel in commission. Een ERP dat verkoopprijzen exclusief btw boekt, rekent terug per regel. Zie adresvelden mappen.

Platformen en systemen die we aan bol koppelen

Aan de ERP-kant: Exact Online koppeling, AFAS webshop koppeling en Business Central koppeling. Voor het magazijn: Picqer koppeling, GoedGepickt koppeling en Monta koppeling. Voor productdata naar meer marktplaatsen tegelijk staat het op Channable koppeling. Je webshop houdt dezelfde voorraad bij via Shopify koppeling of WooCommerce koppeling. Alle stromen staan op koppelingen.

We bouwen de koppeling voor een vaste prijs en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Elke zending wacht in de wachtrij op SUCCESS; een FAILURE komt op de controlelijst met de foutmelding van bol in plaats van stil te verdwijnen. Vertel welk ERP of magazijn je naast bol gebruikt, dan hoor je welke stromen erbij horen.