Nmbrs SDK: Python-packages voor de Nmbrs SOAP- en REST-API
Twee opensource Python-packages die het werken met de API van Nmbrs terugbrengen tot een paar regels code: nmbrs voor de SOAP-API en nmbrs-rest-api voor de nieuwe REST-API. Gratis te gebruiken, met tests en releases via GitHub Actions.
Werkt met
De vraag
Waar het om ging
Wie een koppeling met Nmbrs bouwt, loopt steeds tegen dezelfde dingen aan: SOAP-envelopes en sandbox-instellingen, OAuth-tokens die elke 30 dagen roteren, paginering die je zelf moet bijhouden, antwoorden die per endpoint anders verpakt zijn en een 403 die niet vertelt welke rechten er missen. Elke partij lost dat opnieuw op, en elke oplossing heeft weer eigen fouten.
Wat we bouwden
De oplossing
nmbrs (SOAP): één Python-package voor de vijf services van de Nmbrs SOAP-API (Debtor, Company, Employee, Single Sign-On en Report), met twee manieren van inloggen, standaard in sandbox-modus zodat je niet per ongeluk op productie werkt, en eigen foutklassen zodat je code weet wat er misging.
nmbrs-rest-api (REST): alle 84 lees-endpoints van de nieuwe REST-API, gegenereerd uit de officiële OpenAPI-specificatie. De package regelt OAuth 2.0 van begin tot eind (inloggen, verversen vóór verloop, roterende refresh-tokens veilig opslaan), volgt paginering automatisch, cachet per object en per filter, en vertaalt een 403 naar de scope die je mist.
Beide packages hebben een testsuite en worden automatisch gebouwd en gepubliceerd via GitHub Actions. Omdat de SOAP-API van Nmbrs op 1 maart 2027 stopt, zijn de importnamen bewust verschillend: je kunt beide naast elkaar installeren en stap voor stap migreren.
In het kort
Voor wie
Developers en softwareleveranciers die een koppeling met Nmbrs bouwen
Rol LK Software
Ontwerp, bouw, documentatie en onderhoud
Pakketten
Nmbrs SOAP-API en Nmbrs REST-API
Status
In gebruik, beschikbaar op PyPI en GitHub
Zo werkt het
In vier stappen
01
Installeren
pip install nmbrs of pip install nmbrs-rest-api. Python 3.10 of hoger, verder geen afhankelijkheden van jouw kant.
02
Inloggen
SOAP: gebruikersnaam en token of domein. REST: één keer toestemming geven in de browser, daarna draait alles op het opgeslagen refresh-token.
03
Data lezen
api.companies(), employee.contracts(year=2026): leesbare methodes in plaats van SOAP-calls of losse HTTP-verzoeken.
04
Fouten afvangen
Elke fout is een eigen Python-exceptie, met een uitleg wat je moet doen. Tokens worden uit foutmeldingen gehaald, zodat je ze veilig kunt loggen.
Resultaat
Wat het oplevert
Een Nmbrs-koppeling begint niet meer bij nul: authenticatie, paginering en foutafhandeling zijn opgelost en getest.
Opensource onder MIT- en Apache 2.0-licentie, dus vrij te gebruiken in commerciële software.
Dezelfde kennis is beschikbaar als training: in één dag zetten we samen jouw koppeling op, zie Training.
Meer projecten
Ook interessant
Payroll Controle Tool
Een controletool die een salarisadministratie in Nmbrs op 100 punten toetst en direct laat zien wat er nog niet klopt: van contracten en NAW-gegevens tot loonheffingsinstellingen en looncodes.
Bekijk projectPensioenaangifte taxi & vervoer
Pensioenfonds Vervoer heeft geen automatische koppeling met salarispakketten, dus vervoersbedrijven met veel oproepkrachten verwerken elke maand handmatig tientallen mutaties.
Bekijk projectLoket → Nmbrs documentenconverter
Wie overstapt naar Nmbrs neemt de salarisgegevens mee, maar de documenten per werknemer niet vanzelf.
Bekijk projectWil je iets vergelijkbaars?
Beschrijf in een paar zinnen je situatie en welke pakketten je gebruikt. Binnen één werkdag krijg je een eerlijke inschatting van aanpak, doorlooptijd en kosten.