Lightspeed eCom koppeling met ERP, boekhouding, magazijn en leveranciers

Wat is Lightspeed eCom en wie gebruikt het?

Lightspeed eCom is het gehoste webshopplatform van Lightspeed. Lightspeed draait de servers; jij richt de shop in. Europese shops draaien op het cluster eu1, met de API op api.webshopapp.com, Amerikaanse op us1. Lightspeed heeft daarnaast een kassasysteem. Webshop en kassa kunnen los draaien of omnichannel aan elkaar hangen, en dat verschil bepaalt wat een koppeling kan.

De eerste vraag bij een Lightspeed-koppeling is dus welke van de twee je hebt. De kassakant staat op Lightspeed kassa koppeling.

Wat je met Lightspeed koppelt

Lightspeed is leidend voor orders en webklanten. Voorraad, prijzen en productgegevens komen uit het ERP, het magazijn of de leverancier.

Prijs, voorraad, SKU, EAN en artikelcode staan in Lightspeed niet op het product maar op de variant. Ook een product zonder maten of kleuren heeft één variant, en daar schrijft de koppeling naar. Een variant is te vinden op sku, ean of article_code; de koppeling bewaart na de eerste ronde het variant-ID. Zie voorraad en beschikbaarheid en orders, klanten en verzending.

Hoe Lightspeed data vrijgeeft

Sleutel en geheim

De eCom API is een REST API met JSON of XML. Toegang loopt met een API-sleutel en een geheim per shop, als HTTP Basic-authenticatie. De taal staat in het pad, direct na het adres van het cluster: /nl/products.json geeft Nederlandse teksten, /en/products.json Engelse. De taal moet in de shop actief zijn. Een koppeling die titels en omschrijvingen schrijft, doet dat per taal.

Limieten per shop

Boven de grens antwoordt Lightspeed met 429 Too Many Requests. De limieten gelden per API-sleutel van de shop. Lightspeed verhoogt ze op verzoek per account; de echte waarden staan in GET /account/ratelimit.json, met per venster limit, remaining en reset. Zie Lightspeed's pagina over rate limiting.

De rekensom

Een lijst geeft standaard 50 resultaten per aanroep en maximaal 250. Een volledige voorraad- en prijsronde over 15.000 varianten:

• Lezen: 15.000 / 250 = 60 aanroepen.
• Per variant schrijven: 15.000 aanroepen. Bij 3.000 per uur is de daglimiet van 12.000 na 4 uur op, en de laatste 3.000 wachten tot de volgende dag. Orders ophalen kan in die tijd niet meer.
• In bulk schrijven: PUT /variants/bulk.json neemt maximaal 100 varianten per aanroep. 15.000 / 100 = 150 aanroepen, plus 60 om te lezen is 210. Dat past ruim in één venster van 5 minuten.

Na de eerste ronde schrijft de koppeling alleen varianten waarvan voorraad of prijs is veranderd. De ruimte die overblijft gaat naar orders en zendingen. Je eigen aantallen reken je door met doorvoer berekenen.

{
  "variant": [
    { "id": 196847073, "stockLevel": 14, "priceIncl": 108.30 },
    { "id": 196847074, "stockLevel": 0,  "priceIncl": 108.30 }
  ]
}

Webhooks

Webhooks zijn er voor orders, klanten, zendingen, facturen, retouren, producten, varianten en offertes, met de acties created, updated en deleted, en voor orders ook paid en shipped. Elke melding draagt de header x-signature, een MD5-hash van de inhoud plus het API-geheim. Lightspeed verwacht binnen 5 seconden een 2xx-antwoord. Daarna volgen tot 10 pogingen in 24 uur. Faalt meer dan 50% van de meldingen van een webhook, dan krijgt de eigenaar een e-mail; is dat na 50 uur nog zo, dan wordt de webhook uitgezet.

De koppeling zet een melding direct in een wachtrij en antwoordt meteen. Een controleronde met updated_at_min haalt elke paar minuten op wat er sinds de vorige ronde is gewijzigd. Zie wat is een webhook.

Waar het bij Lightspeed op vastloopt

Prijs inclusief en exclusief btw

Een variant heeft priceIncl en priceExcl. In het bulkvoorbeeld in Lightspeed's eigen documentatie gaan priceIncl 100 en priceExcl 82.6 erin, en komt priceExcl 82.6446 terug: de prijs exclusief wordt uit de prijs inclusief berekend, op vier decimalen. Een ERP met nettoprijzen levert 89,50; de koppeling rekent 89,50 x 1,21 = 108,295 en schrijft 108,30 inclusief. Lightspeed maakt daar 108,30 / 1,21 = 89,5041 exclusief van. Dat is 0,0041 per stuk meer dan in het ERP; bij 10 stuks verschillen order en factuur al 4 cent. Zie bedragen en btw mappen.

Adressen in losse velden

Een Lightspeed-order heeft per adres addressShippingStreet, addressShippingStreet2, addressShippingNumber en addressShippingExtension. Dat sluit aan op een ERP met straat, huisnummer en toevoeging. Maar het eigen veld is niet altijd gevuld: in Lightspeed's eigen voorbeeldorder staat het huisnummer in de straat, 123 viger, en is addressBillingNumber leeg. Een order met een leeg addressShippingNumber en Dorpsstraat 12 A in de straat wordt door de koppeling gesplitst; lukt dat niet, dan komt de order op een controlelijst. Het land komt als code (nl) en als code3 (nld). Zie adresvelden mappen.

Voorraad bij meerdere winkels

stockLevel is één getal per variant. Staat multishop aan, dan is het de totale voorraad over alle shops. Een ERP met 20 stuks in het magazijn en 6 in een winkel moet dus kiezen welk getal de webshop krijgt. stockTracking bepaalt wat er bij 0 gebeurt: enabled stopt de verkoop, indicator laat bestellen op nabestelling toe, disabled houdt geen voorraad bij. Zie welke voorraad toon je in je webshop.

Systemen die we aan Lightspeed koppelen

De combinatie met een eigen pagina: Lightspeed Exact Online koppeling. De systemen zelf: Exact Online koppeling, AFAS webshop koppeling, Picqer-koppeling en Lightspeed kassa koppeling. Andere platformen: Shopify koppeling en WooCommerce koppeling. Alle stromen staan op koppelingen.

Wij bouwen de koppeling voor een vaste prijs op jouw shop en jouw systemen, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor livegang draait hij als dry run: je ziet per variant welke voorraad en prijs er in Lightspeed zou komen, zonder dat er iets wijzigt. Vertel hoeveel varianten je hebt en of je kassa omnichannel meedoet.