Kennisbank Youforce API & bestandsuitwisseling

Publiceer jouw applicatie in de Visma App Store, op die manier kan een Visma Raet-consultant jouw applicatie koppelen aan een klant zonder invitatiecode.

Developer portal, een account aanmaken, applicatie registreren en toegang tot de klantgegevens

Youforce Developer Portal gaat offline Onze producten en oplossingen worden beter wanneer ze verbinding maken met een ecosysteem van geweldige andere oplossingen. Mede daarom heeft Visma Raet besloten aan te sluiten bij het Visma Developer Portal.

  Account aanmaken op Visma Developer Portal De Visma Developer portal is te bereiken via  https://oauth.developers.visma.com/service-registry/home   en maak via Create account een account aan             De portal zal via do.not.reply@mail.connect.visma.com  je een e-mail sturen met een Activatie account link.   Gebruik bij het registreren het Kvk-nummer als Organization number       Startscherm na inloggen       Desgewenst kun je een collega toevoegen via My team en New member. Jullie hebben dan beiden inzicht in de gegevens van de applicatie.       De volgende stap is het aanmaken van een applicatie. Een applicatie aanmaken   Door een applicatie aan te maken ontstaat er een API Key en een Secret Key die je gebruikt om de authenticatietoken op te halen.   Kies via het tabblad My Applications voor Add Application     Als application type selecteer Service, dit is het enige type wat door Visma|Raet wordt ondersteund.       Het aanmaken van de applicatie gaat via vier tabbladen, vul de gegevens in op het eerste tabblad Details. Weet dat de opgegeven Client Id wordt gebruikt als API key bij de API-aanroepen.   Je moet zelf de Client Id opgeven.    Testomgeving - Het is tevens mogelijk om gebruik te maken van onze sandbox. Met deze sandbox kun je testen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan de sandbox. Maak hiervoor een 2e Invitation code  aan (deze stap wordt later toegelicht).    Via deze applicatie met bijbehorende Client Id en Secret krijg je toegang de data en of bestanden uit de Youforce/HRCoreOnline-omgeving(en). Eén API key-set kan toegang geven tot meerdere klantomgevingen. Via de Tenant Id die je als Header meestuurt bij het aanvragen van een authenticatie token bepaal je de benodigde klantomgeving.   Access Token Lifetime mag op de default waarde blijven staan. Een aanpassing van deze waarde heeft geen effect op werking van de API, alsmede de opties Include JSON Web Token ID en TestApplication.   Gebruik eerst Save as a draft om vervolgens de applicatie aan te maken via Create, via Next ga je naar het volgende tabblad.       Het tabblad Credentials stelt je in staat om de API Secret aan te maken. Let op, de Secret waarde wordt alleen getoond via de pop up bij het aanmaken, dus neem dit direct over. De pop up toont ook je eerder gekozen ID (API key).   Let op: Wordt de bestaande secret vergeten dan dien je een nieuwe aan te maken, deze wordt dan toegevoegd.       Via het tabblad Integrations selecteer de gewenste Youforce API, oftewel je ‘basis’ API, je gebruikt hiervoor New integration.         Visma Raet zal de opgegeven API’s goedkeuren. Dit gaat via een workflow in de portal, je hoeft daar niks voor te doen. De goedkeuring door Visma Raet kan enkele dagen duren en zolang de goedkeuring niet is verleend kan je de stap van de Visma App Store niet uitvoeren.       Per API dien je de Scope te selecteren welke gebruikt gaat worden in de applicatie. Op deze manier kun je bepaalde functionaliteiten (endpoints) binnen de Youforce API uitsluiten van je applicatie. Je kunt vanzelfsprekend ook alle Scopes selecteren, een API kan ook bestaan uit 1 Scope.       Het tabblad Integrations kan je niet direct bevestigen via Save, dat kan pas op het moment dat Visma|Raet de gekozen API’s bij de applicatie heeft goedgekeurd, dit gaat via een flow je hoeft hier niks voor te doen. De goedkeuring door Visma Raet kan enkele dagen duren en zolang de goedkeuring niet is verleend kan je de stap van de Visma App Store niet uitvoeren.   Je kan door te klikken op stap ‘Visma App store’ naar de laatste stap (mits Visma Raet de API('s) heeft goedgekeurd).             Tabblad Visma App Store, op dit moment stellen wij de Visma App Store niet ter beschikking aan onze klanten.    Voor toegang tot de klantdata genereer je een Invitation Code. Hoe je dit doet staat hieronder verder uitgelegd. Visma Raet zal de toegang tot de klant-data goedkeuren en dan direct de koppeling van klantdata aan je applicatie gereedmaken.       Na Start setup for Visma App Store ziet u onderstaand scherm en dan kies je bij Access level - Audience voor Invite only   Vul ook de url in waar uw product is uitgelegd.       Je bent nu klaar met het aanmaken van de applicatie, de optie Save wordt zichtbaar op het moment dat Visma Raet de applicatie heeft goedgekeurd, je kunt het aanmaken sluiten door bijvoorbeeld op Back to my Applications te klikken.    Wanneer Visma Raet de goedkeuring heeft verleend, ontvang je hier een e-mail van en kun je de volgende stap uitvoeren door de applicatie te koppelen aan klant-data. Dit staat uitgelegd in het volgende hoofdstuk ‘Invitatiecode aanmaken’.   Invitatiecode aanmaken Met een invitatiecode maak je het mogelijk de klantgegevens op te halen via je applicatie. Ga naar de Developer Portal https://oauth.developers.visma.com/service-registry/home    Kies voor My Applications. En klik op het potloodje achter de applicatie (Edit).      Kies voor het tabblad Visma App Store. En vervolgens New Invitation Code.       Bij Invitation description vul je de naam van de betreffende klant in. En klik vervolgens op Generate.         Visma Raet zal de toegang tot de klant-data goedkeuren en dan direct de koppeling van klantdata aan je applicatie gereedmaken.   Binnen het beheer van je applicatie en het scherm Integrations is via de tabblad Tenants (default wordt het tabblad Scopes getoond) terug te zien welke klanten (tenants) gekoppeld zijn aan je applicatie. Dit scherm laat ook de bijbehorende TenantID zien. De TenantID is benodigd bij het opvragen van de authenticatie token.     Voorbeeld van een Tenant ID     Testomgeving - Het is tevens mogelijk om gebruik te maken van onze sandbox. Met deze sandbox kun je testen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan de sandbox. Maak hiervoor een Invitation code  aan en deel die met Visma Raet.  

Visma|Raet maakt nu gebruik van de Developer portal van Visma, een portal waar u API-applicaties kunt aanmaken en beheren. Met deze portal heeft u niet alleen toegang maar hebben uw collega's ook toegang tot de aangemaakte applicaties.   Wat moet u doen om gebruik te maken van de nieuwe portal?