API Update 2023-03

[#1]

De afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:  

Alle API's
Privé contactgegevens niet standaard zichtbaar in API

In alle API's is een aparte scope opgenomen voor de privé contactgegevens, zoals adres, telefoonnummer en emailadres. Dit betreft de scope GetPrivateContactDetails. 
Standaard is deze scope niet geactiveerd en worden de privé contactgegevens niet in de API weergegeven, alleen het zakelijke emailadres (P01035) en het telefoonnummer werk (P01037) wordt dan in de API getoond.

Wilt u privé contact gegevens wel willen gebruiken in uw applicatie dan zult u dat bij uw uw software leverancier moeten aangeven zodat zij de scope voor de applicatie kunnen activeren. Ook zal een de API consultants de autorisatie op uw data moeten wijzigen. Zie ook eerdere bericht Nieuwe scope voor privé contactgegevens zoals adres, telefoonnummer en emailadres 

IAM API
Het Veld UserUID is toegevoegd aan het endpoint persons

Voorheen was het alleen mogelijk om het UserUID op te halen via het GET User endpoint in de IAM API, wat betekende dat het UserUID per persoon opgevraagd moest worden. Vanaf nu is het mogelijk om het veld standaard op te halen via het Person endpoint, waardoor alle UserUID's van alle medewerkers eenvoudig opgehaald kunnen worden.

Extra controles in PATCH User endpoint

Er zijn enkele controles toegevoegd aan het patch user endpoint. Er wordt nu strenger gecontroleerd op het formaat van de aangeboden json in de body, waarbij het veld "id" vereist is en niet mag worden ondergebracht in een sub-entiteit zoals "User" of "Users". Raadpleeg het artikel IAM user endpoint  voor de juiste aanroep.

Daarnaast wordt er bij de update van de identiteit gecontroleerd of het gebruikersaccount bestaat. Als het gebruikersaccount niet in de Youforce-omgeving wordt gevonden, wordt er een 404-not found melding teruggegeven. Dit kan bijvoorbeeld het geval zijn als het veld "Youforce gebruiker" (P15013) in Beaufort op "Nee" staat.

Endpoints voor het schrijven van zakelijk email adres en telefoonnummer toegevoegd

Er zijn nieuwe endpoints toegevoegd aan de IAM API voor het terugzetten van het zakelijke e-mailadres (P01035) en telefoonnummer (P01037).

De endpoints zijn:

Endpoint	Toelichting
POST /iam/v1.0/contactDetails/[PersonCode] Met in de body: {     "emailAddress": "demo@visma.com",     "phoneNumber": "010-12345678" }	Voor het schrijven van het zakelijk email adres en/of telefoonnummer van een individuele medewerker.
POST /iam/v1.0/contactDetails/bulk met in de body: [     {         "personCode": "10000",         "emailAddress": "bulk.01@visma.com",         "phoneNumber": "030-12344567"     },     {         "personCode": "100001",         "emailAddress": "bulk_02@visma.com",         "phoneNumber": "0341-23457"     } ]	Voor het schrijven van het zakelijk email adres en/of telefoonnummer van meerdere medewerkers gelijktijdig. Maximaal 100 medewerker per API call.
GET /iam/v1.0/ContactDetails/[ticketId]/status waarbij het [ticketId] uit de response van oorspronkelijke POST endpoint gebruikt moet worden.	Endpoint voor ophalen van de status van het terugschrijven.