Retailer API v10 OAuth2 NL + BE

Bol.com Seller API-integratie die wél schaalt

Voor professionele sellers met eigen ERP, WMS of PIM. Geen generieke plug-in, maar een maatwerk-koppeling die orders, voorraad, shipments en returns automatisch afhandelt — met jouw business-regels, jouw grootboekrekeningen, jouw carriers.

Plan een intake Technische details

// POST /orders/{id}/shipment

Authorization: "Bearer eyJhbGc..."

Accept: "application/vnd.retailer.v10+json"

{

"orderItems": [{...}],

"transport": {

"transporterCode": "TNT",

"trackAndTrace": "3SAB..."

}

Wat is een Bol.com Seller API-koppeling precies?

Bol.com heeft twee rollen: verkoper (jij, via het Verkopersdashboard) en platform. De Retailer API is de brug tussen die twee: elke handeling die je normaal via het dashboard doet — order bevestigen, voorraad aanpassen, retour afhandelen — kan automatisch vanuit jouw eigen systemen.

Voor kleine volumes volstaat een pre-built connector uit een marketplace-tool. Maar zodra je te maken krijgt met meerdere magazijnen, multi-channel-logistiek, eigen prijsregels of BTW-complexiteit (NL + BE + OSS), loop je tegen hun grenzen aan. Dan is een eigen integratie efficiënter en goedkoper op lange termijn.

Wij bouwen die koppeling specifiek voor jouw ERP-stack: of dat nu Exact Online, AFAS, Navision, SAP Business One, Microsoft Dynamics of een custom .NET-applicatie is. De Retailer API zelf is alleen de bron — de waarde zit in hoe die data in jouw financiële, logistieke en marketing-processen valt.

Van intake tot go-live in vier stappen

Discovery & scoping

We brengen je huidige flow in kaart: welke systemen (ERP/WMS/PIM), welke bol.com-accounts (NL/BE), orders per dag, uitzonderings-cases (LVB, bol.com Plus, dropshipping). Resultaat: RFC met architectuur en prioritering.

Technisch ontwerp

Data-mapping tussen bol.com-entiteiten en jouw ERP/WMS-schema: order-states, artikel-SKUs, klant-data, BTW-behandeling NL/BE. OAuth2-credentials en vault-setup. Staging-omgeving bij bol.com wordt ingericht.

Bouw & iteratie

Koppeling gebouwd in Node.js of .NET (afhankelijk van je stack) met queue-based architectuur. Sprints van 2 weken: eerst orders → shipments → voorraad → returns → content. Dashboards met Grafana of Datadog voor monitoring.

Go-live & beheer

Soft-launch met beperkte artikelen, monitoring van error-rate en SLA. Na stabilisatie volledige uitrol. SLA-afspraken over uptime, response-time bij incidenten en kwartaal-reviews voor API-versie-migraties.

Functionaliteiten die we standaard afdekken

Order-polling & webhooks

Orders worden elke X minuten opgehaald of real-time via de aangekondigde webhooks verwerkt. Duplicates voorkomen we met idempotency-keys en een lokale staging-laag die orders eerst valideert voordat ze in jouw ERP landen.

Voorraad-sync ERP ↔ bol

Je master-voorraad in ERP of WMS wordt ge-pusht naar bol.com via het Offers-endpoint. Bij multi-warehouse respecteren we je allocatie-regels: bv. 80% naar bol.com, 20% buffer voor eigen webshop.

Shipments & track & trace

Na pick&pack in jouw WMS registreren we shipments met track & trace-codes bij bol.com. Carrier-mapping (PostNL, DHL, DPD, UPS) staat in config — nieuwe carriers voeg je zonder code-wijziging toe.

Commission-fee verwerking

Commission-facturen van bol.com koppelen we aan de originele order in jouw boekhouding, zodat je marges per order reëel ziet. Split in grootboekrekeningen voor marketplace-fee, advertising-fee en bol.com-logistiek mogelijk.

Returns-afhandeling

Retourmeldingen triggeren credit-flows in je ERP, voorraad-terugboekingen en klant-communicatie. Auto-accept voor niet-behandelde retouren na configurabele tijd (default 14d). Dashboards laten retour-reasons en outliers zien.

Content & catalogus-beheer

Productomschrijvingen, afbeeldingen, specificaties en EAN-koppelingen sync je vanuit je PIM (Akeneo, Pimcore, Shopware) naar bol.com via het Content-endpoint. Wijzigingen worden als delta verstuurd om quota te sparen.

Typische integratie-scenario's

Multi-channel seller

Webshop (Shopware / Magento / custom) + bol.com + Amazon delen één voorraad in je WMS. Onze middleware verdeelt stock per kanaal volgens jouw regels en voorkomt overselling met een real-time lock.

Traditionele groothandel die bol.com erbij doet

Je verkocht altijd B2B via je ERP en wilt nu B2C op bol.com. We zetten een aparte divisie op in je ERP, dedicated artikel-SKUs met bol.com-specifieke omschrijvingen en een aparte btw-flow.

Dropshipping via leverancier-feeds

Je voorraad komt van externe leveranciers (via EDI, API, of dagelijkse FTP). We aggregeren die feeds en pushen ze naar bol.com, met configurabele buffers en exclusion-regels voor leverancier-uitval.

Private label met PIM-sync

Je eigen merk vereist actueel content-management. Vanuit Akeneo of Pimcore sync je productomschrijvingen, rich content en varianten naar bol.com via het Content-endpoint. Delta-sync voorkomt onnodige API-calls.

Technische stack en architectuur

Kern-endpoints die we gebruiken

GET /retailer/orders

PUT /retailer/orders/{orderItemId}/shipment

POST /retailer/offers

PUT /retailer/offers/{offerId}/stock

GET /retailer/returns

POST /retailer/returns/{rmaId}/handle

GET /retailer/insights/offer

GET /retailer/invoices

Architectuur-principes

Queue-based: elke API-call is een message in RabbitMQ of AWS SQS. Workers zijn stateless en kunnen horizontaal schalen bij piekbelasting (zoals Black Friday).

Idempotent: elke operatie (shipment, offer-update) heeft een idempotency-key gebaseerd op jouw order-ID of SKU. Retries na timeouts creëren nooit duplicates.

Observability: logs naar Datadog of Grafana Loki, metrics naar Prometheus, alerts op error-rate en queue-depth. Je weet binnen 5 minuten als bol.com down is of als jouw backend traag wordt.

Secret-management: client_id + client_secret in een vault (HashiCorp, AWS Secrets Manager). Nooit in je repo of environment-files.

Waarom Appfront?

Marketplace-kennis

We kennen niet alleen bol.com maar ook Amazon (SP-API), Marktplaats Pro en Beslist. De concepten (seller-APIs, commission-modellen, returns-logica) zijn vergelijkbaar genoeg om snel te switchen of te combineren.

ERP-ervaring

Ons team heeft productie-koppelingen in Exact Online, AFAS, Navision, SAP en Dynamics. We weten waar de datamodellen knellen (BTW in NL vs BE, administratie-splits) en bouwen daar omheen.

Vast aanspreekpunt

Geen team-wissels of offshore-handovers. De developer die je koppeling bouwt is ook degene die na go-live incidents oppakt. Short communication-loops, geen tickets die wegraken.

Security & compliance

Je bol.com-credentials zijn kroonjuwelen: wie ze heeft kan jouw orders wijzigen, prijzen saboteren of voorraad nullen. Wij behandelen ze met de zorg die ze verdienen.

Secret-storage in een dedicated vault (HashiCorp Vault of AWS Secrets Manager), nooit in je codebase of .env-files. Audit-logs op alle API-calls, 90d bewaartermijn. IP-whitelisting waar mogelijk. AVG-compliant opslag van klantdata (naam, adres, email): encrypt at rest, retentie per jouw beleid, sub-processor agreements.

Wij hosten bij voorkeur binnen de EU (Hetzner, AWS eu-central-1, Azure West Europe) en doen pentests waar relevant voor jouw sector.

Veelgestelde vragen

Wat is de Bol.com Retailer API precies?

De Bol.com Retailer API (momenteel v10) is de officiële REST-interface waarmee verkopers op bol.com hun verkoopproces programmatisch kunnen afhandelen. In plaats van handmatig via het Verkopersdashboard te werken, haalt jouw eigen ERP of WMS orders op, bevestigt ze, registreert verzendingen en verwerkt retouren. Voor sellers met meer dan enkele tientallen orders per dag is deze koppeling noodzakelijk om schaalbaar te blijven.

Voor welke sellers is een maatwerk-koppeling zinvol?

Als je meer dan 50-100 orders per dag doet, meerdere kanalen bedient (eigen webshop + bol.com + Amazon), of specifieke voorraad-logica hebt (meerdere magazijnen, dropshipping, pre-orders), loop je tegen de limieten van off-the-shelf connectoren aan. Eigen koppelingen bieden fijnmazige controle: je bepaalt welke offers wanneer geupdate worden, hoe je met stockouts omgaat en hoe je commission-fees naar je boekhouding schrijft.

Welke endpoints en entiteiten dekken we af?

De Retailer API heeft resources voor Orders (ophalen, ship, cancel), Shipments (aanmaken, transport-labels), Returns (ophalen, handled/niet-handled), Offers (CRUD op prijs/voorraad/delivery), Inventory (LVB-voorraad voor bol.com-logistiek), Insights (performance & verkoopdata), Invoices (commission-facturen), Product Content (catalogus) en Replenishments. In de meeste koppelingen focussen we eerst op orders en offers, daarna shipments/returns en als laatste content en insights.

Hoe zit authenticatie in elkaar (OAuth2)?

Bol.com gebruikt OAuth2 client-credentials flow. Je registreert een API-account in het Verkopersdashboard, krijgt een client_id en client_secret, en wisselt die in op `/token` voor een access token dat 299 seconden geldig is. Elke API-call gebruikt een `Bearer` header plus een Accept-header voor de versie (`application/vnd.retailer.v10+json`). Wij regelen het token-refresh en het secret-beheer (bij voorkeur via een vault).

Hoe gaan jullie om met rate-limits?

Bol.com hanteert rate-limits per endpoint en retourneert een `Retry-After` bij overschrijding. Wij implementeren exponential backoff met jitter, queue-gebaseerde worker-pools (bv. RabbitMQ of AWS SQS) en batching waar mogelijk. Voor offer-updates gebruiken we de bulk-endpoint i.p.v. single-offer calls om quota te sparen. Idempotentie op ons systeem zorgt dat retries nooit dubbele shipments aanmaken.

Kunnen jullie onze bol.com-koppeling in onze Exact Online / Navision / SAP boekhouding leggen?

Ja. We koppelen regelmatig bol.com aan Exact Online, Navision, SAP Business One, AFAS Profit en Microsoft Dynamics 365. Orders vloeien vanuit bol.com naar het ERP als verkooporders of direct als facturen, en commission-facturen van bol.com worden als inkoopfactuur ingeboekt. Voorraadmutaties gaan de andere kant op. Bij meerdere kanalen (eigen webshop + bol) zorgen we dat elk kanaal zijn eigen grootboekrekeningen/dimensies raakt.

Wat gebeurt er bij een retour of annulering?

Zowel annuleringen (order nog niet verzonden) als retouren (order al geleverd) haalt de API als events op. In jouw ERP maken we creditnota's aan, boeken we voorraad terug en triggeren we eventueel een uitbetaling via je PSP. Onhandled returns worden automatisch na 14 dagen geaccepteerd door bol.com — wij stellen dashboards/alerts in zodat je klant-service tijdig kan reageren op uitzonderingen.

Hoe lang duurt zo'n integratie ongeveer?

Een standaardintegratie (orders + shipments + voorraad-sync met één ERP of WMS) is meestal 4-8 weken: 1-2 weken discovery en mapping, 3-4 weken ontwikkeling, 1-2 weken testen met stagingomgeving en go-live met real orders. Uitgebreide scenario's met content-sync, dynamic pricing of multi-warehouse kosten 10-16 weken. We werken in sprints zodat je elke twee weken werkende functionaliteit ziet.

Wat kost beheer en monitoring na oplevering?

Bol.com verandert regelmatig zijn API-versies (v8 → v9 → v10) met breaking changes, dus na go-live doen we monitoring (error-rate, latency, queue-depth), kwartaal-reviews en migraties bij nieuwe versies. Vaste maandelijkse bedragen afhankelijk van volume en kritikaliteit — startpakket vanaf een paar uur per maand voor alerting, uitbreidbaar met feature-ontwikkeling en nieuwe endpoints naar behoefte.

Klaar om je bol.com-kanaal écht te schalen?

Plan een vrijblijvend gesprek — we bekijken je huidige flow en schetsen welke koppelingen het meeste opleveren.

Plan een intake Bel direct 085 401 1220

Actuele context (mei 2026)

REST-architectuur is inmiddels de de-facto standaard voor web-API's, gebaseerd op stateless HTTP-requests en resource-oriented URLs — een patroon dat Roy Fielding in 2000 in zijn dissertatie definieerde.

Bron: MDN Web Docs — REST (developer.mozilla.org)