Verbeteringen in de API: foutmeldingen en OAuth

Met een API wissel je eenvoudig gegevens uit tussen jouw verschillende softwarepakketten en Plan4Flex. Dat maakt jouw werk een stuk efficiënter.
Omdat we slimmer werken blijven verbeteren, passen we twee zaken in de API aan. Foutmeldingen zijn nu duidelijker en vanaf volgend jaar (november 2027) verandert KeyBasedAuthentication naar OAuth. Lees hieronder wat dit voor jou betekent en wat je ervoor moet doen.

Uitbreiding terugkoppeling foutmeldingen

De foutmeldingen die je krijgt teruggekoppeld via de API worden uitgebreid.

Wat betekent dat voor mij?

Niet iedereen die met de API werkt, gaat dit merken. In het kort:

• Ik heb geen koppeling met de Plan4Flex API -> er verandert niets
• Mijn koppeling laat foutmeldingen alleen zien of bewaart ze in een log -> er verandert niets
• Mijn koppeling koppelt een foutmelding automatisch aan een veld -> Lees hieronder verder

Worden foutmeldingen direct aan een bepaald veld gekoppeld? Bijvoorbeeld door de melding naast het juiste invoerveld in een formulier te tonen. Dan is een kleine aanpassing nodig. Doe dit vóór eind november, anders werken de foutmeldingen niet meer correct.

Onderhoud je de koppeling niet zelf? Stuur dit bericht dan door naar de partij die de koppeling heeft gebouwd of beheert. Met de technische toelichting hieronder kunnen de aanpassing voor je doen.

Wat verandert er?

In een foutmelding staat bij welk veld de fout hoort. Die veldnaam schrijven we voortaan precies zoals in de rest van de API. De tekst van de foutmelding blijft hetzelfde.

Technische toelichting voor ontwikkelaars

Het gaat om validatiefouten met statuscode 422, en dan om de sleutels in errors en errorCodes.

1. Sleutels staan voortaan in camelCase, net als de JSON-velden in request en response.
2. Heeft een veld in de API een afwijkende JSON-naam, dan gebruiken we die naam in plaats van de interne naam.
3. Fouten in een adres binnen een object krijgen nu het juiste voorvoegsel: address, addressAbroad, pickupAddress of mailingAddress. Dat geldt onder andere voor Employee, CandidateEmployee, Branch en Housing.

Wat gelijk blijft: de foutteksten, de foutcodes, de parameters en statuscode 422.
Controleer je code op deze punten:

• Exacte vergelijking met de oude sleutel: zoals errors[“$.LicensePlate”]. Die vindt niets meer, dus gebruik de nieuwe sleutel $.licensePlate.
• Vergelijking zonder hoofdlettergevoeligheid: Die blijft werken voor gewone velden, maar niet voor adresvelden: $.streetName vindt $.address.streetName niet.
• De sleutel zelf samenstellen uit een interne veldnaam: (PascalCase). Gebruik voortaan de JSON-naam zoals u die in de request verstuurt.
• Omweg voor adresfouten: Koppelde uw code een adresfout aan het hoofdobject omdat het voorvoegsel ontbrak? Dan kunt u de fout nu aan het juiste adresveld koppelen en is de omweg niet meer nodig.

KeyBasedAuthentication vervangen door OAuth

Je maakt contact met je API via KeyBasedAuthentication. Deze methode is verouderd. Daarom stappen we over op OAuth. Per 1 november 2027 zetten we de knop om. Vanaf die datum is het niet meer mogelijk om de API aan te roepen en informatie op te halen of weg te schrijven met KeyBasedAuthentication.

Maar: je kunt nu al overstappen. Maak het jezelf makkelijk en regel dit zo snel mogelijk.

Wat moet ik doen?

Maak jij, of je koppelpartij, gebruik van de Plan4Flex API? Controleer dan of dit via de KeyBasedAuthentication is, of dat jij al gebruikmaakt van OAuth.

Nog geen OAuth? Maak dan een ticket aan via ons selfserviceportaal waarin je vraagt om OAuth credentials en geef beknopt aan welke handelingen je via de API doet. Wij stellen dan de juiste scope voor je gebruiker in.

Zorg ervoor dat je dit uiterlijk in augustus 2027 omzet als je de API wil blijven gebruiken.

We zetten de API in als matchmaker tussen jouw verschillende systemen. Heb jij een softwarepakket dat je via de API wil laten communiceren met Plan4Flex? Vraag bij Renate een offerte aan voor deze koppeling. Stuur een mail naar renate.peters@plan4flex.nl.