Table des matières
Table des matières
Introduction
Notes
Activation de l’API
Définition des balises API dans les champs personnalisés
Structure des appels API
Gestion des erreurs
Utilisation du SSO
De votre application vers VIA : user/getsso
Introduction
Lära LMS possède une API qui vous permet d’appeler ses fonctions par n’importe quel système pour créer des branches, des fournisseurs de services, des formations et événements, des utilisateurs, etc. Il est simple, rapide et sécuritaire de l’utiliser.
Les sections qui suivent donnent aux développeurs toute l’information pertinente au développement d’un pont entre leur système et Lära LMS en utilisant l’API.
Notes
I. Pour des raisons de sécurité, il n’est pas possible de procéder librement à des requêtes API. Pour ce faire, plusieurs informations chiffrées doivent vous être transmises afin de vous permettre d’appeler correctement et vous identifier auprès du service WEB de l’API et les adresses IP de vos serveurs appelants doivent figurer dans les adresses permises de votre environnement Lära. Veuillez demander l'aide de votre conseiller en implantation à cet effet; II. Les termes techniques utilisés dans le présent guide sont définis dans l'article Consulter le lexique SVI du site Mon Assistance, qui, par ailleurs, contient beaucoup d'information sur votre nouveau système de gestion des apprentissages; III. Les appels présents dans le présent article sont vivants et des modifications seront périodiquement apportées aux fonctions API; IV. Veuillez noter que le genre masculin est utilisé de façon générique dans les articles d'assistance pour en alléger le contenu. |
Activation de l’API
Voici les étapes à suivre pour activer l'API sur le système Lära LMS. Vous pouvez demande l'aide de votre conseiller en implantation pour procéder à ces manoeuvre.
- Vous devez tout d’abord activer l’API avant de pouvoir adresser des requêtes au système. Rendez-vous dans les « Réglages avancés » du menu administration, puis sous l'onglet « API ». ATTENTION : vous devez disposer de droits administratifs élevés pour accéder à ces informations.
- Une fois dans la fenêtre « API », la liste des accès API créés sera présentée.
- Cliquez sur « Ajouter une API » pour créer votre nouvel accès API
- Entrer un Nom (administratif) et ajouter vos adresses IP à l’aide du bouton « AJOUTER UNE ADRESSE IP ».
ATTENTION : Pour ajouter une plage d'adresse, veuillez utiliser la syntaxe suivante: 127.0.0.1-127.0.0.100
Définition des balises API dans les champs personnalisés
Le portail permet la création de champs personnalisés (customs fields) sur plusieurs de ses entités (utilisateurs, formation et événements, etc.). Il vous est possible d’obtenir les informations sur ces champs par la page « Champs personnalisés » qui se trouve sous « Administration ».
Par exemple, si vous choisissiez comme élément concerné « formation et événements » la propriété correspondant à votre champ personnalisé sera prise en charge dans les appels de l’API.
Structure des appels API
La structure des appels API est simple :
- Les appels sont en HTTP à l’URL fourni dans votre portail dans la section API.
- La méthode d’appel doit être en POST
- Le format de données est en JSON
Lors de l’appel des fonctions, une entête HTTP doit être ajoutée pour contenir la clé « ApiID » et sa valeur. Cette dernière vous a été attribuée sur le portail (dans votre fournisseur de service).
Exemple de clé ApiID : 20a3581253484dcfa055904e33b3d655
Gestion des erreurs
Lorsque des erreurs surviennent sur les appels d’API, ce dernier retourne la structure générique suivante :
{
"errors": {
"message": "Invalid userId",
"code": 39
}
}
Description des codes d’erreurs génériques
Numéro | Message | Commentaires/description |
1 | Required id | Vous devez fournir un identifiant. |
2 | Invalid id | L’identifiant fourni est invalide. |
3 | Invalid country | Le pays fourni est invalide. |
4 | Invalid state | La province ou l’état fourni est invalide. |
5 | Required state | La province ou l’état est requis. |
6 | Custom field required | Le champ personnalisé se trouvant dans le message d’erreur est requis. |
7 | Custom field does not exists | Le champ personnalisé se trouvant dans le message d’erreur n’existe pas. |
8 | Custom field cannot receive null | Le champ personnalisé se trouvant dans le message d’erreur ne peut pas recevoir la valeur null. |
9 | Custom field value is not “Type” | La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas du même type que le champ. |
10 | Custom field is not a valid value of this list value | La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas comprise dans la liste des valeurs. |
11 | Custom field value is not a valid country | La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas un pays valide. |
12 | Action empty | Vous devez fournir une action à votre requête. |
13 | Json data invalid : message | Le Json est invalide. Voir le message d’erreur pour obtenir plus de précision. |
14 | Action processor not found | Le processeur en lien avec votre action n’a pas été trouvé. |
15 | Api processor not found | Le processeur fourni n’a pas été trouvé. |
16 | ApiID is empty | Vous devez fournir un identifiant pour l’Api. |
17 | Invalid ApiID | L’identifiant fourni pour l’Api est invalide |
18 | Invalid Url | L’url fourni est invalide. |
19 | Invalid IP | L’adresse IP fourni est invalide. |
20 | message | Le message vous indiquera quel est l’erreur. |
21 | Custom field value is not a valid Location | La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas un emplacement valide. |
22 | Missing search value | Aucune valeur de champ de recherche n’est spécifiée. |
23 | Unexpected Failure | Une erreur imprévue est survenue pendant l’opération d’une requête. |
Utilisation du SSO
De votre application vers VIA : user/getsso
https://www.domaine.com/lmsapi/user/getsso
Exemple d’appel :
{
"id": "MS6Hj2EsyN8wvPrcAWAZMA%3d%3d",
"portalId": "Ej1w%2flaWRrB8V5JBIxl7Cg%3d%3d",
"refId": "WSmUkyUmFT%2bEGm2dllhihg%3d%3d",
"subRefId": "WSmUkyUmFT%2bEGm2dllhihg%3d%3d",
"redirectType": 4,
"urlRedirect": null,
"forceAccess": 1
}
Réponse de l’appel (par l’API)
https://www.domaine.com/lmsapi/user/getsso
{
"urlSSO": “https://portailpreprod.sviesolutions.com/Web/SignInSSO?token=8c629721c8dc40c399fa454a289cc883"
}
Description des champs
Nom | Obligatoire | Commentaires/description |
id | ![]() | Il s’agit de l’identifiant de l’utilisateur pour lequel on désire produire un lien de transfert vers Via. (Type String) |
portalId |
| Portail par défaut pour la personnalisation et le sign out. Si la valeur est vide, le portail par défaut est utilisé. (Type String) |
refId |
| ID de référence en fonction du redirectType, nécessaire pour les modes 3, 4 et 8. (Type String) |
subRefId |
| ID de référence en fonction du redirectType, nécessaire pour le mode 8(ID d’enregistrement). (Type String) Il est important de récupérer le returnURL placé sur l’url du bouton qui envoie l’utilisateur vers le SSO afin que vous puissiez le retourner connecté dans le bon contexte. Vous devez réencoder en format URL ce paramètre afin qu’il puisse être valide. |
redirectType | RedirectTypes : Noter que la valeur urlRedirect n’est pas obligatoire si la valeur redirectType est fournie. | |
urlRedirect | Il s’agit de l’url de redirection une fois l’utilisateur authentifié. Noter que la valeur redirectType n’est pas obligatoire si la valeur urlRedirect est fournie. | |
forceAccess | | Paramètre optionnel qui est prit en compte uniquement pour le redirectType 8 (Application Via HTML5). |
Retour d'appel :
{
"urlSSO": url de redirection pour le sso. (Type String)
}