NMBRS-koppeling laten maken.

Waarom koppelen aan NMBRS?

De salarisadministratie is in de meeste organisaties het laatste eiland. Overal elders zijn de systemen inmiddels gekoppeld, maar één keer per maand gaat er nog een bestand met uren, toeslagen en mutaties over de mail naar iemand die het overtypt. En omdat het om salaris gaat, is de foutmarge daar nu net het minst acceptabel.

NMBRS leent zich goed voor automatisering, want het platform heeft een publieke API en een uitgesproken partnerstrategie: er zijn meer dan honderd partners op aangesloten. Wat de meeste organisaties niet weten, is dat er onder de motorkap iets aan het verschuiven is — en dat dit bepaalt hoe je een koppeling vandaag zou moeten bouwen.

Wat kun je koppelen?

In de praktijk komen de vragen die wij krijgen neer op een handvol datastromen. Welke daarvan voor jou spelen, hangt af van waar het handwerk zit:

• Uren richting de salarisverwerking — De klassieker. Uit een urenregistratie, planningssysteem of interne app gaan gewerkte uren, overuren en toeslagen automatisch naar de loonrun in plaats van via een spreadsheet.
• Medewerkerdata en mutaties — In- en uitdiensttredingen, contractwijzigingen, adreswijzigingen en bankgegevens. Vaak vanuit een HR-systeem of onboardingproces dat toch al de bron is.
• Verlof en verzuim — Aanvragen en saldi, meestal bidirectioneel: aanvragen gaan vanuit de app naar NMBRS, saldi komen terug zodat de medewerker ziet wat hij nog heeft staan.
• Declaraties en variabele looncomponenten — Kilometers, onkosten, bonussen en toeslagen die per periode verschillen en anders handmatig worden ingeklopt.
• Journaalposten richting het grootboek — De verwerkte salariskosten doorzetten naar de boekhouding, zodat de cijfers in het financiële pakket kloppen zonder tussenstap.

Die laatste stroom is bij accountantskantoren vrijwel altijd het startpunt, omdat hij per klant elke maand terugkomt. De uren-stroom is bij bedrijven met veel personeel op locatie meestal het grootste tijdverlies.

REST of SOAP: de deadline van 1 maart 2027

Hier zit het belangrijkste dat je nu moet weten. NMBRS heeft jarenlang een SOAP API gehad, en heel wat bestaande integraties draaien daar nog op. Die API is inmiddels gedeprecieerd: nieuwe koppelingen horen op de REST API gebouwd te worden, en de ondersteuning voor SOAP stopt per 1 maart 2027.

Dat heeft twee praktische gevolgen. Bouw je nu iets nieuws, dan is de keuze simpel: REST, en niets anders. Draai je al een koppeling, dan is het verstandig om vandaag te controleren waar die op leunt. Een SOAP-integratie die nu prima werkt, is namelijk geen probleem tot hij dat ineens wel is — en migraties waarbij salarisbetalingen in het spel zijn, wil je niet in de laatste maand doen.

Een koppeling met een einddatum is geen koppeling maar uitgestelde werkvoorraad.

De REST-documentatie is opgezet als een gewone, moderne API-referentie, dus in vergelijking met de XML-constructies van veel boekhoudpakketten valt het bouwwerk mee. De complexiteit zit hier niet in het protocol maar in het domein: loonbegrippen, periodes en verwerkingsmomenten.

Authenticatie en het partnertraject

De REST API van NMBRS gebruikt de standaard OAuth 2.0 authorization code flow. Daarbovenop komt een tweede sleutel: in het developer portal abonneer je je op een product, en de subscription key die je daarmee krijgt stuur je bij elke request mee. Met scopes leg je vast welke gegevens je integratie mag benaderen — je vraagt dus niet standaard alles aan.

Wat veel mensen verrast, is dat de weg naar productie meer is dan een technische. NMBRS werkt met een partnertraject:

1. Registreren als partner — Je meldt je aan via de NMBRS App Store en krijgt toegang tot het developer portal.
2. Testomgeving opzetten — Je bouwt tegen een demo-omgeving in plaats van tegen de administratie van een echte klant.
3. Ontwikkelsubscription — Die krijg je vrij, zodat je zonder drempel kunt bouwen en testen.
4. Demo en productiesubscription — Een productiesubscription wordt pas verstrekt na een geslaagde demo van je integratie. Je laat dus zien wat je gebouwd hebt voordat je op echte loondata mag.

Die demo-stap is geen formaliteit om te negeren, maar hij is ook geen probleem: hij zit gewoon in je planning tussen "af" en "live". Wie hem over het hoofd ziet, belooft een klant een opleverdatum die hij niet haalt.

Synchroniseren met webhooks in plaats van pollen

Bij veel boekhoud- en HR-pakketten moet je zelf periodiek gaan kijken of er iets veranderd is. NMBRS biedt daarvoor een beter alternatief: op debiteurniveau kun je webhooks instellen die een melding sturen zodra een event is afgerond. Je hoeft dan niet elk kwartier te vragen of de salarisrun al klaar is — je krijgt te horen wanneer dat zo is.

Dat past goed bij het ritme van salarisverwerking, dat nu eenmaal in schokken gaat. De rest van de maand gebeurt er weinig, en rond de verwerking gebeurt alles tegelijk. Een paar dingen om vooraf over na te denken:

• Behandel een webhook als een signaal, niet als de data — Gebruik de melding om gericht de actuele gegevens op te halen, in plaats van blind te vertrouwen op wat er in het bericht staat.
• Zorg voor idempotentie — Een melding kan dubbel binnenkomen. Zonder idempotente verwerking boek je zomaar twee keer dezelfde journaalpost.
• Houd een vangnet achter de hand — Een endpoint dat er even uit lag, mag geen periode overslaan. Een periodieke controle naast de webhooks vangt dat op.
• Reken op onderhoudsmomenten — NMBRS voert wekelijkse updates uit op woensdagavond. Een koppeling die daar niet tegen kan, valt elke week een keer om.

Salarisdata is geen gewone data

Bij een boekhoudkoppeling gaat het over facturen; hier gaat het over burgerservicenummers, salarissen, bankrekeningen en soms verzuimgegevens. Dat verandert de eisen aan de koppeling wezenlijk, en dat is geen juridische bijzaak maar een ontwerpkeuze.

• Vraag alleen de scopes die je nodig hebt — Als je koppeling uren wegschrijft, hoeft hij geen salarisgegevens te kunnen lezen.
• Sla zo min mogelijk op — Elke kopie van loondata in jouw systeem is een kopie die je moet beveiligen, bewaren en ooit verwijderen.
• Log zonder inhoud — Logregels zijn onmisbaar bij het oplossen van fouten en fataal als er persoonsgegevens in staan. Log identifiers en statussen, geen payloads.
• Leg de verwerking vast — Wie welke gegevens waarom doorgeeft, hoort in je verwerkingsregister en in de afspraken met de klant. Zie ook AVG voor webapplicaties.

Veelgemaakte fouten bij NMBRS-koppelingen

Uit de HR- en salariskoppelingen die we bouwen, komen steeds dezelfde valkuilen terug:

• Nog op SOAP bouwen — Begrijpelijk als er voorbeeldcode rondslingert, maar je bouwt dan iets met een houdbaarheidsdatum in 2027.
• De demo-stap vergeten — Technisch klaar is niet hetzelfde als in productie mogen.
• Periodes verkeerd interpreteren — Een loonperiode is geen kalendermaand, en een correctie op een afgesloten periode werkt anders dan een gewone mutatie. Dit is waar de meeste inhoudelijke bugs zitten.
• Verwerkte runs willen wijzigen — Zodra een salarisrun verwerkt is, corrigeer je hem niet meer door de oorspronkelijke gegevens aan te passen. Je koppeling moet dat onderscheid kennen.
• Geen terugkoppeling naar de gebruiker — Als er iets misgaat met de uren van een medewerker, moet iemand dat zien vóór de betaling, niet erna. Een stille foutafhandeling is bij salaris geen optie.
• Alles tegelijk willen — Uren, verlof, mutaties en journaalposten in één keer opleveren duurt lang en levert pas aan het eind waarde op.

Mijn kijk op NMBRS-koppelingen

Salariskoppelingen zijn technisch niet de moeilijkste die we bouwen, maar wel de koppelingen waar ik het meest aandacht besteed aan wat er misgaat. Bij een boekhoudkoppeling die een dag stilstaat, haal je de achterstand de volgende dag in. Bij een salarisrun die verkeerd gevuld is, staat er geld op de verkeerde rekening en zit er een medewerker met een probleem. Die asymmetrie hoort terug te komen in het ontwerp: liever een koppeling die stopt en alarm slaat dan een die dapper doorgaat met halve gegevens.

Wat ik verder vaak zie, is dat de vraag "koppel NMBRS aan ons systeem" eigenlijk een procesvraag is. Iemand heeft een routine opgebouwd rond die maandelijkse export, met controles die nergens beschreven staan maar die wel echt iets vangen. Als je die routine wegautomatiseert zonder te vragen wat er in dat halfuur precies gebeurt, automatiseer je ook de controle weg. Ik begin daarom altijd bij de persoon die het nu doet, niet bij de API-documentatie.

En dan de deadline. Draait er bij jou nog een SOAP-koppeling, dan is dit het jaar om het rustig aan te pakken — met tijd om parallel te draaien en te vergelijken. Volgend jaar is het haasten, en haasten en salarisadministratie gaan slecht samen.

— Jasper

Zo helpt Coding Agency hierbij

Wij bouwen NMBRS-koppelingen op maat: van een stroom die gewerkte uren automatisch naar de salarisverwerking brengt tot een tweerichtingskoppeling tussen je HR-applicatie en de administratie. We regelen de OAuth-afhandeling en het partnertraject, de mapping van jouw begrippen naar loonperiodes en componenten, en een synchronisatie met foutafhandeling die zichtbaar is voor de mensen die ermee werken. Migratie van een bestaande SOAP-koppeling naar REST pakken we in fases aan, zodat er geen loonrun tussen wal en schip valt. Bekijk ook hoe een AFAS-koppeling werkt, wat er bij een Twinfield-koppeling komt kijken, of hoe we dossierautomatisering op een accountantskantoor aanpakken.

Benieuwd wat een NMBRS-koppeling voor jouw situatie kan betekenen? Neem contact op voor een vrijblijvend gesprek.

Bronnen: Nmbrs API (api.nmbrs.nl) en Building a Nmbrs integration (nmbrs.com).