API

Triaspect heeft in december 2022 een API gereleased. Deze API heeft endpoints die gebruikt kunnen worden voor gebruikersbeheer. Dan gaat het om het opvragen, toevoegen, wijzigen en verwijderen van gebruikers en hun relevante kenmerken.

Welke endpoints er zijn en op welke manier je ze kunt gebruiken, kun je vinden in de swaggerdocumentatie: https://swaggerapi-test.triasweb.nl/triaswebapi/index.html

De huidige pagina beantwoordt de volgende vragen:

Wat is een API?

API staat voor Application Programming Interface. Het zorgt ervoor dat je buiten de schermen van TriasWeb om, toch gegevens kunt uitwisselen met TriasWeb. Een API heeft endpoints. Een endpoint is een webadres waar je alleen bij kunt met een gebruikersnaam, wachtwoord en certificaat. Als je naar dat webadres toegaat (het endpoint aanroept) kun je daarmee gegevens uit TriasWeb ophalen of wijzigen.

Dit kan niet gewoon in Chrome, zoals met andere webadressen. Dit moet via een programma. Dat programma schrijf je zelf, of laat je schrijven door een technische organisatie. Triaspect kan dat niet voor je doen.

Met de TriasWeb API kun je op dit moment (december 2022) gebruikers beheren. Op latere tijdstippen wordt er ook functionaliteit ontsloten om client- en meldingsgegevens uit te wisselen.

Wat kost het?

Het gebruik van de API kost niets. Dat is verwerkt in de licentie die je betaalt voor TriasWeb. Aan het inrichten van de toegang tot de API zijn eenmalige kosten verbonden. Deze kosten betaal je voor het verkrijgen van certificaten voor test-, acceptatie- en productieomgeving en het laten controleren van het ontwerp van het programma. Vooralsnog vallen de kosten in de categorie add-on 1. Je kunt je adviseur vragen wat dat voor jullie organisatie betekent.

Wie bouwt mijn programma?

Om een programma te maken dat de API aanroept, moet je weten wat de API doet. Dat kun je lezen in de swagger-documentatie (https://swaggerapi-test.triasweb.nl/triaswebapi/index.html).

Het programma moet een certificaat kunnen inlezen en endpoints aanroepen. Als je die kennis niet zelf in huis hebt, zijn er organisaties die dat voor je doen.

Triaspect doet dat zelf niet, en heeft daarvoor ook geen partnerorganisatie gezocht. Mocht je op zoek zijn naar een organisatie die je hierbij kan helpen, dan kunnen we je de namen geven van organisaties die dit ook voor andere klanten doen.

Hoe krijg ik (of mijn leverancier) toegang tot de API?

Om te zorgen dat er op een goede manier gebruik gemaakt wordt van de API, hebben we het volgende proces ingericht.

1. Je vraagt als organisatie via de servicedesk toegang aan tot de API op de testomgeving. Hiervoor moeten de relevante IP-adressen toegevoegd worden aan de Triaspectservers. Je krijgt een certificaat, een gebruikersnaam en een wachtwoord van de SD. Hiermee kun je verbinding maken met de test-omgeving van de API. Op deze testomgeving staan alle tabellen die ook beschikbaar zijn op acceptatie en productie. De data in de tabellen is echter gefingeerd. Je kunt hier dus wel kijken wat de structuur is van de data die je terugkrijgt, en je kunt kijken of je überhaupt de data kunt benaderen, en of je de data kunt toevoegen.

2. Op basis van je tests schrijf je een ontwerp. Van dat ontwerp maak je een uittreksel van een half a-4tje waarin staat wat je wilt bereiken, welke endpoints je wilt aanroepen en hoe vaak je dat per minuut verwacht te doen. Vooralsnog hebben we een maximum van 50 aanroepen per seconde, met een sliding window. Dit ontwerp wordt gecontroleerd door onze technisch consultants. Zij kijken niet naar de functionaliteit, maar naar de techniek en het aantal aanroepen.

3. Als het ontwerp door Triaspect geaccordeerd is, kan toegang tot de acceptatieomgeving aangevraagd worden, weer via de servicedesk. Hiervoor wordt een nieuw certificaat uitgegeven.

4. Je test je programma op de acceptatieomgeving. Omdat hier jullie eigen data op staat, kan het zijn dat er nog wat aangepast moet worden aan het programma. Dat is geen probleem. Er hoeft niet opnieuw een ontwerp opgeleverd te worden.

5. Ben je tevreden met hoe het programma werkt, dan vraag je toegang aan tot de productiedata. Daarvoor krijg je weer een nieuw certificaat. Voordat dat certificaat wordt uitgegeven, doet een technisch consultant een check op het gebruik van de API op de acceptatieomgeving. Als dat nog iets bijzonders oplevert, dan wordt daarover nog even contact opgenomen.

Kan ik de API tegelijkertijd met cliënt- of medewerkersynchronisatie gebruiken?

Ja, dat kan. De API werkt nu alleen nog maar voor medewerkers (gebruikers), dus de clientsynchronisatie staat er helemaal buiten.

Het gebruik van de medewerkersynchronisatie in combinatie met de API kan heel handig zijn (zie hieronder) maar het is wel zaak om goed op te letten dat ze elkaar niet in de weg lopen. Denk bijvoorbeeld aan dat de synchronisatie die alle medewerkers deactiveert die niet in de synchronisatie zitten. Dus als je de API gebruikt om nieuwe medewerkers toe te voegen die niet in de synchronisatie zitten, dan worden die bij de eerstvolgende synchronisatie weer gedeactiveerd.

Wat is het verschil tussen de API en de medewerkersynchronisatie?

De medewerkersynchronisatie is een batchverwerking. Dat betekent dat je niet alleen de verschillende medewerkers verwerkt, maar dat er ook nog zoiets is als álle medewerkers in de synchronisatie. Dat is bijvoorbeeld gebruikt bij het ‘vooraf deactiveren’ waarbij alle medewerkers die niet in de synchronisatie aanwezig zijn, deactief worden.

De API verwerkt 1 medewerker per keer. Je kunt met de API geen verband aanbrengen tussen medewerkers. Dat zou wel kunnen in het programma wat je bouwt om de API aan te roepen, maar er is dus geen functie ‘vooraf deactiveren’ die je kunt aanroepen.

Voor de medewerkersynchronisatie geldt nu dat je er minder mee kunt dan met de API. Met de API kun je bijvoorbeeld een gebruiker als hoofdverantwoordelijke koppelen aan een organisatieonderdeel. Of je kunt een of meerdere rollen koppelen aan een gebruiker. Dat kan in de medewerkersynchronisatie niet, en dat zal ook niet meer ontwikkeld worden door Triaspect.

Hoe kan ik de API slim inzetten in combinatie met de medewerkersynchronisatie?

Je kunt tijdelijke accounts voor ZZP-ers aanmaken via de API, terwijl de medewerkersynchronisatie gewoon de ‘normale’ accounts afhandelt. Dat kan bijvoorbeeld zo:

• Zorg voor een lijst met alle actuele ZZP-ers. Deze moet je twee keer verwerken, met (bijvoorbeeld) een week ertussen.

• Per ZZP-er roep je de endpoint GET /api/users?method=email&value=iemand@organisatie.nl op basis van de identificatie (email in dit voorbeeld) aan.

• Als je 404 terugkrijgt is deze persoon niet aanwezig in TriasWeb. Dan roep je de PUT /api/users aan met de relevante parameters in de request body. Zorg ervoor dat handmatig deactiveren aangezet wordt ("isDeactivationManual": true) zodat de medewerkersynchronisatie deze gebruiker niet verwijdert.

• Als de gebruiker bestaat, dan update je indien nodig. Zorg ervoor dat handmatig deactiveren aangezet wordt (zet "isDeactivationManual": true in de request body) zodat de medewerkersynchronisatie deze gebruiker niet verwijdert.

• Na een week (of hoe lang je ook wilt) verwerk je de lijst nogmaals, maar verwijder je de gebruikers die op de lijst staan, uit TriasWeb. Deactiveer de gebruiker met endpoint.
  /api/users/close-account?method=email&value=iemand@organisatie.nl

• Voer het programma meteen weer uit met een nieuwe lijst met ZZP-ers.