De complete gids voor de SD Worx API en HR-automatisering

Door uw HR-tools te verbinden via de SD Worx API, bouwt u een gecentraliseerd data-ecosysteem. Dit levert in de praktijk heel wat voordelen op die veel verder gaan dan enkel tijdsbesparing.

In België speelt de SD Worx API een sleutelrol bij het naadloos verbinden van personeelsplanningstools als Shyfter met de loonadministratie. We zien in de praktijk dat een goede integratie het aantal fouten met wel Deze geautomatiseerde aanpak is vooral een must voor bedrijven met dynamische uurroosters, zoals in de horeca of retail. Een correcte en snelle verwerking van personeelsdata is daar de sleutel tot operationele perfectie. Voor meer achtergrondinformatie kunt u onze gids lezen over hoe wij uw sociaal secretariaat helpen.

Een API spreekt via 'endpoints'. Zie het als specifieke URL's die fungeren als toegangspoorten tot de data in je HR-software. Om het maximale uit de Elk endpoint heeft zijn eigen, specifieke taak. Sommige zijn bedoeld om data op te halen (een GET-request), terwijl andere dienen om informatie toe te voegen of aan te passen (POST- of PUT-requests). Voor HR-managers zijn vooral de endpoints rond werknemers, loon en tijdregistratie van goudwaarde.

De basis van elke HR-integratie is de data van je personeel. Via de werknemer-endpoints haal je de essentiële informatie op die je nodig hebt voor een sluitende personeelsplanning en administratie.

Persoonlijke gegevens: Naam, adres, contactinformatie en geboortedatum.

Contractdetails: Start- en einddatum van het contract, type tewerkstelling (voltijds, deeltijds, flexi-job) en de functie van de medewerker.

Endpoints voor loon- en prestatiegegevens

Een correcte datastructuur is hierbij essentieel. De API levert data vaak aan in een gestructureerd JSON-formaat. Dit formaat maakt het mogelijk om specifieke velden, zoals looncodes voor overuren of nachtwerk, direct te mappen naar de overeenkomstige velden in uw planningstool.

Een samenvatting van de belangrijkste endpoints, hun functie en de typische data die ze beschikbaar stellen voor integratie.

/employees: Ophalen en beheren van werknemersgegevens.
/payroll-results: Toegang tot verwerkte loonresultaten en loonfiches.
/timesheets: Synchroniseren van gewerkte uren en prestaties.
/absences: Beheren van afwezigheden.
/contracts: Inzien en beheren van arbeidscontracten.
Deze endpoints vormen samen het zenuwcentrum voor de data-uitwisseling tussen je HR- en planningssystemen, en maken een geautomatiseerde workflow mogelijk.

De endpoints voor tijdregistratie zijn het hart van je operationele efficiëntie. Ze maken real-time synchronisatie van gewerkte uren en afwezigheden mogelijk, wat onmisbaar is voor een nauwkeurige planning en loonadministratie.

cobra.sdworx.com zogenaamde OData-endpoints voor resources zoals werknemersdata. Deze bevatten ook cruciale gegevens als het rijksregisternummer en fiscale ID's, essentieel voor een loonberekening conform de Belgische cao's. Dit stelt planningstools in staat om afwezigheden te combineren met gewerkte uren voor een payroll met een compliance-rate van Een succesvolle integratie met Shyfter realiseren

SD Worx API koppelen aan een personeelsplanningstool zoals Shyfter is een project dat je best gestructureerd aanpakt. Een goede voorbereiding is het halve werk en zorgt ervoor dat de data-uitwisseling vanaf dag één vlekkeloos verloopt. Alles start met het verzamelen van de juiste gegevens en documentatie.

Configuratie binnen Shyfter

ontvangen SD Worx API-gegevens in.

De onderstaande afbeelding geeft een helder beeld van de datastroom via de belangrijkste SD Worx API-endpoints.

Deze visualisatie laat zien hoe data over werknemers, lonen en prestaties naadloos van het ene naar het andere systeem stroomt. Dit vormt de basis van een geautomatiseerde HR-workflow.

Een absoluut cruciale stap is

Door de integratie eerst met testdata te valideren, spoor je eventuele problemen op in een veilige omgeving. Dit garandeert een soepele overgang, zonder dat je de live operaties en de loonverwerking van je echte medewerkers verstoort. Het verzekert een stabiele en betrouwbare dataflow vanaf dag één.

Requests en responses: concrete voorbeelden uit de praktijk

SD Worx API nu écht? Laten we het concreet maken. Elke interactie met een API bestaat uit een vraag (een response). Door naar echte voorbeelden te kijken, demystificeren we wat er achter de schermen gebeurt – handig voor zowel ontwikkelaars als HR-managers die de data-uitwisseling beter willen begrijpen.

Een van de meest voorkomende taken is het opvragen van de gegevens van een specifieke medewerker. Hiervoor stuur je een simpele employees endpoint, met het unieke ID van de werknemer erbij.

12345 opvragen. De request die jouw software naar de SD Worx API stuurt, ziet er dan zo uit:

Je vraagt de server letterlijk: "Geef mij alle informatie die je hebt over werknemer De response: Gestructureerde data in JSON

JSON-formaat (JavaScript Object Notation), een lichtgewicht en universele standaard die voor zowel machines als mensen makkelijk te lezen is.

{
"employeeId": "12345",
"firstName": "Jan",
"lastName": "Peeters",
"nationalNumber": "85.01.15-123.45",
"contract": {
"contractType": "Vast",
"startDate": "2023-01-01",
"jobTitle": "Teamleider"
}
}


"firstName") met een bijbehorende waarde (). Deze heldere structuur maakt het voor een tool als Shyfter kinderspel om de juiste velden te herkennen, te importeren en te gebruiken voor een vlekkeloze personeelsplanning.

Een ander praktisch voorbeeld is het ophalen van afwezigheden, wat essentieel is voor een accurate planning en loonverwerking. Zeker in sectoren als de event- en cateringbranche in België, waar naar schatting 95% in de loonverwerking helpen garanderen, simpelweg door afwezigheden correct door te geven aan planningstools.

Om de afwezigheden van een werknemer op te vragen, stuur je een gelijkaardige request, maar dan naar het GET /v1/employees/12345/absences?dateFrom=2024-01-01
Host: api.sdworx.com
Authorization: Bearer [JOUW_AUTHENTICATIETOKEN]


Deze voorbeelden tonen hoe krachtig en tegelijkertijd eenvoudig data-uitwisseling kan zijn. Het is precies deze gestructureerde communicatie die de basis vormt voor een efficiënte en geautomatiseerde HR-workflow.

Zelfs met de meest zorgvuldige voorbereiding kan er tijdens een API-integratie wel eens iets mislopen. De dataflow hapert, en plots verschijnt er een foutmelding. Geen paniek. Weten hoe je die fouten snel herkent en aanpakt, is cruciaal om je koppeling met de De meeste API’s, en dus ook die van SD Worx, communiceren via standaard HTTP-statuscodes. Dit zijn genummerde antwoorden die de server terugstuurt. Ze vertellen je in een notendop of je verzoek succesvol was of waar het precies is fout gelopen. Deze codes begrijpen is de eerste stap naar een snelle oplossing.

Wanneer er iets fout gaat, is de statuscode je eerste en belangrijkste aanwijzing. In de context van de SD Worx API zul je vaak de volgende codes tegenkomen:

Het correct interpreteren van deze codes bespaart je een hoop zoekwerk en frustratie. Om het nog makkelijker te maken, hebben we de meest voorkomende fouten en hun oplossingen hieronder voor je samengevat.

Foutcode 401 Unauthorized:

• Betekenis: Het opgevraagde endpoint bestaat niet.
• Oplossing: Verifieer de URL van je request. Let op typefouten en check of je de meest recente endpoint-documentatie gebruikt.

Foutcode 500 Internal Server Error:

• Betekenis: Je hebt de limiet van het aantal toegestane aanvragen overschreden.
• Oplossing: Spreid je API-calls over een langere periode. Implementeer een 'exponential backoff'-strategie om je requests te vertragen na een fout.

Praktische checklist voor troubleshooting

Controleer de API-sleutels: Zijn de gebruikte credentials, zoals het authenticatietoken, nog geldig? Worden ze correct meegestuurd bij elke request? Soms is een verlopen token de simpele oorzaak.

Verifieer de endpoint URL's: Een kleine typefout in de URL kan al resulteren in een Een vaak vergeten aspect is 'rate limiting'. API's beperken het aantal aanvragen dat je binnen een bepaalde tijd mag doen om overbelasting te voorkomen. Als je te veel requests te snel na elkaar stuurt, krijg je een Door deze stappen te volgen, tackel je de meeste problemen met de Compliance en voordelen voor de Belgische markt

Wie in België onderneemt, weet dat de sociale wetgeving complex is. De Door een directe lijn te leggen tussen een tool voor tijdregistratie, zoals Shyfter, en je payroll in SD Worx, worden gegevens automatisch en zonder fouten doorgestuurd. Dat is cruciaal om te voldoen aan de strenge regels die de Belgische arbeidsmarkt typeren.

De Belgische regelgeving eist een haarfijne administratie van prestaties en tewerkstelling. Met de SD Worx API voldoe je aan die eisen met een minimum aan manueel werk. De automatisering zorgt voor een stipte en correcte afhandeling van taken die je anders uren zouden kosten.

Dimona-aangiftes: De API stuurt de data voor de onmiddellijke aangifte van tewerkstelling rechtstreeks door. Essentieel bij de aanwerving en het vertrek van personeel.

RSZ-rapportages: Geregistreerde prestaties worden omgezet in sluitende data voor de kwartaalaangiftes aan de Rijksdienst voor Sociale Zekerheid.

Correcte loonberekening: Toeslagen voor nacht- of weekendwerk, overuren en specifieke sectorpremies worden feilloos berekend op basis van de geregistreerde uren.

Dimona-aangifte.

Data-integriteit en een sluitende audittrail

data-integriteit. Omdat gegevens rechtstreeks van het ene naar het andere systeem vloeien, zonder manuele tussenstappen, blijft alle informatie consistent en betrouwbaar.

audittrail op die van onschatbare waarde is bij een sociale inspectie of interne controle. Je kunt op elk moment aantonen waar de data vandaan komt en hoe die verwerkt is.

Veelgestelde vragen over de SD Worx API

SD Worx API, met heldere en directe antwoorden.

Ja, doorgaans is het gebruik van de SD Worx API een betalende dienst. De precieze kosten hangen af van uw contract en het type data dat u wilt gaan gebruiken.

Heb ik een ontwikkelaar nodig om de koppeling te maken?

Wilt u echter een maatwerkkoppeling bouwen met een ander, niet-standaard systeem? Dan is technische kennis of de hulp van een ontwikkelaar wel een must. Zij kunnen dan de specifieke response-logica op maat van uw systemen implementeren.

De SD Worx API ontsluit een schat aan HR-data, wat de basis is voor een vlotte automatisering. Welke gegevens u precies kunt synchroniseren, hangt af van de specifieke API-endpoints die voor u geactiveerd worden.

Personeelsgegevens: De basisinfo zoals naam, adres, rijksregisternummer en contractdetails.

Prestaties en uren: Alle gewerkte uren, overuren en specifieke toeslagen die u in uw planningstool registreert.

Looncomponenten: Alle elementen die nodig zijn voor een correcte en tijdige loonberekening.

Diverse afwezigheden: Verschillende types afwezigheid, van ziekte en wettelijk verlof tot klein verlet.


Klaar om uw HR-beheer te transformeren?

Shyfter is veel meer dan een eenvoudige planningstool. Het is een complete personeelsbeheer software en HR-management oplossing, ontworpen om uw workforce management te vereenvoudigen en u kostbare tijd te besparen.
Vraag een demo aan