Comment utiliser l'API Checklick

Si votre organisation souhaite intégrer ses propres systèmes avec Checklick, vous pouvez utiliser l'API de Checklick. L'API est disponible pour toutes les organisations.

Démarrage rapide

Pour commencer rapidement et envoyer une requête de test à Checklick :

Connectez-vous à Checklick en tant que gestionnaire de votre organisation.
Cliquez sur le menu contextuel de l'utilisateur (en haut à droite).
Cliquez sur votre nom.
Trouvez la section Clé secrète de l'API (API Secret Key) et cliquez sur générer une nouvelle clé.
Vous devriez maintenant voir une zone de texte avec un exemple de commande cURL. Copiez et collez-la dans votre terminal, puis appuyez sur Entrée.
Vous devriez recevoir une réponse JSON contenant la liste de toutes les personnes de votre organisation.

À propos de l'API

L'API de Checklick est une API de type RESTful qui renvoie des données au format JSON. L'API respecte la spécification JSON-API, qui est une norme documentée pour la structure des requêtes et des réponses API.

Chaque gestionnaire dans Checklick est en mesure de générer sa propre clé API secrète (indépendante de son identifiant et de son mot de passe), qu'il peut utiliser pour accéder aux données de Checklick via l'API.

La portée de l'accès aux données d'un utilisateur de l'API sera la même que sa portée d'accès dans l'application web. Un utilisateur de l'API pourra uniquement afficher et modifier les données des personnes faisant partie des organisations qu'il gère, ainsi que des organisations qu'il peut consulter en raison de licences de listes de contrôle.

Points de terminaison de l'API (Endpoints)

L'API utilise des URI sans état, basées sur les ressources. Les points de terminaison suivants sont disponibles à partir de https://api.checklick.com depuis la dernière version de l'API (version 2) :

URI	Verbe HTTP	Description
/users	GET	Récupérer toutes les personnes visibles pour cette organisation
/users	POST	Créer une nouvelle personne
/users/1	GET	Récupérer une personne spécifique
/users/1	PATCH	Mettre à jour une personne
/users/1/assessments	GET	Récupérer toutes les évaluations (registres de compétences) pour une personne
/users/1/assessments/1	GET	Récupérer un registre d'évaluation spécifique pour une personne
/users/1/credentials	GET	Récupérer tous les registres de certifications pour une personne. Les registres de certifications sont utilisés pour produire les certificats de réussite de niveau.
/users/1/credentials/1	GET	Récupérez le dossier de compétences d'une personne. Les dossiers de compétences servent à délivrer les certificats de réussite de niveau.
/users/1/tag-applications	GET	Récupérer toutes les applications de étiquettes (étiquettes générales) pour une personne
/users/1/tag-applications/1	GET	Récupérer une application d'étiquette spécifique pour une personne
/users/1/tag-applications	POST	Appliquer une étiquette existante à une personne
/users/1/tag-applications/1	DELETE	Retirer une étiquette existante d'une personne
/tags	GET	Récupérer toutes les étiquettes existantes (créées par votre organisation)
/tags	POST	Créer une nouvelle étiquette
/tags/1	GET	Récupérer une étiquette existante
/tags/1	PATCH	Mettre à jour une étiquette existante
/tags/1	DELETE	Supprimer une étiquette existante
/tags/1/tag-applications	GET	Révéler toutes les applications d'étiquettes (étiquettes générales) d'une étiquette spécifique
/tags/1/tag-applications	PUT	Appliquer une étiquette existante à une personne
/tags/1/tag-applications/1	GET	Récupérer une application d'étiquette spécifique pour une personne
/tags/1/tag-applications/1	DELETE	Retirer une étiquette existante d'une personne
/checklists	GET	Récupérer toutes les listes de contrôle disponibles pour cette organisation
/checklists/1	GET	Récupérer une liste de contrôle spécifique
/levels	GET	Récupérer tous les niveaux disponibles pour cette organisation
/levels/1	GET	Récupérer un niveau spécifique
/levels/1/credentials	GET	Récupérez toutes les certifications (niveaux atteints) pour ce niveau et attribuées aux personnes visibles par cette organisation. Ces enregistrements de certifications servent à produire les certificats de réussite de niveau.
/levels/1/credentials/1	GET	Récupérez une attestation spécifique. Les relevés d'attestation servent à produire les certificats de réussite de niveau.
/sections	GET	Récupérer toutes les sections disponibles pour cette organisation
/sections/1	GET	Récupérer une section spécifique
/skills	GET	Récupérer toutes les compétences disponibles pour cette organisation spécifique
/skills/1	GET	Récupérer une compétence spécifique
/skills/1/assessments	GET	Récupérer toutes les évaluations (niveaux de registres de compétences) pour cette compétence et enregistrées pour les personnes visibles par cette organisation
/skills/1/assessments/1	GET	Récupérer une évaluation spécifique

Voici un exemple de requête pour le point de terminaison suivant /tags (POST - Créer une nouvelle étiquette) :

{
"data": {
"type": "tags",
"attributes": {
"name": "NOM DE L'ÉTIQUETTE" }
}
}

Point de terminaison /tags/1/tag-applications (PUT - Appliquer une étiquette existante à une personne) :

{

"data": {

"type": "tag_applications",

"attributes": {

"detail": "detail text"

"relationships": {

"tag": {

"data": { "type": "tags", "id": 62782 }

"user": {

"data": { "type": "users", "id": 161753 }

}

La description complète de la charge utile :

Quelles sont les exigences minimales pour créer un nouvel utilisateur ?

Lors de la création d'un nouvel utilisateur, les champs suivants sont obligatoires : nom d'utilisateur, prénom, nom, adresse e-mail, date de naissance, mot de passe, confirmation du mot de passe.

Voici la description complète de la charge utile :

{

"data": {

"type": "users",
"attributes": {
"username": "test user",
"first-name": "testuser",
"last-name": "testuser",
"email": "test@test.com",

"birth-date": "1999-02-19",

"gender": "",
"full-address": "",
"street-address": "",
"city": "",
"province": null,
"country": "",
"postal-code": "",
"political": null,
"admin-area-2": null,

"admin-area-3": null,

"admin-area-4": null,

"admin-area-5": null,

"colloquial-area": null,

"ward": null,

"sublocality": null,

"neighborhood": null,

"premise": null,

"subpremise": null,

"lat": null,

"lng": null,

"phone": null,

"health-notes": null,
"personne-à-contacter-en-urgence": null,

"coordonnées-à-contact-en-urgence": null,

"mot-de-passe": "1234",

"confirmation-mot-de-passe": "1234"
}
}
}
Exigences de connexion

Sous-domaine de l'API

Toutes les requêtes doivent être envoyées à api.checklick.com. Toute requête API envoyée à app.checklick.com, www.checklick.com ou tout autre sous-domaine de Checklick sera refusée.

HTTPS

Les requêtes envoyées via HTTP seront refusées. Toutes les requêtes doivent être envoyées en utilisant HTTPS.

En-tête Content-Type

Toutes les requêtes doivent inclure l'en-tête de type de média spécifique au fournisseur JSON API. Par exemple :

Content-Type:application/vnd.api+json

En-tête de version de l'API

L'API Checklick dispose d'un système de gestion des versions, ce qui signifie que les futures mises à jour de l'API ne casseront pas nécessairement votre implémentation actuelle. La version actuelle de l'API est la version 2. Toutes les requêtes doivent inclure un numéro de version sous forme d'en-tête. Par exemple :

Api-Version:2

Clé secrète

Checklick utilise des clés secrètes pour authentifier chaque requête (au lieu d'un identifiant et d'un mot de passe). Chaque gestionnaire d'une organisation peut créer une clé secrète unique. Voici comment générer votre clé :

Connectez-vous à Checklick en tant que gestionnaire de votre organisation.
Cliquez sur le menu contextuel de l'utilisateur (en haut à droite).
Cliquez sur votre nom.
Trouvez la section Clé secrète de l'API (API Secret Key) et cliquez sur générer une nouvelle clé.

Toutes les requêtes doivent inclure une clé secrète valide. Par exemple :

Authorization:Token token=2c96ef73e5ad003362b1851cb7c607f3

Identifiant de l'organisation

De nombreux gestionnaires gèrent plus d'une organisation dans Checklick. Comme méthode d'authentification supplémentaire, toutes les requêtes doivent inclure un en-tête spécifiant un identifiant d'organisation qui provient d'une organisation gérée par l'utilisateur dont la clé secrète a été transmise. Par exemple :

Organization-Id:999

L'identifiant de l'organisation sera utilisé comme « contexte » pour la requête, ce qui signifie que les données que vous recevrez seront limitées aux mêmes données auxquelles vous pouvez accéder lorsque vous gérez cette organisation spécifique.

Assembler le tout

Si vous utilisez cURL, votre requête pourrait ressembler à ceci :

curl -X GET \

https://api.checklick.com/users\

-H 'Api-Version: 2' \
-H 'Authorization: Token token=2c96ef73e5ad003362b1851cb7c607f3' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Organization-Id: 999'

Pagination, recherche et filtrage

Pagination

Les résultats contenant plus de 10 éléments seront automatiquement paginés. Vous verrez des liens au bas de vos résultats vers la première, la suivante et la dernière page. Par exemple :

JSON

"links": {

"first": "https://api.checklick.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10",

"last": "https://api.checklick.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10"

}

Recherche ou filtrage

Lorsque vous accédez à des points de terminaison qui renvoient plusieurs éléments, vous pouvez inclure un paramètre de filtre pour limiter le nombre d'éléments affichés. Ces paramètres doivent être inclus dans votre requête en tant que paramètres de requête.

La plupart des attributus peuvent être utilisés comme paramètres. Par exemple, pour filtrer toutes vos personnes par un nom de famille spécifique, essayez :

https://api.checklick.com/users?filter[last_name]=Smith

Vous pouvez également appliquer deux filtres spéciaux, created_on_or_after et created_before, pour afficher uniquement les enregistrements créés à une date et une heure spécifiques, après ou avant. Le paramètre de ce filtre est un horodatage UNIX. Par exemple, pour obtenir tous les utilisateurs créés après le 1er janvier 2018, essayez :

https://api.checklick.com/users/?filter[created_on_or_after]=1514764800

Vous pouvez facilement convertir des dates en horodatages UNIX grâce à cette page.