Mijn Communities
Help

Kennisbank Youforce API & bestandsuitwisseling

Sorteren op:
Dit document beschrijft de ‘PlusPort - Visma Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.
Volledig artikel weergeven
23-12-2021 15:47 (Bijgewerkt op 24-06-2024)
  • 0 Antwoorden
  • 0 kudos
  • 1134 Weergaven
This document described the ‘mijnLMS - Visma Raet Learning API’-connector. This connector has been built on top of the Visma Raet Learning API.
Volledig artikel weergeven
23-12-2021 15:44
  • 0 Antwoorden
  • 0 kudos
  • 541 Weergaven
This document describes the ‘De leerrekening (EduBookers) - Visma Raet Learning API’ - connector. This connector has been built on top of the Visma Raet Learning API.
Volledig artikel weergeven
23-12-2021 15:43
  • 0 Antwoorden
  • 0 kudos
  • 501 Weergaven
Dit document beschrijft de ‘Dialog - Visma Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.
Volledig artikel weergeven
23-12-2021 15:42 (Bijgewerkt op 29-08-2024)
  • 1 Antwoorden
  • 0 kudos
  • 907 Weergaven
Dit document beschrijft de ‘AppicalNow - Visma|Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.
Volledig artikel weergeven
23-12-2021 15:39
  • 0 Antwoorden
  • 0 kudos
  • 842 Weergaven
With the documents endpoint files like certificates and other kind of documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).  The API supports the following types of documents certificate (Certificaat) diploma (Diploma) career agreement (Loopbaan afspraak) career mail (Correspondentie loopbaan) career other (Overige loonbaan documenten) appraisal Review (Beoordelingsgesprek) performance Review (Functioneringsgesprek)  As-synchronized file upload Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.     Endpoints The API supports the following type of documents: API endpoint Personal file system endpoint Document type Description learning/v1.0/employees/ {personCode}/documents/certificate certificaat Certificaat learning/v1.1/employees/ {personCode}/documents/certificate certificaat Certificaat learning/v1.1/employees/ {personCode}/documents/diploma diploma Diploma learning/v1.1/employees/ {personCode}/documents/appraisalReview beoordelingsGesprek Beoordelingsgesprek learning/v1.1/employees/ {personCode}/documents/performanceReview functioneringsGesprek Functioneringsgesprek learning/v1.1/employees/ {personCode}/documents/careerAgreement loopbaanafspraken Loonbaan afspraken learning/v1.1/employees/ {personCode}/documents/careerMail corrLoopbaan Correnspondentie loopbaan learning/v1.1/employees/ {personCode}/documents/careerOther ovLoopbaan Overige loonbaan documenten   Note: v1.1 is using Content-Type: multipart/form-data and supports the other document types as well. v1.0 is using Content-Type: multipart/related and supports only certificates. We are advice you the use the latest version of an endpoint   To upload a document you need to use the POST method. For example  POST https://api.youforce.com//learning/v1.1/employees/{personCode}/documents/diploma for uploading a diploma to the Personal File System of Visma Raet. The endpoint returns a  ticketId  . The file will be stored in a standard folder for diplomas (see table for the other endpoints) The API will automatically upload the file to the Personal File System. This is an a-synchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected. GET documents/{TicketId}/status Endpoint for getting the status of the file upload. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned. Examples version 1.1 (all document types) Use POST request with multipart/form-data content type. Replace the PersonCode in the URL with the Id of the employee Use the authentication token received from the authentication endpoint Replace the tenant code with the tenant code of the client Give the document a proper description The field validFrom is optional. If it's empty the system date will be used as default The content-type for the file is  application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb   Response Example of the response. HTTP/1.1 200 Content-Type: application/json { "ticketId": "7ca486f6-c730-4d50-a2ec-31a3a1373366", "description": "Example description", "size": 77491, "tenantId": "4028868", "creationDateTime": "2022-04-01T13:53:30.3985949", "status": "InProgress", "errorMessages": [] }   version 1.0 (certificates only) Use POST request with multipart/related content type with the first part having metadata in json format and the second one having a file. Replace the PersonCode in the URL with the Id of the employee Use the authentication token received from the authentication endpoint Replace the tenant code with the tenant code of the client Give the document a proper description The content-type of the metadata is application/json The content-type for the file is  application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb     POST https://api.youforce.com/learning/V1.0/api/employees//documents/certificate Authorization: Bearer [YOUR_AUTH_TOKEN] Content-Type: multipart/related; boundary=boundary_not_used_within_file_content --boundary_not_used_within_file_content Content-Type: application/json; charset=UTF-8 { "Description":"YOUR_OWN_DESCRIPTION", "ValidFrom" : "2021-01-01" } --boundary_not_used_within_file_content Content-Type: application/pdf [PDF Content] --boundary_not_used_within_file_content--  Upload status After the file is posted to the API, the file upload can be followed with the status endpoint. Replace the TicketId in the URL with the  ticketId  from the previous API call. GET https://api.youforce.com/learning/v1.0/employees/documents/{{TicketId}}/status The API will return the status of the file upload. If the API could not upload the file, an error is shown as well. Response { "status": "Complete", "errorMessages": [] }
Volledig artikel weergeven
21-12-2021 16:25 (Bijgewerkt op 28-03-2023)
  • 0 Antwoorden
  • 0 kudos
  • 1323 Weergaven
API Statuses   Controlled Available (CA) APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base: It is available to a few partners Connections of a partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted There can be functional limitations of these APIs Controlled Available APIs have the usual security and support level.   General Available (GA) APIs (or API versions) with this status are available to all partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API.   Deprecated The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement.   Life cycle policy We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience. You can also find this information in the Service Level Agreement.   Different types of changes The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behavior or semantics. The release and support strategy makes a clear distinction in how these are managed.   Major releases At times Raet may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Raet may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Raet aims to have a maximum of one major release per year. Each major release will be supported for at least 24 months after releasing the next major version. As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above.   Minor releases A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Raet can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version. As a consumer of the API it is up to you to decide if you start using the newly available features.   Announcing major releases Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes. When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it:   Communication When Where Recipient Announcement At the release of the new major version. Includes the date of decommissioning the previous version. General release notes All recipients of general release notes.   At the release of the new major version. Includes the date of decommissioning the previous version. Developer portal Designated API contact persons 1st notification 6 months prior to decommissioning   Designated API contact persons 2nd notification 3 months prior to decommissioning   Designated API contact persons 3rd notification 1 months prior to decommissioning   Designated API contact persons   Spike arrest details Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts. Spike Arrest’s behavior differs from what you might expect to see from the literal per minute values. Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals: Per-minute rates get smoothed into full requests allowed in intervals of seconds. For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail. When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.
Volledig artikel weergeven
17-12-2021 20:19 (Bijgewerkt op 30-12-2024)
  • 0 Antwoorden
  • 0 kudos
  • 1106 Weergaven
Choose an API product Youforce has several API products available, you find more information here:  https://developer.visma.com/api/youforce   Every API covers a different use cases, for example The IAM API is intended for identity & access management systems and enables the provisioning of users in other systems like Active Directory or IDP.  The Learning API provides employee data that is relevant for applications in the learning, development, appraisal domain, etc.   The File API allows you to download or upload files directly from Youforce. In this way we help to achieve ‘purpose binding’ required to safeguard the privacy of employees and to comply with GDPR legislation. It furthermore allows us to tailor and grow the API supporting specific needs in that domain   Create an account and application To use an Youforce API product, you must register and create an account. An account is quick to set up and is free of charge. A step by step manual is availible here.   Get the access token In order to grant access to a target API, Apps must first authenticate against our Authorization Server.    This token will provide access to a particular tenant in a specific application. Hence, this step will require knowing the client-id, client-secret and tenant-id.   curl -X POST   'https://connect.visma.com/connect/token'  -H 'Cache-Control: no-cache'   -H 'Content-Type: application/x-www-form-urlencoded'   -d 'client_secret=xxxxxxx      &client_id=xxxxxxxx      &tenant_id=xxxxxxxx      &grant_type=client_credentials'     Below, a response example containing the access token, the authorized scopes and the expiration time which is 1 hour max. After that time Apps need to re-authenticate to get a new access token.   {     'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',     'expires_in': '3600',     'token_type': 'Bearer',     "scope": "youforce-fileapi:files:list youforce-fileapi:files:upload" }     HTTPs support   Our API's domain is secured by using digicert (SHA2) certificates, a world wide industry-recognized provider.   Protocol TLS 1.2 (only) Key exchange ECDHE RSA with X25519 Cipher AES_256_GCM   All HTTP Requests will be refused with a Not Found 404 error response.   Request headers   Our APIs have headers in common   Header Name Description Cache-Control The Cache-Control general-header field is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain. In our authentication request the header is mandatory with the value Cach-Control: no-cache Content-Type The content type of the resource in case the request content in the body. Example: Content-Type: application/x-www-form-urlencoded Authorization The information required for request authentication Accept The Accept request-header field can be used to specify certain media types which are acceptable for the response. Example: Accept: text/plain   Response Codes Our APIs have response codes in common.   Type Responses Situation Succes Codes 200 OK Synchronous read, update, and delete operations 201 Created Synchronous create requests   202 Accepted A-synchronous operations   204 No Content Referring to non-existing entity (e.g. after delete)   Redirection Codes 304 Not Modified Resource has not been modified. 308 Permanent redirect Resource has permanently moved.   Invalid Request Errors 400 Bad request Bad Request (e.g. validation errors) 401 Unauthorized Not Authorized: Missing or invalid access token   403 Forbidden Not Authorized: Authenticated, but user has no access to the API   404 Not Found Invalid  URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized:  Authenticated, access to api, but user has no access to to the resource (data authorization).  From a security standpoint we don't expose the reason why the object could not be found because an  attacker can use this to figure out the internals of our system.   409 Conflict Concurrency problem: Record changed by another user   Server Errors 500 Internal server error Server Error (e.g. database failure, event could not be send) 503 Service unavailable Server Error (resource temporary not available)        
Volledig artikel weergeven
17-12-2021 08:53 (Bijgewerkt op 30-12-2024)
  • 0 Antwoorden
  • 0 kudos
  • 2868 Weergaven