Nmbrs stopt met de SOAP-API op 1 maart 2027: zo weet je of jouw salariskoppeling erop draait

Op 1 maart 2027 zet Nmbrs zijn SOAP-API definitief uit. De meeste ondernemers die dat raakt weten dat nog niet, want de koppeling eronder heeft nooit een naam gehad. Er is ooit een token gedeeld met een planningspakket, en sindsdien lopen de uren vanzelf de loonrun in. Valt die koppeling om, dan merk je het pas bij de eerste loonrun daarna: lege urenregels, en een salarisadministratie die je met de hand moet vullen.

Dit stuk gaat niet over XML versus JSON. Het gaat over de vier vragen die eronder liggen. Draait mijn koppeling hierop? Wie moet het werk doen? Wat kost het mij? En wanneer moet ik beginnen zodat de loonrun nooit stilvalt.

Wat er stopt, en wat Nmbrs bij jou neerlegt

De uitfasering van de Nmbrs SOAP-API is het stopzetten van de oudste van de twee koppelvormen die Nmbrs aanbiedt. Een SOAP-koppeling werkt met een e-mailadres plus een API-token dat je aan een externe partij geeft. Een REST-koppeling werkt met OAuth 2.0, waarbij jij als gebruiker eenmalig in Nmbrs zelf toestemming geeft. Vanaf 1 maart 2027 werkt alleen de REST-variant nog, en stopt elke koppeling die nog op SOAP draait.

Dat is geen aankondiging waar later nog aan geschoven wordt. Nmbrs heeft dit precies zo eerder gedaan: bij het uitzetten van API v2.1 werkten koppelingen op de oude versie niet meer vanaf de wekelijkse update van 15 februari 2023. Geen coulanceperiode, geen uitzondering voor wie het gemist had. De aankondiging voor SOAP staat sinds 30 juni 2026 in de kennisbank en zegt in één zin dat de SOAP-API op 1 maart 2027 definitief wordt stopgezet.

Nmbrs splitst zijn klanten daarbij in twee situaties, en die splitsing is bruikbaar. Situatie 1: er is ooit een token gedeeld met een externe partij, bijvoorbeeld een HR-tool of een planningsapplicatie. Dan moet die aanbieder overstappen. Situatie 2: je hebt zelf of samen met een tussenpartij een koppeling gebouwd. Dan ben jij de opdrachtgever van het migratiewerk.

Daar houdt de leverancier op. Wie de rekening betaalt, wat er gebeurt als je aanbieder te laat is, en welke stap jij zélf moet zetten: dat staat er niet. Precies dat is de rest van deze gids.

Wat je nodig hebt voordat je één mail verstuurt

De inventarisatie strandt bijna altijd op toegang, niet op techniek. Je hebt een login op het juiste niveau nodig om te kúnnen zien welke koppelingen er lopen, en je hebt de contracten nodig om te kunnen vragen wie betaalt. Regel die twee eerst, dan is de rest een middag werk.

Concreet heb je dit klaarliggen:

• Een Nmbrs-login op het hoogste niveau. Alleen gebruikers met een template gebaseerd op Master Accountant (accountantomgeving) of Master Client (businessomgeving) kunnen API-tokens zien en aanmaken. Zit je zelf op een lager niveau, dan zie je de helft niet.
• Een lijst van elk systeem dat medewerker-, uren- of verzuimdata met Nmbrs uitwisselt. Niet je toolstack: je datastromen. Eén pakket kan drie stromen hebben.
• De opdrachtbevestiging of het contract per koppelpartner, want daar staat of onderhoud is inbegrepen.
• Je loonrunkalender voor 2026 en 2027, inclusief de jaarovergang en de momenten waarop je sowieso niets wilt veranderen.
• De naam van wie de maatwerkkoppeling ooit bouwde. Bestaat dat bureau nog, en heb je de broncode.
• Een Nmbrs-testomgeving. Elke omgeving heeft een sandbox met de data van de vorige dag, waarin je kunt testen zonder je echte administratie te raken.

De stappen: van inventarisatie tot een koppeling die REST spreekt

Je gaat een SOAP-koppeling migreren naar de Nmbrs REST-API: eerst vaststellen welke datastromen er lopen en op wiens token, dan per stroom bepalen wie het ombouwt, daarna een OAuth-applicatie met de juiste scopes laten registreren, en tot slot parallel draaien tot één volledige loonrun aan beide kanten identiek is. Negen stappen, van inventarisatie tot het intrekken van het oude token:

1. Tel datastromen, niet tools. Schrijf per systeem op wat er precies heen en weer gaat en in welke richting. Uren naar Nmbrs, mutaties uit Nmbrs, verzuimmeldingen beide kanten op. Een planningspakket dat "gekoppeld is" blijkt in de praktijk vaak drie stromen te hebben, waarvan er twee stilletjes zijn uitgezet. Je migreert straks per stroom, niet per leverancier.

2. Kijk in Nmbrs wie er een token heeft. Ga naar het icoontje rechtsboven, dan Gebruiker Profiel, dan de tab API Token. Daar zie je of er een API-account geactiveerd is en op welk e-mailadres. Voor koppelingen op debiteurniveau staat hetzelfde onder de instellingen van de klantlogin. Bestaande REST-koppelingen vind je ergens anders: in het gebruikersprofiel van degene die de koppeling ooit legde, onder de tab Manage apps. Staat een pakket daar al, dan is die stroom al over.

3. Situatie 1: stel de drie vragen van Nmbrs, en de drie die Nmbrs niet stelt. Nmbrs geeft je drie vragen mee voor je aanbieder: zijn jullie op de hoogte van de uitfasering op 1 maart 2027, wat is jullie planning om over te stappen, en komt er een verstoring van mijn koppeling tijdens of na de overstap. Goede vragen, alleen leveren ze een antwoord op waar je niets aan hebt als het misgaat. Stel daarom deze drie er achteraan:

• Wie draagt de kosten van de migratie, en zit dat in mijn huidige abonnement of onderhoudscontract?
• Op welke datum staat mijn omgeving concreet ingepland, en wat moet ik zelf op die dag doen?
• Wat gebeurt er contractueel als jullie op 1 maart 2027 niet klaar zijn: krijg ik een terugvaloptie, of draai ik dan zelf de uren met de hand in?

4. Leg het antwoord vast met een datum en een gevolg. Een mail met "wij zijn ermee bezig" is geen planning. Vraag om een maand, zet die in je eigen agenda met drie maanden marge ervoor, en bevestig het antwoord schriftelijk terug. Doe dit ook als je aanbieder geruststellend klinkt, want de aanbieder die te laat is, is bijna nooit de aanbieder die dat vooraf toegeeft.

5. Situatie 2: maak de veldenvergelijking voordat iemand code aanraakt. Dit is de stap die het meeste geld bespaart. Zet naast elke SOAP-aanroep die je nu doet het REST-equivalent en het bijbehorende scope, en markeer wat er niet één op één in past. Nmbrs deelt de REST-toegang op in scopes zoals employee.employment voor contracten, salaris en rooster en employee.info voor persoonsgegevens, bankrekening en adres, met een read-only variant per scope en een verplichte offline_access als je een refresh token wilt. Drie dingen komen daar bijna altijd uit:

• Authenticatie is fundamenteel anders. SOAP: één token, dat alles kan wat de gebruiker kan. REST: een geregistreerde applicatie met een client id en secret, en een token dat alleen de goedgekeurde scopes dekt.
• Het niveau verschuift. De REST-API is niet beschikbaar voor accountantlogins; je hebt een klantlogin of bedrijfslogin nodig. Draaide je koppeling op accountantniveau over al je klanten heen, dan wordt dat een autorisatie per debiteur.
• Volume werkt anders. Op SOAP gold een fair use policy met 150 aanroepen per seconde, waarna een vertraging van een halve seconde volgt. Op REST hangt de limiet af van je abonnement en lever je gepagineerd terug in plaats van in één grote lijst. Een nachtelijke export van alle medewerkers wordt daarmee een lus, geen aanroep.

6. Regel de ontwikkelaarskant, en reken op wachttijd. Je bouwer moet zich registreren op het developer portal van Nmbrs, een subscription nemen en de applicatie aanmelden om een client id en secret te krijgen. Er is een mockserver om alvast tegenaan te ontwikkelen. De adder zit in de laatste stap: een ontwikkelabonnement is gratis, maar toegang tot productie krijg je pas na een demo waarin je laat zien dat de koppeling werkt. Dat is geen formaliteit van een middag, en het is de reden dat je niet in februari 2027 kunt beginnen.

7. Zet de consentflow in jouw eigen agenda. Dit is de stap die geen enkel bureaustuk noemt, en de enige die niemand voor je kan doen. Bij REST deel je geen token meer: je klikt in het andere pakket op koppelen, logt in bij Nmbrs, kiest het juiste domein en ziet dan een scherm met precies welke gegevens de applicatie opvraagt. Pas als je minimaal één profiel selecteert, wordt de knop groen. Die eenmalige toestemming werkt zoals inloggen met Google en kan alleen met de juiste login: een Master Client login of een bedrijfslogin, waaronder de templates HR Manager (System) en General Manager Payroll en HR. Heb je meerdere debiteuren in hetzelfde Nmbrs-domein, dan kun je ze sinds maart 2024 in één keer meenemen, mits bij elke debiteur hetzelfde e-mailadres actief is en er minstens één keer met dat profiel in de interface is ingelogd. Loopt de consentpagina op een 403, dan is het meestal een cookie-kwestie en werkt een incognitovenster wel.

8. Draai parallel tot en met één volledige loonrun. Zet de nieuwe koppeling aan naast de oude, laat beide schrijven naar een periode die je nog kunt corrigeren, en vergelijk de output regel voor regel: aantallen uren per medewerker, urencodes, verlofsaldi, de journaalpost. Pas als één complete loonrun aan beide kanten identiek is, is de migratie geslaagd. Niet als de eerste aanroep een 200 teruggaf.

9. Zet de oude koppeling uit en trek het token in. Deactiveer het API-token in Nmbrs zodra de nieuwe koppeling een loonrun heeft overleefd. Een token dat blijft leven is een sleutel tot je volledige personeelsadministratie bij een partij die hem niet meer nodig heeft.

De valkuilen die deze migratie eigen zijn

De koppellogin staat op het mailadres van een medewerker. Vertrekt diegene en wordt de login verwijderd of gedeactiveerd, dan valt de koppeling om. Nmbrs adviseert daarom zelf om voor een koppeling altijd een generiek e-mailadres en een herkenbare naam te gebruiken, zoals "Koppeling planning". Regel dat meteen bij de migratie: je maakt de login toch al opnieuw.

Je accountant koppelt op accountantniveau, en dat kan straks niet meer. Dit is de grootste stille verbouwing. Sommige leveranciers kozen SOAP juist hierom: FinWizer schrijft dat het bewust de SOAP-API gebruikt zodat nieuwe klanten automatisch worden opgehaald zonder dat de verbinding opnieuw geautoriseerd hoeft te worden. Onder REST vervalt dat gemak en komt er een autorisatie per debiteur voor in de plaats. Werk je met een accountantskantoor, vraag dan expliciet hoe zij dit oplossen en voor welke van jouw entiteiten jij straks moet klikken.

Niemand heeft de login die de consentflow kan afronden. De koppeling is technisch klaar, en dan blijkt de enige met een Master Client login met vakantie te zijn, of het account met de juiste template is nooit aangemaakt. Controleer in stap 2 wie die login heeft, niet in de week van de livegang.

De oude koppeling gaat uit vóór de jaarovergang. Januari is de maand waarin de meeste uitzonderingen bovenkomen: nieuwe tabellen, gewijzigde percentages, correcties over het oude jaar. Ga je in december over en zet je SOAP meteen uit, dan mis je precies de run waarin je de vergelijking het hardst nodig hebt.

Niemand merkt dat de nieuwe koppeling stilstaat. Een koppeling die stopt geeft geen foutmelding maar een leegte, en daarom is een hartslag per geslaagde run met een coulanceperiode van het normale interval de eerste voorziening die je aanzet, niet de laatste. In een periode waarin je twee koppelingen naast elkaar hebt lopen is dat dubbel waar.

Alleen de bouw wordt begroot. Een offerte voor de migratie is niet de kostprijs van de koppeling. Onderzoek naar dertig applicatiesystemen vond dat bij vijf jaar productie 79 procent van de levenscycluskosten na de oplevering valt. Vraag dus ook wat het onderhoud per jaar wordt, en wie hem repareert als Nmbrs volgend jaar iets aan de REST-API verandert.

Wie doet het werk, en wie betaalt het

De eerlijke volgorde is: laat het over aan je aanbieder als dat kan, en pak het alleen zelf op als er niemand anders is. Vier routes, met wat ze realistisch kosten.

De vaste prijzen die bureaus noemen lopen ver uiteen, en dat verschil zegt vooral iets over de scope: Coding Agency zet een Nmbrs-koppeling met monitoring en retry-logica weg vanaf 1.000 euro per koppeling (augustus 2026), terwijl het bedrag van CleverTech het overnemen en ombouwen van bestaand maatwerk dekt. Vraag dus altijd wat er in de prijs zit voordat je twee offertes naast elkaar legt.

Twee dingen bepalen de keuze meer dan de prijs. Ten eerste: hoeveel uitzonderingen zitten er in je huidige koppeling? Een stroom die alleen uren doorzet is kandidaat voor een standaardpakket. Een stroom die urencodes vertaalt, verlofsaldi splitst en een eigen kostenplaats meestuurt, is dat niet. Ten tweede: wie beheert hem over drie jaar? Een migratie is het natuurlijke moment om een koppeling die niemand meer begrijpt te vervangen door één die iemand ondersteunt.

Dit patroon is trouwens niet Nmbrs-specifiek. Bij AFAS speelt dezelfde beweging: wie nog op classic tokens draait moet voor 31 augustus 2027 over op een App connector op basis van OAuth. Leveranciers halen gedeelde tokens weg en zetten er toestemming per applicatie voor in de plaats. Dat is per saldo winst, maar het werk ligt bij de koper.

Terugrekenen van 1 maart 2027 naar jouw eigen datum

De fout die je hier kunt maken is 1 maart 2027 als je deadline nemen. Dat is de datum waarop het kapotgaat, niet de datum waarop het klaar moet zijn. Reken terug, en zorg dat er minstens één jaarovergang in je parallelfase past. Dat betekent in de praktijk: live vóór december 2026.

Die kalender ziet er ruim uit tot je hem afzet tegen de doorlooptijd van één toeleverancier die pas in het najaar begint. Ben je afhankelijk van een pakket dat nog geen datum heeft gegeven, dan is de enige zinvolle actie deze maand: schriftelijk om die datum vragen.

Hoe dat er in de praktijk uitziet

Neem een installatiebedrijf met 42 medewerkers. Nmbrs voor de salarisadministratie, een planningspakket voor roosters en urenregistratie, en een eigen exportscript dat elke nacht loonkosten per project naar een Power BI-rapportage trekt. Drie stromen, twee situaties.

De inventarisatie levert op dat er twee actieve API-tokens zijn: één op het generieke adres van het planningspakket, en één op het mailadres van een oud-controller die twee jaar geleden is vertrokken. Dat tweede token voedt het exportscript, gebouwd door een freelancer die niet meer reageert.

Voor het planningspakket, situatie 1, gaan de zes vragen de deur uit. Het antwoord komt binnen twee weken: migratie in het vierde kwartaal van 2026, inbegrepen in het abonnement, en de klant moet zelf eenmalig de consentflow doorlopen. De kantoormanager blijkt geen Master Client login te hebben, dus die wordt aangemaakt en getest, ruim voor de migratiedatum.

Voor het exportscript, situatie 2, is er niemand om het aan over te dragen. Reconstrueren wat het script ophaalt kost anderhalve dag; de ombouw naar REST met de scopes employee.employment.read en company.info.read nog eens vier. Met zes bouwdagen à 900 euro landt de ombouw rond de 5.400 euro, in de orde die een vast tarief per koppeling ook oplevert. De vraag die daarna komt is de betere: is een nachtelijke Power BI-export deze investering waard, of levert een rapport uit het planningspakket hetzelfde inzicht? Vaker wel dan niet blijkt zo'n export ooit gebouwd voor een vraag die niemand meer stelt.

De migratie is in dit voorbeeld dus niet één project maar drie beslissingen: één stroom uitbesteden aan de leverancier, één stroom ombouwen, en één stroom mogelijk gewoon opheffen.

Wat deze deadline eigenlijk aan het licht brengt

Een gedwongen migratie is een vervelende factuur en een uitstekende inventarisatie. Vrijwel iedereen die deze exercitie doet vindt minstens één token dat aan niemand meer toebehoort, en minstens één datastroom die al maanden niets nuttigs meer oplevert.

Dat is de echte opbrengst van 1 maart 2027. Niet dat SOAP REST wordt, maar dat je voor het eerst in jaren op papier hebt welke systemen bij je personeelsgegevens kunnen, met welke rechten, en op wiens naam. Wie die lijst maakt, houdt hem daarna makkelijk bij. Wie wacht tot de loonrun leegloopt, maakt hem alsnog, maar dan onder tijdsdruk en met de salarisadministratie als inzet.