Utiliser l'API externe

Mis à jour le 19 novembre 20267 min de lecture

Disponible avec : Business. Non inclus dans Starter et Pro. Comparer les offres

L'API externe permet de connecter vos outils à Lexio : catalogue de véhicules, clients, réservations et opérations de location. Les clés sont réservées aux appels entre serveurs et doivent rester confidentielles.

Ce guide s'adresse au loueur : créer et surveiller ses clés, choisir leurs scopes, savoir ce que l'intégration voit et fait dans Lexio. Tout le détail technique (démarrage rapide, authentification, codes d'erreur et leur ordre, idempotence, pagination, synchronisation par événements, limites de débit, versions) est publié sur docs.lexio.rent : transmettez cette adresse à votre développeur ou à votre partenaire. Cette documentation fait foi ; la spécification OpenAPI se télécharge sur https://docs.lexio.rent/openapi.json.

Avant de commencer

  • L'API externe est incluse dans le plan Business. Sans lui, chaque appel répond 403 FEATURE_NOT_AVAILABLE : voir Différences entre les plans.
  • Sur Starter et Pro, Paramètres > Développeur montre un exemple verrouillé avec le bouton Débloquer l'API. Si des clés créées auparavant existent encore, elles restent listées sous l'encart API non incluse dans votre offre : elles sont refusées tant que l'offre ne comprend pas l'API, et vous pouvez les révoquer. Le bouton Nouveau token et la bascule d'activation des clés n'apparaissent pas.
  • Il n'y a pas de bac à sable : faites tester l'intégration sur une organisation de test dédiée, avec des dates futures, puis annulez les locations d'essai.

Créer une clé

Avec la permission Gérer les jetons Pennylane et API, modifier l'IBAN (avec « Gérer les paramètres ») (réservée par défaut au propriétaire, qui peut l'accorder à un membre), ouvrez Paramètres > Développeur, puis Nouveau token.

  1. Donnez un nom au token, de 3 à 100 caractères. Nommez-le d'après l'intégration (« Site de réservation », « Plateforme X ») : ce nom signe ses écritures dans Lexio.
  2. Cochez au moins une permission (un scope, voir ci-dessous) nécessaire à votre intégration. Voir les clients est coché par défaut : décochez-le s'il n'est pas utile.
  3. Choisissez une expiration : Jamais, 30 jours, 90 jours, 6 mois ou 1 an (choix par défaut).
  4. Cliquez sur Créer le token.
  5. Copiez la clé complète avant de fermer la fenêtre et transmettez-la par un canal sûr.

La clé complète n'est affichée qu'à sa création. La liste conserve son préfixe, son créateur, sa dernière utilisation connue et son expiration. Une clé perdue doit être remplacée.

Une organisation garde au plus 20 clés non révoquées (une clé désactivée ou expirée compte tant qu'elle n'est pas révoquée), et un utilisateur crée au plus 10 clés par heure.

Choisir les scopes

Un scope ouvre une famille d'opérations, par exemple rentals.read (voir les locations) ou payments.refund (rembourser). Le libellé de chaque scope s'affiche à la création de la clé ; la correspondance complète entre scopes et opérations est publiée sur docs.lexio.rent, guide « Authentification et scopes ». Accordez le minimum nécessaire.

Intégration Scopes habituels
Site ou plateforme de réservation offers.read, quotes.write, rentals.read, rentals.write, et payments.write pour enregistrer les paiements
Outil de planning en lecture rentals.read, vehicles.read
Application de départ et de retour rentals.read, rentals.operate, et payments.write pour encaisser au départ ou au retour
  • Vous ne pouvez accorder que les scopes dont vous détenez vous-même les permissions dans Lexio.
  • Les scopes d'une clé ne se modifient pas : pour en changer, créez une nouvelle clé.
  • Les scopes sensibles sont à part : payments.refund (remboursements, décision sur un trop-perçu), rentals.delete et les autres …delete (suppressions définitives), customers.read (données personnelles de vos clients).
  • Seuls ces scopes s'accordent : les noms de permission de Lexio et les anciens raccourcis read, write, delete et admin sont refusés. Une ancienne clé qui n'en portait aucun autre n'ouvre plus rien (badge « Aucune permission v1 : clé inopérante, recréez-la ») : remplacez-la.

Pour un partenaire tiers (comparateur, broker), renseignez un Code partenaire à la création, dans Paramètres > Développeur ; il ne se modifie plus ensuite. Ses locations, devis et clients restent cloisonnés à ce code, et seuls catalog.read, offers.read, quotes.write, rentals.read, rentals.write et payments.write (paiement Stripe seulement) lui sont accordables. Une clé sans code voit toutes les locations de l'organisation, dans la limite de ses scopes.

Ce que l'intégration voit et fait dans Lexio

  • Une clé appartient à une seule organisation et ne lit que ses données, dans la limite de ses scopes.
  • Ses écritures portent pour auteur « API : » suivi du nom de la clé, dans les notes, les paiements et le journal d'activité.
  • Chaque location créée par l'API vous est signalée. L'email de confirmation au client ne part que si le réglage d'emails Confirmation de réservation (API externe) est actif.
  • Les notes internes de votre équipe ne se lisent ni ne s'écrivent par l'API. L'intégration sait qu'un client est bloqué (refus « Client bloqué », indicateur sur la fiche client), mais n'en reçoit jamais le motif, ni de nom de client dans le message.
  • Les remises qu'une clé ajoute à une location sont plafonnées comme celles d'un membre : le plafond Membre des Remises commerciales (Paramètres > Exploitation) s'applique. Voir Plafonds de remise commerciale. Le code promo n'entre pas dans ce plafond.
  • L'API n'applique aucun frais d'annulation et n'exécute aucun remboursement : elle enregistre ceux que vous ou l'intégration déclarez. Les frais se facturent dans Lexio, selon votre politique.
  • Une annulation enregistrée par l'API émet les avoirs des factures déjà émises. Un remboursement n'émet un avoir que pour la part qui fait passer l'encaissé sous le montant facturé : rendre un trop-perçu n'en émet aucun. Ces avoirs sont transmis à votre comptabilité si elle est connectée.

Certaines décisions restent dans Lexio : les blocages de planning (hors entretien), le contrôle technique, la création et la suppression des saisons, le blocage d'un client, la fiche entreprise nécessaire aux avoirs, la création des codes promo, l'approbation des demandes du site de réservation, les réglages tarifaires, et la création ou la suppression d'un palier de majoration courte durée (l'API modifie le taux, l'état et les exceptions par saison des paliers existants). La liste à jour figure sur docs.lexio.rent, guide « Ce qui se gère dans Lexio ».

Surveiller une clé

La clé appartient à l'organisation, pas à la personne qui l'a créée : elle continue de fonctionner si son créateur perd des droits, quitte l'équipe ou supprime son compte. Quand le créateur est retiré de l'équipe, les membres qui gèrent les clés reçoivent une notification dans Lexio : à eux de garder ou de révoquer ses clés. Seuls la suspension de l'organisation, la perte de l'accès API ou le blocage du compte du créateur par Lexio interrompent une clé valide.

Situation Réponse de l'API Qui agit Même clé ensuite
Clé désactivée 401 API_KEY_DISABLED Vous la réactivez dans Paramètres > Développeur. Oui
Clé expirée ou révoquée 401 API_KEY_EXPIRED ou API_KEY_REVOKED Vous créez une nouvelle clé. Non
Créateur retiré de l'équipe Aucun refus : la clé continue de fonctionner Les gestionnaires des clés, prévenus dans Lexio, la gardent ou la révoquent. Oui
Créateur rétrogradé ou compte supprimé Aucun refus : la clé continue de fonctionner Vous la révoquez si vous le souhaitez. Oui
Compte du créateur bloqué par Lexio (même s'il a quitté l'équipe) 401 API_KEY_DISABLED Un gestionnaire des clés la réactive dans Paramètres > Développeur s'il lui fait confiance. Oui
Organisation supprimée 401 API_KEY_INVALID : la clé est supprimée avec elle — Non
Organisation suspendue 403 ORGANIZATION_SUSPENDED Vous régularisez votre abonnement. Oui
Plan inférieur à Business 403 FEATURE_NOT_AVAILABLE Un administrateur passe au plan Business. Oui
Scope manquant 403 INSUFFICIENT_SCOPE Vous créez une clé qui porte le scope. Non

Les clés ne permettent pas de gérer d'autres clés : créez, désactivez et révoquez-les depuis votre session Lexio. Une clé envoyée ailleurs qu'à l'API externe (par exemple aux adresses de l'application Lexio) est refusée.

Pour un incident, demandez à l'intégrateur l'identifiant requestId de la réponse en cause et communiquez-le au support, sans jamais joindre la clé.

Protéger et remplacer une clé

Ne placez jamais une clé dans le navigateur, une application distribuée, un dépôt Git ou des logs. Utilisez HTTPS et un stockage de secrets côté serveur.

Dans Paramètres > Développeur, désactivez une clé pour interrompre son usage ou choisissez Révoquer pour la retirer définitivement. Pour la remplacer sans coupure : créez une nouvelle clé avec les mêmes scopes, faites basculer l'intégration, attendez 24 heures (les reprises en cours restent liées à l'ancienne clé), vérifiez le fonctionnement puis révoquez l'ancienne. En cas de fuite, révoquez sans attendre.

Toujours bloqué ?

Décrivez la page, l'action effectuée et le message affiché : nous pourrons vous répondre plus vite.

Quelle est votre offre Lexio ?

Les guides vous signaleront ce qui n'est pas inclus dans votre offre, et les captures montreront vos écrans. Vous la trouvez dans Paramètres › Abonnement.