CycleSoftware API koppelen aan je webshop.

CycleSoftware is bedrijfssoftware voor de tweewielerbranche, gemaakt door CycleSoftware B.V. in Nistelrode. Het is geen voorraadpakket alleen: kassa, voorraad, pakbonverwerking, verkoopregistratie, werkplaatsplanning en verhuur zitten er allemaal in, en het draait online.

Voor een fietsenwinkel is dat het systeem waar de dag in begint en eindigt. Dat is ook meteen het uitgangspunt van een koppeling: de winkel blijft in CycleSoftware werken en de website haalt op wat daar staat. Twee plekken waar je voorraad bijhoudt is geen koppeling maar een probleem.

Twee kanten op, en dat is wat deze koppeling anders maakt dan een gewone voorraadfeed.

Naar je site gaan de tweewielers en de artikelen, met de voorraadstand van dat moment, de voorraadindicatie van je leverancier, je winkel- of webshopprijs en de volledige productinformatie met foto’s en de DST-productcategorieën. Dat laatste is wat je zoekfilters en je categoriepagina’s voedt.

Terug komen de bestellingen. Een order uit je webshop verschijnt in CycleSoftware met de producten en de klantgegevens erbij, zodat je hem afhandelt vanuit hetzelfde systeem als een verkoop aan de balie. Met de webhooks-API krijg je daarnaast bericht bij wijzigingen in orders, offertes, werkplaats en facturen, zodat je site niet hoeft te blijven vragen of er al iets is.

De toegangsgegevens komen van CycleSoftware zelf of staan in de gebruikersaccounts; heb je ze niet, dan vraag je ze aan bij support@cyclesoftware.nl. Je meldt je aan met HTTP Basic Authentication, met gebruikersnaam en wachtwoord, en de api-key erbij. Alles gaat over HTTPS, en CycleSoftware raadt gzip aan.

Let op het land. Er zijn aparte adressen voor Nederland, België en Frankrijk: api.cyclesoftware.nl, api.cyclesoftware.be en api.cyclesoftware.fr. Heeft een account meer dan één winkel, dan geef je met dealer_id aan om welke winkel het gaat.

Voor een webshop tellen drie onderdelen. De artikeldata voor e-commerce komt uit versie 4 van de API, met de voorraad erbij. Een bestelling gaat terug met saveorder, en met getorderstatus vraag je op hoe het met die order staat.

Een testomgeving noemt de documentatie niet. Wij beginnen daarom met alleen ophalen, zodat er niets in de kassa verandert, en zetten het wegschrijven van orders pas aan als artikelen en voorraad kloppen. Een geweigerde aanroep komt terug met een veld error en een error_message; die loggen we, want daar staat in waarom. Of de webshop daarna op WooCommerce, Shopify of maatwerk draait, staat bij Design & Development.

Dit is het punt waar een integratie misgaat, en het is geen detail. De CycleSoftware API limiteert het aantal aanvragen per endpoint: 360 per minuut en 15.000 per dag. Elk antwoord vertelt in de headers X-RateLimit-Minutely-Remaining en X-RateLimit-Daily-Remaining hoeveel je er nog over hebt, en ga je eroverheen dan krijg je een 429 terug en niets anders.

De verleiding is om de voorraad live op te vragen bij elke bezoeker, want dan klopt hij altijd. Dat gaat goed tot de eerste drukke dag. Wij halen daarom periodiek op en bewaren het aan onze kant, en vragen alleen de voorraadstand van één artikel live op waar dat echt uitmaakt, zoals op de productpagina zelf.

Hoe vaak dat moet hangt af van je winkel. Een fiets die één keer verkocht wordt vraagt iets anders dan een band die je met tientallen tegelijk hebt liggen. Die afweging maken we per klant, en we zetten er een melding op als het ophalen stilvalt. Niet elk systeem telt zo: de Itsperfect API rekent per uur, met 750 aanroepen, en daar hoort een ander ophaalritme bij.

DST is de branchestandaard voor artikeldata in de tweewielerbranche. Leveranciers leveren hun producten daar op één manier aan, en CycleSoftware gebruikt die data.

Voor een webshop is dat precies wat je nodig hebt. Merk, maat, kleur, framehoogte en motorvermogen zijn losse velden en geen zinnen in een omschrijving, dus je kunt er echt op filteren. Zonder zo’n standaard eindig je met filters die op tekst zoeken en dan valt de helft van je aanbod eruit omdat de ene leverancier "28 inch" schrijft en de andere "28".

Eén ding om rekening mee te houden: niet elk merk levert volledig aan. Wij bouwen de filters daarom zo dat een ontbrekend veld een product niet uit de resultaten haalt, want anders verdwijnt precies het aanbod waar de gegevens nog niet compleet van zijn.