Introduction

Introduction

La documentation proposée traite avant tout de l'utilisation de nos API.
Nous proposons également des interfaces web et mobile en marque blanche permettant de couvrir les cas d'usage mentionnés. Vous pouvez demander une démonstration via notre formulaire de contact

Traçabilité des appels et historisation des données

Un système de gestion des insertions et mises à jour de données est en place pour suivre les changements opérés par nos utilisateurs. Nous avons en particulier un suivi des dates, heures, contenu et compte utilisateur responsable des modifications de données sociales.

Certaines données sont également historisées comme la rémunération pour permettre de regénérer les calculs à une date donnée en cas de besoin.

Principes d'utilisation de l'API Listo

Un utilisateur ne peut consulter ou modifier que des éléments sur lesquels il a des droits.
Lorsqu'un partenaire crée un établissement, les droits de gestion de cet établissement et des éléments associés (salariés, contrats...) sont accordés au compte ayant servi pour la création.

Un utilisateur peut accorder des droits au mieux équivalent aux siens à un autre utilisateur.

Format pris en charge

La majorité des endpoints supportent les formats d'échange application/json, application/ld+json, application/hal+json, application/xml, text/xml

Par défaut les exemples de retours proposés sont au format application/json.

Pagination

Pour garantir des performances optimales, les requêtes ne renvoient que les 100 premiers résultats.
Il faut indiquer la page à retourner en attribut de la requête :
page=X

Le format application/ld+json permet de récupérer la dernière page disponible en valeur de l'attribut :
"hydra:last"

Documentation des exemples d'appels API

Les variables à définir lors de chaque appel sont définies selon le format suivant :
<Description de la variable>

Les valeurs importantes à conserver en retour de l'API sont indiqués selon le format suivant :
!Description de la valeur!

Les commentaires dans les exemples d'appels sont sous le format suivant pour conserver la mise en forme : "#Commentaire",

A noter que par soucis de simplification, seules les informations pertinentes et en lien avec le cas d'usage concerné sont documentées. Les JSON peuvent contenir plus d'attributs.
En cas de doute sur la volumétrie, n'hésitez pas à nous contacter.

Authentification

L'API Listo nécessite l'utilisation d'un token. Il est obtenu de la façon suivante, après création d'un compte :

📘

L'identifiant du compte API doit être une adresse mail valide que vous pouvez consulter. Cela est rendu nécessaire notamment pour la gestion des renouvellements / changements de mot de passe ainsi que l'envoi de rapports d'erreurs détaillés (en cours d'implémentation).

Nous vous recommandons de prévoir un compte d'administration pour chaque établissement qui héritera des droits du compte API principal utilisé pour la création de l'établissement.

cURL

curl --location --request POST '<URL Environnement>/api/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "<Email associée au compte API>",
    "password": <Mot de passe associé au compte API>"
}'

Vous pouvez demander la création de votre compte de test via notre formulaire de contact ou directement via notre notre dépôt publique en créant un ticket

Erreurs éventuelles

Code	Explication
401	Les informations saisies ne sont pas correctes (mauvais identifiant ou mot de passe)

Retour

JSON

{
	"token": "!Token!",
  "user": {
    "id": "!Identifiant User!"
  }
}

Ce token doit ensuite être fourni à chaque appel :

cURL

--header 'Authorization: Bearer <Token>'

Changement du mot de passe

Il est possible de changer le mot de passe en accédant à l'interface web d'administration et en utilisant la fonctionnalité "mot de passe oublié".
URL : "<Environnement>/signin"

Méthodes API disponibles

L'API propose les méthodes GET ainsi que POST, PUT et DELETE dans le cas où les données peuvent être transmises, modifiées et/ou supprimées.
L'utilisation des méthodes PUT et DELETE nécessite de préciser l'ID technique de la donnée à modifier/supprimer dans l'URL d'appel

A l'issue d'un POST, l'identifiant technique de la donnée créée est retourné pour faciliter les futures modifications ou la suppression.