Overslaan naar inhoud
Nederlands
Meer over Cash
  • Er zijn geen suggesties want het zoekveld is leeg.

API: Introductie (voor ontwikkelaars)

Met API kun je integraties bouwen met het salarisplatform. We bieden twee API's aan: de REST-API en de SOAP-API. Die laatste zal begin 2027 worden uitgefaseerd. De REST-API is de huidige standaard. Deze maakt gebruik van OAuth 2.0 voor authenticatie. Alle nieuwe functionaliteiten worden uitsluitend op REST gebouwd. Als je start met een nieuwe integratie, gebruik dan de REST-API.

Introductie

Wat kan ik doen met de API?

  • Werknemersgegevens ophalen / wijzigen: Inclusief persoonlijke en salarisinformatie. Bijvoorbeeld voor het registreren van uren of verzuim.

  • Bedrijfs- en debiteurengegevens ophalen / wijzigen: Voor onder andere boekhouding, planningen, roosters en dashboards.

  • Rapporten opvragen: Zoals journaalposten en looncomponenten.

Zie de onderstaande methoden voor meer informatie over wat je uit Cash Payroll kunt halen en over de verschillende implementatiescenario's, zoals de Single Sign-On Service, Debtor Service, Company Service en Employee Service.

 

Webservices

Gebruikslimieten (Usage limits)

Het verbruik van de API is gebaseerd op een fair use policy. Dit betekent dat er momenteel geen specifieke beperkingen van kracht zijn. Misbruik van de API kan echter wel leiden tot een blokkering van de toegang.

  • Snelheid: Je kunt 150 aanroepen (calls) per seconde doen. Als dit aantal wordt overschreden, treedt er een vertraging op van een halve seconde. Houd er rekening mee dat andere gebruikers op hetzelfde moment ook een aanroep kunnen doen.

  • Verwerkingstijd: Afhankelijk van de hoeveelheid opgehaalde en overgedragen data kan de responstijd van een aanroep oplopen. Dit kan bijvoorbeeld gebeuren wanneer er gegevens worden opgehaald voor een groot aantal werknemers of bij de run-output van grote bedrijven.

  • Batchverwerking: Voor grotere hoeveelheden data zijn er specifieke acties beschikbaar. Dit is bijvoorbeeld handig wanneer er gegevens voor veel werknemers tegelijk moeten worden ingevoerd.

 

Batch-methoden (Batch methods)

Updates en wijzigingen aan de API

De API is constant in ontwikkeling. Alle aanpassingen worden gepubliceerd in onze update-notities (update notes). Mocht een wijziging impact hebben op de huidige beschrijving van de webservices, dan stellen we een staging-omgeving (testomgeving) beschikbaar zodat ontwikkelaars hun code kunnen aanpassen. Deze overgangsfase is altijd minimaal één week beschikbaar.

 

API update-notities (API update notes)

Testen / Sandbox

Naast een demo-omgeving die aan jou ter beschikking kan worden gesteld, bevat elke omgeving een "sandbox-omgeving". In de Cash Payroll-applicatie hebben we een speciale functie genaamd "Sandbox". De Sandbox is een volledig afgescheiden Cash Payroll-omgeving die is gevuld met alle gegevens van de voorgaande dag. We hebben deze functie ontwikkeld zodat je functionaliteiten binnen de Cash Payrol-applicatie kunt testen zonder dat dit invloed heeft op je echte live-data.

Beveiliging (Security)

De API-service is uitsluitend beschikbaar via HTTPS - Secure Socket Layer (SSL), ongeacht hoe je account is geconfigureerd. Dit betekent dat de data-overdracht altijd versleuteld is. Je moet een geverifieerde gebruiker zijn om API-verzoeken te kunnen doen.

Wat betreft de reikwijdte van de databeveiliging: de gebruiker die verbinding maakt met de API en gegevens uit Nmbrs ophaalt, is zelf verantwoordelijk voor het gebruik van deze gegevens buiten de Nmbrs-applicatie.

Wie kan een API-token aanmaken?

Alleen gebruikers op het hoogste niveau (top level users) van accountant- en business-omgevingen kunnen hun eigen API-token genereren. Voor alle andere typen gebruikers kan een API-token worden aangemaakt door gebruikers die toegang hebben tot de inloginstellingen.

Waar hebben gebruikers met een API-token toegang toe?

Gebruikers met een API-token kunnen gebruikmaken van alle services en methoden van onze API, en hebben via de API toegang tot alle informatie. Zij hebben echter uitsluitend toegang tot de gegevens van de entiteiten (debiteuren/bedrijven) waarvoor zij geautoriseerd zijn. Deze toegang kan worden ingesteld via de filtering op de gebruikersaccounts. Op het hoogste niveau gebeurt dit via de debiteurentags (zie ook: Debiteur tags aanmaken). Op debiteurenniveau gebeurt dit via de filtering van bedrijven (zie voor meer informatie: Klanten toegang geven).

Ondersteuning op de API (Support)

Wij ontwikkelen en onderhouden de Cash Payroll API voor elke gebruiker die er gebruik van wil maken. We zullen altijd zo goed mogelijk ondersteunen bij het opzetten van een integratie, maar we kunnen dit niet voor je uitvoeren.

Wanneer je de API gebruikt en deze integratie ook interessant is voor andere klanten van Cash Payroll, kun je een integratiepartner worden. Voor bedrijven die integratiepartner willen worden, neem dan contact op met de helpdesk via mail helpdesk.lonen@cash.nl.

Hoe te verbinden (How to connect)

Authenticatie en autorisatie (Authentication and Authorization)

De API-service is uitsluitend beschikbaar via HTTPS - Secure Socket Layer (SSL), ongeacht hoe je account is geconfigureerd. Dit betekent dat de data-overdracht altijd versleuteld is. Je moet een geverifieerde gebruiker zijn om API-verzoeken te kunnen doen.

Om onze API te gebruiken, heb je een e-mailadres en een API-token nodig. Om een API-token te verkrijgen, moet je een gebruikersaccount hebben binnen een Cash Payroll-omgeving. Dit betekent dat dezelfde filters die in de gebruikersinterface (UI) gelden, ook van toepassing zijn op de API. Je kunt de verbinding tot stand brengen met het e-mailadres en de token van een bestaand gebruikersaccount, of er kan specifiek een account voor je worden aangemaakt.

Het niveau waarop het gebruikersaccount wordt aangemaakt, bepaalt de toegang tot de API-service. De onderstaande vragen helpen je te bepalen welk type gebruikersaccount je nodig hebt voor de integratie:

  • Wil je integreren met één of met meerdere Cash Payroll-omgevingen?

  • Wil je integreren met alle debiteuren binnen een Cash Payroll-omgeving?

  • Wil je integreren met alle bedrijven van een specifieke debiteur binnen een Cash Payroll-omgeving?

API-aanroepen (API calls)

Methoden (Methods)

Bepaal wat het doel is van je integratie. Wil je alleen informatie ophalen uit Cash Payroll, of wil je ook gegevens invoeren? Moet Cash Payroll het leidende systeem worden? En hoe zorg je ervoor dat de systemen synchroon blijven?

Voordat je begint met het bouwen van de integratie, is het verstandig om een functionele flow (procesontwerp) te maken. Dit helpt je te begrijpen welke informatie je precies nodig hebt uit ons systeem. Als je weet wat je wilt bereiken, kun je direct controleren of alles wat je voor ogen hebt ook daadwerkelijk mogelijk is met de API.

Hieronder vind je de basisdefinities van de methoden voor al onze webservices:

Here are the basic definitions to our methods for all webservices:

  • _Get - use to get data
  • _Insert - use to insert new data
  • _Update - use to change existing data
  • _Delete / _clear - use to delete data

Common fields in the methods:

  • <Datetime>
    Can be used as YYYY-MM-DD. Time can be added but will be ignored
  • <Unprotected mode>
    If the period is before the company's current period, unprotected mode flag is required, else a TWK exception is thrown. Fore more information about periods see company period
    Use 0 or false if no TWK is required. Use 1 or true if TWK is required.

 The Cash Payroll API has the following Batch methods:

  • HourComponentFixed_Insert_Batch 
  • HourComponentVar_Insert_Batch 
  • WageComponentFixed_Insert_Batch 
  • WageComponentFixed_Insert_Batch_With_End 
  • WageComponentVar_Insehttps://api.nmbrs.nl/rt_Batch 

 

Webservices

Onze webservices  zijn onderverdeeld in vier verschillende categorieën. Elke categorie bevat een overzicht van de beschikbare methoden en een link naar een voorbeeld van een SOAP-aanroep. De onderliggende artikelen verduidelijken daarnaast de specifieke naam van de locatie of het dashlet binnen Cash Payroll. Klik op het desbetreffende artikel voor meer informatie. 

.

Nummers en ID's (Numbers and ID's)

Houd er rekening mee dat werknemers-, bedrijfs- en debiteurennummers NIET hetzelfde zijn als ID's, klik hier.

 

Aanvullende informatie Report Service

De output van de Report Service heeft een XML-structuur, wordt twee uur gecached en is identiek aan de output in de gebruikersinterface. Er zijn geen debiteur- of bedrijfsfilters van toepassing op de rapportagemethoden (report methods), wat betekent dat deze rapporten handmatig moeten worden gefilterd.

 

API-implementatiescenario's (API Implementation scenario's)

Ongeacht het type integratie dat je bouwt, moet je een aantal keuzes maken voordat je met Cash Payroll integreert. Cash Payroll is een salarisverwerkingssysteem met een eigen specifieke structuur en achterliggende logica. Zorg ervoor dat je de verschillende niveaus goed begrijpt, en houd er rekening mee dat de meeste bedrijfs- en werknemersgegevens in Cash Payroll periodegebonden zijn.

  • Cash Payroll uitgelegd voor API-integraties (Cash Payroll explained for API integrations), klik hier.

Implementatiescenario's (Implementation Scenarios)

Hoe gebruik je de API in de meest voorkomende implementatiescenario's:

  • Werknemer aanmaken: Om een werknemer aan te maken die kan worden meegenomen in de salarisverwerking, is basisinformatie vereist.

  • Inloggen automatiseren: Met de SSO Service kun je een applicatie bouwen waarmee automatisch wordt ingelogd op Cash Payroll.

  • Single Sign-On Service

Voor meer informatie over de verschillende implementatiescenario's:

  • API-implementatiescenario's

Controleren op mutaties (How to check for mutations)

Bij integratiescenario's is het een veelvoorkomende behoefte om te controleren op specifieke gebeurtenissen (events). Denk hierbij aan momenten waarop gegevens in Cash Payroll zijn gewijzigd, zoals wanneer een run is afgerond, werknemersgegevens zijn bijgewerkt of contracten zijn beëindigd.

 

References and enumerations

Cash Payroll API V3 (Latest) - Reference, klik op een van de onderstaande titels voor meer informatie.

XML References

klik hier.
 

API enumerations

 klik hier.

Sjabloon API-gebruiker (API User Template)

Er zijn API-sjablonen beschikbaar om de rechten voor specifieke API-aanroepen te beperken. Deze sjablonen kunnen door de beheerder (administrator) worden aangepast via het dashlet ‘Sjabloon gebruikers’. Met deze sjablonen krijgt een API-gebruiker uitsluitend toegang tot de specifieke aanroepen die de klant toestaat. De beheerder is er zelf verantwoordelijk voor om de rechten voor deze API-aanroepen te beperken. Zie hiervoor: Sjabloon API-gebruiker, klik hier.