blog·4 min lezen

78 prijslijsten en tienduizenden regels: klantprijzen uit Exact Online bijhouden

Elke klant zijn eigen prijs, uit Exact Online, zonder je daglimiet op te blazen. Welke lijsten je nodig hebt, waarom de eerste synchronisatie duizend aanroepen kost en hoe je daarna met bijna niets toe kunt.

Zorg dat ons bestelportaal per klant de prijs laat zien die ook op zijn
factuur komt, rechtstreeks uit de boekhouding.

Een bestelportaal waarin elke klant zijn eigen prijs ziet, is geen kwestie van een prijsveld bij het artikel. In een groothandel staan afspraken per klant, per artikel en soms per aantal, in een stelsel van prijslijsten. Die afspraken staan in de boekhouding, en daar moeten ze ook blijven staan.

Wij bouwden dat voor een drankengroothandel met slijterij. Het staat live. De klant blijft anoniem en er staan hier geen bedragen, prijzen of marges.

Het lastige is niet het ophalen. Het lastige is dat het elke dag opnieuw moet, binnen de limieten van de API, en dat een halve synchronisatie geen bruikbaar antwoord mag opleveren.

Vier lijsten, niet één

Een klantprijs zit niet in één lijst. Je hebt er vier dingen voor nodig:

De prijslijsten zelf. Welke lijsten bestaan er, hoe heten ze, in welke valuta.

De perioden per lijst. Een lijst kan een begin- en einddatum hebben. Zonder de perioden weet je niet welke versie vandaag geldt.

De prijsregels. Dit is het grote werk: per lijst per artikel een regel, met het aantal waarvoor hij geldt, de eenheid, de basisprijs, een korting en de nieuwe prijs.

De klanten met een prijslijst. In de boekhouding wijst de klantkaart naar een lijst. Je hoeft niet alle klanten op te halen, alleen die met een lijst. Dat scheelt een hoop.

De eerste twee en de laatste zijn klein genoeg om altijd in hun geheel op te halen. De prijsregels zijn dat niet.

Waarom de eerste keer duizend aanroepen kost

Bij de eerste volledige synchronisatie haalde onze koppeling 78 prijslijsten en 63.707 prijsregels op. Dat kostte 1.104 aanroepen.

Dat komt door de paginagrootte. De prijsregels komen per 60 stuks binnen. Tienduizenden regels betekent dus ruim duizend keer "geef me de volgende pagina". De artikelen zelf zijn een aparte voorraad van ongeveer vijfhonderd aanroepen, en die verversen we 's nachts.

Daarna is het beeld anders. Bij een gewone bijwerkronde vraagt de koppeling alleen de regels die sinds de laatste keer zijn gewijzigd. Op een dag waarop niemand aan de prijzen werkt, is dat één aanroep met een leeg antwoord.

Eén uitzondering, en één gat

Twee dingen die we hard in de code hebben gezet.

De uitzondering: als er nog helemaal geen prijsregels in de kopie staan, haalt de koppeling ze altijd volledig op, ook bij een bijwerkronde. Anders krijg je na een lege database een kopie met alleen de regels die sinds gisteren zijn aangepast, en dat ziet eruit als een werkende synchronisatie terwijl je niets hebt.

Het gat: filteren op "sinds wanneer gewijzigd" laat verwijderde regels staan. Wat weg is, meldt zich niet. Daarom draait er regelmatig een volledige ronde, bij ons als de laatste volledige ronde ouder is dan een week. Dan verdwijnt uit de kopie wat er in de boekhouding ook niet meer is.

Dat tweede geldt voor elke synchronisatie op basis van wijzigingsdatums, niet alleen voor prijzen. Wie alleen op wijzigingen bijwerkt, bouwt langzaam een kopie op met spookregels erin.

Binnen de limieten blijven, netjes

De API staat 60 aanroepen per minuut toe en een paar duizend per dag. Bij ruim duizend aanroepen op een rij is dat geen theorie meer.

Drie dingen die wij doen:

Tempo houden. Minstens iets meer dan een seconde tussen twee aanroepen. Dat is langzamer dan het mag en voorkomt dat je tegen de minuutgrens aanloopt.

De koppen lezen. Elk antwoord vertelt hoeveel aanroepen je nog hebt, per minuut en per dag. Dat is een harde teller en geen schatting, dus gebruik hem.

Op tijd stoppen. Komt de dagteller in de gevarenzone, dan stopt de ronde met de status "afgebroken" in plaats van met een foutmelding halverwege. Komt de minuutteller bijna op, dan wacht de koppeling even, hooguit iets meer dan een minuut.

Dat laatste klinkt als een detail en is het niet. Een synchronisatie die alle aanroepen van de dag opmaakt, legt ook alles plat wat later op die dag nog met de boekhouding moet praten: de voorraad, de orders, de facturen.

Een halve ronde mag niets slopen

Elke ronde is een eigen record, met zijn soort, zijn begin en zijn uitkomst. En er wordt per pagina weggeschreven, niet alles aan het eind in één keer.

Dat betekent dat een ronde die halverwege afbreekt, de pagina's die al binnen waren bewaart. De volgende ronde pakt verder op. Een alles-of-niets-synchronisatie van tienduizenden regels mislukt vroeg of laat, en dan heb je niets.

Nog iets dat we onderweg leerden: weigert de boekhouding een lijst met een foutmelding over een veld dat niet bestaat, dan probeert de koppeling het één keer opnieuw zonder de optionele velden, en meldt dat. Velden verschijnen en verdwijnen tussen administraties en versies. Een koppeling die daarop meteen stopt, valt uit op een veld dat je niet eens nodig had.

Veelgemaakte fouten

Denken dat een klantprijs in het artikel zit. Je hebt de lijsten, de perioden, de regels en de verwijzing op de klantkaart nodig.

Alle klanten ophalen. Filter op klanten die een prijslijst hebben. De rest hoeft niet.

Alleen op wijzigingsdatum bijwerken. Verwijderde regels blijven dan voor altijd staan. Draai periodiek een volledige ronde.

Bijwerken op een lege kopie. Haal alles op zolang er nog niets staat, anders lijkt een lege kopie gevuld.

De limieten schatten in plaats van lezen. De antwoorden vertellen je precies hoeveel aanroepen er over zijn. Stop voordat je bij nul bent, want er is meer dat vandaag met de boekhouding moet praten.

Hoe we met dezelfde aanpak de voorraad per magazijn bijhouden, staat in meerdere magazijnen in Exact Online. Wat de documentatie verder niet zegt, staat in de Exact Online-API, en wat er nog meer op te bouwen is in meer dan facturen. Wil je zoiets voor je eigen administratie, kijk dan op maatwerk.

MK
Maarten Keizer

Oprichter van Invoker. Ruim twintig jaar hosting, systeembeheer en webdevelopment; bouwt de Claude-hosting zelf en test alles eerst op de eigen servers.

over maarten