SDB Planning API Externe organisatie - Info en Stappenplan

SDB Planning API Externe organisatie - Info en Stappenplan

SDB Planning API

In het kort

Binnen SDB Planning is het mogelijk om op verschillende manieren te werken met uitzendkrachten. Verderop kun je zien welke manieren er allemaal zijn. De SDB Planning API is de ultieme stap om naadloos flex-aanvragen op te pakken met externe organisaties. Je kunt dit zien als een brug die SDB Planning en het pakket van een externe organisatie/bemiddelaar verbindt en hiermee nog meer handmatige acties automatiseert.

Verschillende vormen van werken met uitzendkrachten:



In bovenstaande afbeelding zie je de verschillende manieren waarop je als organisatie binnen SDB Planning kunt werken met uitzendkrachten. De manier die voor jouw organisatie van toepassing is bepaald tevens of er een voortraject nodig is m.b.t. het inrichten van de API. Zijn er in SDB Planning al externe organisaties als planeenheden aangemaakt en beschikken jullie over de uitzendmodule? Dan kun je het voortraject overslaan.

Voortraject inrichten API

Wanneer er voor jouw organisatie in SDB Planning nog geen externe organisaties zijn aangemaakt als planeenheden en/of jullie nog geen gebruik maken van de uitzendmodule, zal er een voortraject gestart moeten worden. Dit wordt in samenhang met jullie relatie-accountmanager opgestart. We vragen jullie daarom bij interesse in de API contact op te nemen met jullie relatie-accountmanager.

De inrichting

Hoofdtraject inrichten API

Indien gewenst zullen we een oriënterend gesprek inplannen met de externe organisatie en/of bemiddelaar en de organisatie. Onderstaande is het hoofdtraject van het inrichten van de API gevisualiseerd.

Bovenstaande afbeelding geeft het proces van de ontwikkeling van één fase weer. In eerste instantie is dit het ophalen van diensten middels de API. De volgende fases doorlopen opnieuw bovenstaand proces, hierover lees je verder meer.

Technische documentatie

De technische documentatie met betrekking tot de SDB Planning API voor bemiddelaars/externe organisaties vind je hier.

Extra technische informatie

API Foutmeldingen & oorzaken

Error
Foutmelding
Oorzaak
400
request.self_match.no_function_match
Niet de juiste functiematch tussen medewerker en dienst (indien dit wordt afgedwongen)
400
employee.get.not_found
Medewerker niet gevonden
403
employee.get.not_authorized
Niet geautoriseerd voor de medewerker die je wil koppelen
400
invalid_employee
Medewerker heft geen geldig dienstverband op de datum van de dienst
403
duty.match.connect_not_allowed
Niet toegestaan om een medewerker aan deze dienst te koppelen.
400
duty.match.already_connected
Dienst is al gekoppeld aan een medewerker
404
duty.get.not_found
Dienst niet gevonden
403
duty.get.not_authorized
Geen autorisatie voor de dienst
403
duty.get.is_retracted
Dienst is inmiddels teruggetrokken en niet meer actueel.

Booleans bij ophalen diensten

Bij de request “Retrieve duties given a specific period” is het mogelijk om enkele booleans mee te geven. Je doet dit door de boolean als header met true of false mee te geven bij de request. Hieronder leggen we de vier booleans uit, je kunt meerdere booleans tegelijkertijd meegeven.

Boolean
Actie
Staat standaard op
includeOpenDuties
Toon open diensten in de lijst
True
includePlannedDuties
Toon geplande diensten in de lijst
True
includeRetractedDuties
Toon teruggetrokken diensten in de lijst
False
includeDeletedDuties

Toon verwijderde diensten in de lijst
False

Het is voor externe organisatie met name belangrijk om te zien welke diensten nog open staan. Aan de hand van de andere statussen kun je zien dat deze dienst niet meer ingevuld kan worden. Tussen teruggetrokken (retracted) en verwijderde (deleted) duties zit met betrekking tot de API geen verschil, dit heeft enkel impact op wat er bij de organisatie met de dienst gebeurt. Deze gaat bij retracted terug naar het rooster en bij deleted wordt de aanvraag volledig verwijderd.

Request vertaaltabel

Engels

Nederlands

Collective Labor Agreement Code (CLA)

CAO, bijvoorbeeld: VVT

Employee

Medewerker

Employee Number

Medewerkernummer

Employment

Dienstverband

Duties

Diensten

Duty Codes

Dienstcodes

Activity Code

Diensturensoort

Functions

Functies

Qualifications

Kwalificaties

Propose

Voorstellen / Inschrijven

Withdraw

Terugtrekken (van inschrijving/voorstellen)

Connect

Koppelen

Flex duty

Deze diensten zijn niet van toepassing

Organizational Units

Planeenheden

Organizational Unit Requests

Aanvragen van een dienst

Requested On

Aangevraagd op

Retracted On

Teruggetrokken op

Match Candidates

Voorkeur medewerkers

Created on

Aangemaakt op

Last Updated On

Laatst gewijzigd op

Availabilities

Beschikbaarheden

Statussen van een aanvraag

Open: De aanvraag staat nog open, er is nog geen medewerker aan gekoppeld.
Pending: Een door een zorgmedewerker aangemaakte dienst moet nog goedgekeurd worden door de planner/manager.
Approved: Een door een zorgmedewerker aangemaakte dienst is goedgekeurd door de planner/manager.
Planned: Er is een medewerker gekoppeld aan deze dienst.
Realized: De dienst is gerealiseerd middels het realisatieproces in SDB Planning, dit betekend dat deze definitief is en meegenomen wordt in de (salaris)exports.
Rejected: Een door een zorgmedewerker aangemaakte dienst is afgekeurd door de planner/manager.

Meerdere OrganizationalUnitRequests

Bij het ophalen van diensten kunnen er meerdere organizationalUnitRequests worden teruggegeven. Dit gebeurd wanneer een aanvraag bijvoorbeeld meerdere keren wordt uitgezet en teruggetrokken. Je kunt hierbij uitgaan van de laatste organizationalUnitRequest als de waarheid. Houd rekening met deze mogelijke data bij het interpreteren van de API
  1. employeeNumbers
  2. includePlannedDuties: true

Fases SDB Planning API

Fase 1: Ophalen diensten middels de API
Fase 2: Inschrijven/Koppelen medewerkers middels de API
Fase 3: Reverse billing ofwel facturatie ondersteund door de API

Elk van deze fases wordt op elk van deze omgevingen en in deze volgorde getest en toegepast:

Bij het inrichten van de volgende fase start het hoofdtraject opnieuw. Elke functionaliteit wordt middels deze methode ontwikkeld, getest en gedemonstreerd. Hierdoor kun je de betreffende functionaliteit als organisatie met zekerheid in gebruik nemen op de productie-omgeving.

Inrichten API in SDB Planning

Om de externe organisatie toegang te geven tot de demo- of productieomgeving zul je als organisatie enkele zaken moeten inrichten. Dit inrichten verdelen we in twee onderdelen, het aanmaken van een API-key en het inrichten van een autorisatiegroep. Mocht je als organisatie vragen hebben met betrekking tot dit stuk inrichting, neem dan contact op met de helpdesk.
Mocht je deze inrichting willen laten doen, neem dan contact op met de relatie-accountmanager van SDB Zorgt.

De uitzendmodule

Voor het uitzetten van diensten naar externe partijen, dient de 'uitzendmodule' afgenomen te worden. Zonder deze module, kan er niet gewerkt worden met de API koppeling. Controleer of deze module aan staat onder Beheer -> Autorisatie -> Organisatierecht


API-key aanmaken

Ga naar Beheer –> Autorisatie –> API-accounts. Klik hier op het ‘+’ teken en vul in:

  1. Een herkenbare gebruikersnaam
  2. Een geldig van en geldig tot datum

Klik vervolgens op opslaan. Er wordt een api-key gegenereerd

Sla deze key ergens op! Deze is later niet opnieuw aan te vragen. Indien de API-key toch wordt kwijtgeraakt, dient er een nieuwe gegenereerd te worden, waarna de oude key ongeldig zal worden.

Let op! De externe organisatie/bemiddelaar kan géén info ophalen van diensten buiten deze data.
Voorbeeld: Wanneer er hier 1 februari 2025 is ingevuld en er wordt info opgevraagd vanaf 1 januari 2025, dan zal de organisatie een error 401 melding krijgen.

Planeenheid aanmaken

Ga naar Beheer -> Tabellen en maak een nieuwe planeenheid aan voor het Uitzendbureau.
Zet hier het type op Externe organisatie -PNIL en vul een geprivilegieerd emailadres in.


Medewerkers van het uitzendbureau dienen als bronplaneenheid deze planeenheid te hebben.

Autorisatiegroep voor API-account inrichten

Ga naar Beheer –> Autorisatie –> Groep. Maak hier een nieuwe groep aan met een herkenbare naam met betrekking tot de externe organisatie/bemiddelaar en klik op opslaan. Klik vervolgens op het hamburgermenu-icoon van deze regel.

Functionele rechten

Welke functionele rechten je hier invoert, is afhankelijk van welke fase en onderdelen van de API er gebruikt gaan worden. Hieronder een lijst die per functionaliteit aangeeft welke functionele rechten je hiervoor dient in te richten:

Functionaliteit
Functioneel recht
Diensten ophalen (Fase 1)
Geen
Medewerkers ophalen
Medewerkerkaart
Medewerkers aanmaken
Medewerkerkaart
Medewerkerkaart details wijzigen
Medewerkerkaart contactgegevens wijzigingen
Medewerker aanbieden (inschrijven) (Fase 2)
API – Diensten – Medewerker aanbieden
Aangeboden medewerker terugtrekken (Fase 2)
API – Diensten – Medewerker terugtrekken
Medewerker direct koppelen (Fase 2)
API – Diensten – Medewerker koppelen
Medewerker vragen
API – Diensten – Medewerker vragen
Diensten toevoegen
API – Diensten – Toevoegen
Diensten wijzigen
API – Diensten – Wijzigen
Diensten verwijderen
API – Diensten – Verwijderen

Data rechten

Bij data rechten voer je enkel de planeenheid van de externe organisatie in. Hierdoor kunnen zij enkel de diensten zien die naar hen zijn uitgezet.

Zelfmatch instellingen planeenheid

Om inschrijven en koppelen mogelijk te maken moet er bij de planeenheid voor de juiste zelfmatch instelling worden gekozen:


Diensten uitzetten naar een externe partij

Ga naar Flex -> Match. Klik met de rechtermuisknop op een dienst (dit kan zowel in de kalendermodus of in de actielijst) en klik op Flexmatchinstellingen.
Zoek onder Extern het betreffende uitzendbureau en verander de instelling van Geen naar Inschrijven of Koppelen.


Verantwoordelijkheden van iedere partij

  1. SDB Zorgt:
    1. Richting organisaties: Ondersteuning in het proces van inrichten API door beantwoorden vragen. Is er meer hulp nodig of wil de organisatie de API laten inrichten door ons? Dan zullen we middels consultancy zoeken naar een passende oplossing.
    2. Richting bemiddelaar/externe organisatie: Ondersteuning inrichten API middels beantwoorden van vragen m.b.t. het technische aspect van de API.
    3. Aanleveren van een test-account op de DZZ-omgeving van SDB Groep voor bemiddelaars/externe organisaties i.c.m. een set diensten om mee te testen.

  2. Organisatie:
    1. Inrichten van een API-account, versturen van de hierdoor aangemaakte API-key naar bemiddelaar/externe organisatie en inrichten van de juiste bijbehorende rechten op de demo-omgeving en in de volgende fase productieomgeving. Zie de handleiding “Werkinstructie API maken” in FlexPlan voor meer informatie hierover.

  3. Bemiddelaar / Externe organisatie:
    1. Communicatie met betrekking tot de ontwikkeling van de integratie richting de organisatie.

  4. Gezamenlijk:
    1. Samen zijn we er verantwoordelijk voor dat de API-workflow middels overleg goed afgestemd is ten opzichte van de huidige workflow van de betreffende organisatie. Zodat we samen zorgen voor een efficiënte oplossing!