De Seller API van Kaufland kom je tegen als je zelf iets wilt automatiseren of als software om je sleutels vraagt. Dan wil je weten wat die sleutels kunnen, waar ze staan en wat er gebeurt als je ze kwijtraakt.
Alles over de techniek komt uit de API-documentatie van Kaufland zelf; de bronnen staan onderaan.
Wat de Seller API is
De Kaufland Marketplace Seller API is een REST-API. Je stuurt versleutelde HTTPS-verzoeken naar een vast adres, zoals https://sellerapi.kaufland.com/v2/ in de voorbeelden van Kaufland, en krijgt gegevens terug of voert een handeling uit. Denk aan bestellingen ophalen, aanbiedingen aanpassen of een verzending melden.
Kaufland beschrijft de authenticatie als “password and HMAC based”. Dat betekent: je hebt twee sleutels en elk verzoek draagt een handtekening die je met de geheime sleutel berekent. De geheime sleutel zelf gaat niet mee in het verzoek. Anoniem gebruik is niet mogelijk.
De twee sleutels
- Client key: 32 tekens. Deze identificeert jouw account bij elk verzoek.
- Secret key: 64 tekens. Hiermee onderteken je elk verzoek. Wie deze sleutel heeft, kan namens jou met de API werken.
Je maakt de sleutels aan in het Seller Portal, op de pagina met API-instellingen. Kaufland schrijft erbij dat verloren sleutels om veiligheidsredenen niet terug te halen zijn. Je kunt alleen nieuwe genereren.
Genereer je nieuwe sleutels, dan vul je die opnieuw in bij alles wat met je account praat: eigen scripts, maar ook software die je hebt gekoppeld.
Hoe een verzoek eruitziet
Elk verzoek heeft vijf vaste headers nodig. Volgens de documentatie zijn dat:
| Header | Wat erin staat |
|---|---|
| Accept | Altijd application/json. |
| Shop-Client-Key | Je client key. |
| Shop-Timestamp | Het tijdstip van het verzoek als Unix-tijd in seconden, hooguit 5 minuten naast de tijd van Kaufland. |
| Shop-Signature | De handtekening, berekend met je secret key. |
| User-Agent | De naam van je software, of Inhouse_development als je de koppeling zelf bouwt. |
Bij POST- en PATCH-verzoeken komt daar Content-Type: application/json bij. De handtekening is een HMAC-SHA256 over vier onderdelen, onder elkaar gezet met een regeleinde: de methode (GET, POST enzovoort), de volledige URI, de body en de timestamp. Klopt één teken niet, dan klopt de handtekening niet en wordt het verzoek niet uitgevoerd. Kaufland heeft een Signature Calculator om je eigen berekening na te lopen.
Loopt de klok van je server meer dan 5 minuten voor of achter, dan krijg je foutmeldingen die op een verkeerde sleutel lijken. Laat je server de tijd automatisch synchroniseren voordat je aan de sleutels gaat twijfelen.
De limiet: 111 verzoeken per seconde
Kaufland hanteert een limiet van 111 verzoeken per seconde per verkoper, opgeteld over alle endpoints. Ga je daarboven, dan krijg je HTTP-status 429 terug.
De limiet geldt per verkoper: alle programma’s op je account delen hem. Heb je grote aantallen aanbiedingen, verdeel de verzoeken dan over de tijd.
Bouw je zelf, vang 429 dan netjes af: even wachten en opnieuw proberen, in plaats van direct weer vol gas.
Waar verkopers de API voor gebruiken
Er zijn grofweg twee routes.
- Zelf bouwen. Een eigen script dat bijvoorbeeld voorraad uit je magazijnsysteem naar Kaufland zet, of bestellingen ophaalt voor je boekhouding. Dan zorg je zelf voor ondertekening, limieten en foutafhandeling.
- Software koppelen. Je vult je client key en secret key in bij een programma dat al met de API praat. Dat programma doet het werk en jij bepaalt wie je sleutels krijgt.
Sellgrip volgt de tweede route. Het koppelt via de Kaufland Seller API: je vult je client key en secret key in en Sellgrip slaat ze versleuteld op. Daarna leest Sellgrip onder meer je bestellingen en producten en maakt er meldingen van als er geld of een termijn op het spel staat. Welke onderdelen er zijn, staat op de pagina Functies.
Je sleutels veilig houden
De secret key is een wachtwoord met volle rechten. Behandel hem ook zo.
- Nooit in een e-mail of chat. Een sleutel die in een mailbox staat, staat er over drie jaar nog.
- Niet in code die je deelt. Zet sleutels in een instellingenbestand of omgevingsvariabele, buiten versiebeheer.
- Bijhouden wie ze heeft. Een lijstje met elk programma en elke persoon die je sleutels gebruikt, maakt het vervangen overzichtelijk.
- Vervangen bij twijfel. Vertrekt een medewerker of stop je met een programma, genereer dan nieuwe sleutels en koppel opnieuw wat je wilt houden.
Waar de documentatie staat
Kaufland publiceert de documentatie op sellerapi.kaufland.com, met een overzicht van alle endpoints en een aparte pagina over limieten. De documentatie is in het Engels. Voor verzendmeldingen via de API gebruik je de vervoerderscodes die Kaufland daar publiceert; meer over het melden van verzendingen staat in Verzendlabels en verzendmelding op Kaufland.
