Avant de commencer
Lucca met à disposition deux API distinctes :
- L’API Legacy, disponible au lien : https://developers.lucca.fr/api-reference/legacy/introduction ;
- L’API Lucca, disponible au lien : https://developers.lucca.fr/api-reference/latest/introduction.
Pour comprendre les différences et savoir laquelle utiliser, nous vous invitons à vous rendre sur la documentation directement. Nous recommandons autant que possible d’utiliser l’API Lucca.
Les applications OAuth permettent de s’authentifier pour utiliser l’API Lucca. Pour s’authentifier et utiliser l’API Legacy, vous devez suivre cette fiche d’aide : générer une clé API.
Lors de la création, des scopes vous seront demandés. Pour définir ceux dont vous aurez besoin, vous devez anticiper vos besoins à l’aide de la documentation API et lister les scopes nécessaires suivant les requêtes. Sachez que la liste des scopes est modifiable après la génération de l’application.
Voici la liste des scopes disponibles : https://developers.lucca.fr/api-reference/latest/oauth-scopes.
Attention aux scopes que vous donnez à l'application OAuth et à qui vous transmettez le client ID et client secret. La personne possédant ces données peut obtenir des informations qui peuvent être confidentielles.
Créer une nouvelle application OAuth
Pour créer une nouvelle application OAuth, vous devez vous rendre dans la roue crantée > Authentification, SSO et API > Applications OAuth. Si vous n'avez pas les droits d'accès, veuillez contacter votre administrateur pour qu'il génère l’application OAuth et si vous êtes administrateur sans accès aux rôles, veuillez, contactez le support.
Cliquez sur Créer une application pour créer l’application OAuth.
1 - Contact technique
Renseignez le mail de contact associé à cette application OAuth, ce mail permet à Lucca de contacter un référent en cas de souci technique sur l’API. Pour assurer la validité du mail, vous devez renseigner un code reçu par mail.
2 - Informations
Renseigner quelques informations tel que le nom de l’application OAuth et l’usage pouvant être interne ou bien pour un éditeur spécifique. Le nom doit être le plus représentatif possible de l’intégration pour pouvoir l’identifier dans le futur.
3 - Scopes
Sélectionnez les scopes préalablement choisis depuis la documentation API.
4 - Établissements
Choisissez les établissements accessibles avec cette application OAuth et toutes les intégrations qui s’en serviront.
5 - Génération terminée !
Une fois la création terminée vous pourrez visualiser deux informations nécessaires à l’utilisation de l’API, le client ID et la valeur du secret, attention la valeur du secret n’est visible que maintenant et est valable 3 ans.
Modifier à une application existante
Vous pouvez revenir sur une des étapes de la création pour modifier une application OAuth. Pour ce faire, rendez-vous sur Éditer. Vous pourrez y modifier les scopes (1), les établissements (2) et le contact technique (3).
Gérer les secrets
Vous pouvez gérer les secrets dans le but d’en supprimer ou d’en créer de nouveaux en vous rendant dans Gérer les secrets.
Vous y trouverez la date d’expiration de chaque secret et la possibilité d’en créer de nouveau avec le bouton en haut à droite.
Comme expliqué précédemment, il n’est pas possible de revoir un secret après sa génération.
Utiliser une application OAuth
Pour utiliser l’API Lucca vous devez générer un Bearer token qui nécessite de faire une première requête API transmettant différentes informations, dont le Client ID de l’application OAuth et le secret. Le détail de la requête à réaliser est expliqué dans notre documentation : Create Access-Token.