Gérer l'API et l'utiliser (Lära et Via HTML)

Miro Lagueux

Modifié le : Ven, 13 Janv., 2023 à 11:01 H

TABLE DES MATIÈRES
Introduction
Activer l'API sur votre environnement Lära LMS
Lancer un appel API
Gérer les erreurs
Description des codes d’erreurs génériques
Gérer les champs personnalisés pour les appels API

Notes

I. Pour des raisons de sécurité, veuillez demander l'aide de votre conseiller en implantation pour accéder à l'API de votre environnement Lära LMS;
II. 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.

Introduction

Lära LMS possède une API qui vous permet d’appeler ses fonctions par n’importe quel système pour gérer ses différentes composantes. Les sections qui suivent donnent aux équipes techniques toute l’information pertinente au développement d’un pont entre leur système et Lära LMS en utilisant l’API.

Activer l'API sur votre environnement Lära LMS

Pour utiliser l'API de Lära LMS, elle doit être activée, et les adresse IP des appels entrant doivent être autorisées. Vous pouvez demander l'aide de votre conseiller en implantation pour mener ces opérations.

Pour activer l'API de votre environnement et vous autoriser à passer des appels API, rendez-vous sous l'onglet « Réglages avancés » du menu « Administration », puis sous l'onglet « API ». À partir de la liste des API, cliquez sur le bouton « Ajouter une API ». Remplissez les options suivantes :

Nom : donnez un nom administratif à votre nouvelle API;
Type : vous pouvez ignorer ce paramètre. Il est présentement seulement possible de conférer un accès complet.
Adresses autorisées : pour passer des appels API, votre adresse IP ou celle du système utilisé pour les appels doivent être autorisées. Cliquez sur « Ajouter une adresse IP », et entrez la ou les adresse IP à autoriser.

ATTENTION : Pour ajouter une plage d'adresse, veuillez utiliser la syntaxe suivante: 127.0.0.1-127.0.0.100

Cliquez sur « Créer » pour créer votre nouvelle API.

Lancer un appel API

Les appels API peuvent être lancés vers Lära LMS manuellement ou avec un script, à partir d'un logiciel comme Postman ou d'une passerelle de votre organisation.

La structure des appels vers Lära LMS à privilégier est simple :

Les appels doivent être faits en HTTP;
Les appels doivent être envoyés à l'adresse URL de l'API indiquée dans le haut de l'API que vous avez créée;
La méthode d'appel doit être en POST;
Le format des données envoyées doit être en JSON;
L'entête HTTP (header) doit contenir la clé de l'API (ApiID) indiquée dans le haut de l'API que vous avez créée;

Gérer les erreurs

Lorsque des erreurs surviennent lors d'appels API sur Lära LMS, la structure générique suivante est retournée par le système :

{
  "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.
24	Invalid Color	La valeur de couleur fournie est invalide.
25	Invalid Color Length	La longueur de couleur fournie est invalide.
26	Invalid Date	La valeur de la date est en dehors des limites supportées.

Gérer les champs personnalisés pour les appels API

Il est possible d'attacher ses propres données aux différentes composantes du système Lära à l'aide de « champs personnalisés ». Pour créer ou gérer les champs personnalisés, rendez-vous sous l'onglet « Réglages avancés » du menu « Administration », puis sous « Champs personnalisés ».

Pour chaque champ personnalisé créé, vous pouvez définir l'identifiant utilisé dans l'API pour passer vos différents appels. Ces champs personnalisés sont présentés dans les autres articles de l'API correspondant aux différentes composantes.

French