Démarrage rapide

De la recherche d'un véhicule à l'annulation, en cinq appels. Vous avez besoin d'une clé API (voir « Authentification et scopes »), d'une organisation au plan Business, d'un véhicule actif rattaché à une catégorie tarifaire avec prix, et des scopes offers.read, quotes.write, rentals.read et rentals.write.

Les dates sont calculées dans le shell (dans 30 jours, pour 5 jours) : elles restent futures. Remplacez <vehicle-uuid> par le data[].vehicle.id lu à l'étape 1, <quote-uuid> par le data.id lu à l'étape 2 et <rental-uuid> par le data.id lu à l'étape 3.

# 0. Clé API (Paramètres → Développeur) et adresse de base.
export LEXIO_KEY="lck_xxxxxxxxxxxxxxxxxxxxxxxx"
export LEXIO_API="https://api.lexio.rent/api/external/v1"
# Un numéro de commande unique par essai : une partnerReference déjà utilisée répond 409 ALREADY_EXISTS.
export REF="quickstart-$(date +%s)"
# Dates futures, date GNU puis BSD/macOS.
export START=$(date -d '+30 days' +%F 2>/dev/null || date -v+30d +%F)
export END=$(date -d '+35 days' +%F 2>/dev/null || date -v+35d +%F)

# 1. Véhicules réservables et prix (offers.read) ; lisez data[].vehicle.id
curl "$LEXIO_API/availability?startAt=${START}T10:00&endAt=${END}T10:00&isAvailable=true" \
  -H "Authorization: Bearer $LEXIO_KEY"

# 2. Devis au prix garanti 24 h (quotes.write) ; lisez data.id et data.totalTTC
curl -X POST "$LEXIO_API/quotes" \
  -H "Authorization: Bearer $LEXIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": "<vehicle-uuid>",
    "startAt": "'"$START"'T10:00",
    "endAt": "'"$END"'T10:00"
  }'

# 3. Créer la location au prix du devis (rentals.write) ; lisez data.id
curl -X POST "$LEXIO_API/rentals" \
  -H "Authorization: Bearer $LEXIO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "<quote-uuid>",
    "partnerReference": "'"$REF"'",
    "customer": {
      "firstName": "Marie",
      "lastName": "Durand",
      "email": "marie@example.com",
      "phone": "+33612345678"
    }
  }'

# 4. Relire la location (rentals.read) ; lisez data.totalTTC et data.balance
curl "$LEXIO_API/rentals/<rental-uuid>" -H "Authorization: Bearer $LEXIO_KEY"

# 5. Annuler avec un motif (rentals.write) ; lisez effects.cancellation
curl -X POST "$LEXIO_API/rentals/<rental-uuid>/cancel" \
  -H "Authorization: Bearer $LEXIO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Annulation du démarrage rapide" }'

Ce qu'il faut retenir :

• le devis fige le prix pendant 24 h mais ne réserve rien : la disponibilité est revérifiée à l'étape 3 (409 VEHICLE_UNAVAILABLE) et un devis ne se consomme qu'une fois ;
• si le prix recalculé s'écarte du devis, la création répond 409 PRICE_CHANGED et n'écrit rien : demandez un nouveau devis ;
• relancer l'étape 3 avec la même Idempotency-Key et le même corps renvoie la réponse d'origine (voir « Idempotence et reprise ») ;
• pour tester sans écrire, ajoutez ?dryRun=true à une action : la réponse est celle de l'appel réel, rien n'est enregistré ;
• il n'y a pas de bac à sable : testez sur une organisation de test du loueur, avec des dates futures, puis annulez.

Authentification et scopes

La clé API

L'API s'authentifie par clé API uniquement, sans connexion d'utilisateur. La clé commence par lck_ ; le loueur la crée dans Lexio (Paramètres → Développeur) et vous la transmet. Seul le propriétaire de l'organisation, ou un membre autorisé par le propriétaire à gérer les clés API, peut la créer.

La clé s'envoie dans un seul en-tête, jamais dans l'adresse :

Authorization: Bearer lck_xxxxxxxxxxxxx

L'API se consomme depuis votre serveur : elle n'émet aucun en-tête CORS et une clé ne doit jamais être embarquée dans une page web ni dans une application installée. Une clé envoyée à une autre adresse que l'API externe est refusée (403) : vérifiez que vous appelez bien la base de l'API externe indiquée dans la référence.

Appartenance et auteur des écritures

La clé appartient à l'organisation, pas à la personne qui l'a créée : elle continue de fonctionner si ce membre perd des droits ou quitte l'équipe. Les écritures faites avec la clé sont signées « API : nom de la clé » (suivi de l'identifiant partenaire entre parenthèses s'il existe) dans les notes, les paiements et le journal d'activité du loueur.

États de la clé

Toute réponse 401 porte WWW-Authenticate: Bearer realm="Lexio API", complété de error="invalid_token" dès qu'un en-tête Authorization a été envoyé.

Expiration et rotation

Une clé expire par défaut au bout de 365 jours. Pour la remplacer sans coupure : créez une seconde clé avec les mêmes scopes (et le même identifiant partenaire), basculez vos appels, attendez 24 h (durée de vie des Idempotency-Key, propres à chaque clé : un rejeu ne passe pas d'une clé à l'autre), puis faites révoquer l'ancienne.

Corrélation des requêtes

Chaque réponse porte X-Request-Id, repris dans le champ requestId des erreurs : communiquez-le au support. Vous pouvez fournir le vôtre dans X-Request-Id (8 à 128 caractères parmi A-Za-z0-9._:-) ; sinon le serveur en génère un.

Corps de requête

JSON UTF-8 de 1 Mio au plus, en application/json (application/merge-patch+json aussi sur PATCH). Au-delà, 413 ; autre type de contenu, 415 ; JSON illisible, 400. Les champs inconnus sont refusés (400).

Scopes

Un scope s'écrit <ressource>.<accès> : read couvre les lectures de la ressource et de ses sous-ressources, write les créations, modifications et actions, les droits sensibles ont leur scope propre. Une opération accepte l'un des scopes listés (OU logique). GET /organization s'ouvre à toute clé valide. Un scope se choisit à la création de la clé et ne se modifie pas.

offers.read et quotes.write permettent de chiffrer sans ouvrir le registre des locations.

Limites de débit

Quatre seaux protègent l'API. Une requête refusée répond 429 RATE_LIMITED, avec Retry-After (secondes) ; le corps indique le seau (limit), sa fenêtre (windowSeconds) et le délai (retryAfter).

• Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset décrivent le seul seau PER_KEY ; les autres seaux se signalent par le 429.
• Un rejeu d'Idempotency-Key ne consomme aucun seau d'écriture ni de devis, sauf sur la préparation et l'enregistrement de photos, rejoués par uploadId : chaque renvoi compte dans le seau WRITE. Une écriture refusée (4xx ou 5xx) rend son jeton du seau WRITE ; le seau QUOTE compte aussi les refus.
• ?dryRun=true compte dans le seau QUOTE, pas dans le seau d'écriture.
• Les compteurs sont tenus en mémoire par serveur et remis à zéro à chaque déploiement : les plafonds sont des maximums, pas des garanties de débit.
• Sur 429, attendez Retry-After puis rejouez la même requête avec la même Idempotency-Key.

Pagination

Toute liste utilise un curseur, partout :

{ "data": [ … ], "nextCursor": "eyJ…" }

• limit : 1 à 100, 50 par défaut. cursor : valeur opaque, à renvoyer telle quelle.
• nextCursor nul signifie la fin de la liste. Il n'y a ni page, ni offset, ni total.
• Les collections bornées (saisons, calendrier des saisons, paliers de délai, remises de durée, états des lieux, opérations et alertes d'entretien) ont la même enveloppe, avec nextCursor toujours nul ; elles n'acceptent ni limit ni cursor.
• Une page peut contenir moins d'éléments que limit, voire aucun : suivez nextCursor tant qu'il n'est pas nul (c'est le cas de GET /availability, qui tarife au plus 3 100 jours-véhicule par page).
• L'ordre par défaut est documenté sur chaque liste et total (le dernier critère est toujours id) ; il n'y a pas de paramètre de tri.
• Un curseur de liste n'expire pas ; il ne vaut que pour les filtres de la requête qui l'a émis (sinon 400 sur /cursor). Seul le curseur de GET /events expire, après 30 jours (410 CURSOR_EXPIRED) : voir « Synchronisation par événements ».

Filtres

• Le nom d'un filtre est celui du champ : status, vehicleId, customerId, categoryId, partnerReference, isActive, vehicleType.
• Plusieurs valeurs se séparent par des virgules, chacune validée contre l'énumération.
• from et to (YYYY-MM-DD, inclusifs, fuseau de l'agence) bornent une fenêtre de jours ; to antérieur à from répond 400.
• Un booléen s'écrit true ou false ; filtre omis, tous les éléments.
• Un paramètre inconnu répond 400.

Idempotence et reprise

Idempotency-Key

Une écriture réseau peut échouer après avoir réussi. Envoyez une Idempotency-Key pour la rejouer sans risque de doublon.

• Obligatoire sur toute écriture de location et de paiement (création, modification, suppression, annulation, départ, retour, report, changement de véhicule, de couverture ou de titulaire, options, paiements). Absente, elle répond 400. Acceptée sur toute autre écriture. Non exigée avec ?dryRun=true.
• Format : 1 à 255 caractères imprimables, un UUID par opération, réutilisé pour chacun de ses rejeux. Portée : votre clé API, la méthode, le chemin et la valeur de la clé. Durée : 24 h.
• Même clé, même corps : la réponse d'origine est rejouée à l'identique, avec l'en-tête Idempotent-Replayed: true. Exception : la préparation (POST /rentals/{rentalId}/photo-uploads) et l'enregistrement de photos (POST /rentals/{rentalId}/photos) ne sont jamais rejoués depuis la clé : un renvoi réexécute l'opération, et l'enregistrement se rejoue par uploadId.
• Même clé, corps différent : 422 IDEMPOTENCY_KEY_REUSED.
• Même clé, requête en cours : 409 IDEMPOTENCY_IN_FLIGHT avec Retry-After ; rejouez après le délai.
• Seul un succès (2xx) est rejoué. Après un échec avant écriture, la même clé réexécute l'opération : rien n'a été écrit.
• Écriture appliquée, réponse perdue : sur les opérations qui déclarent IDEMPOTENCY_ALREADY_APPLIED (création de location et de devis, actions sur une location, paiements, enregistrement d'un entretien, suppression d'une photo), une écriture faite dont la réponse a échoué (5xx) garde sa clé : un rejeu répond 409 IDEMPOTENCY_ALREADY_APPLIED avec resourceId, et l'en-tête Location quand la ressource se relit par un GET. Ne rejouez pas : relisez la ressource. Sur les autres écritures, la même clé réexécute l'opération après un 5xx : relisez la ressource avant de rejouer.

Quels codes rejouer

Votre numéro de commande

partnerReference est votre numéro de commande : unique par identifiant partenaire, il n'est pas un mécanisme de rejeu. Un doublon répond 409 ALREADY_EXISTS (field, conflictingId). Ne l'alimentez jamais avec un identifiant de paiement : une réservation a sa propre identité, indépendante du cycle de vie du paiement. Le rejeu sûr passe par Idempotency-Key.

Action déjà faite

Une action sur une location déjà dans l'état visé répond 409 RENTAL_STATUS_NOT_ALLOWED. L'annulation d'une location déjà annulée fait exception : elle répond 200 sans rien écrire, avec effects.cancellation.alreadyCancelled: true.

Aperçu avant écriture

?dryRun=true exécute l'action jusqu'au bout, puis l'annule : la réponse est identique à l'appel réel, y compris effects.priceChange et effects.overpayment, et rien n'est enregistré.

• Une action qui modifie le prix accepte expectedTotalTTC : si le total recalculé s'en écarte d'une unité mineure de la devise ou plus, elle répond 409 PRICE_CHANGED sans rien écrire. Sans expectedTotalTTC, l'action s'applique au prix courant.
• Une modification qui ferait passer le total sous le montant déjà encaissé exige overpaymentResolution (REFUND_PENDING ou NO_REFUND, scope payments.refund) ; sinon 409 OVERPAYMENT_RESOLUTION_REQUIRED. Une clé partenaire reçoit resolvableByKey: false : le loueur traite la baisse dans Lexio.

Synchronisation par événements

GET /events est le flux ordonné des changements de locations. Il remplace l'interrogation périodique des listes et ne demande aucun webhook.

GET /api/external/v1/events?cursor=…&limit=100&types=rental.created,rental.cancelled

{
  "data": [
    {
      "id": "4e1a…",
      "type": "rental.cancelled",
      "occurredAt": "2027-06-01T09:12:44+02:00",
      "resource": { "type": "RENTAL", "id": "9c2d…", "partnerReference": "LR-884213" }
    }
  ],
  "nextCursor": "…"
}

• Types : rental.created, rental.updated, rental.cancelled, rental.deleted. D'autres types pourront s'ajouter : ignorez ceux que vous ne connaissez pas.
• Les événements sont minces (type, instant, référence) : relisez la location par GET /rentals/{rentalId} pour obtenir son état. Une location supprimée ne se relit plus (404).
• Une création de location et de ses options produit un seul rental.created. L'ordre est total : un événement validé tard n'est jamais sauté.
• Scope rentals.read. Une clé partenaire ne voit que les événements de ses propres locations.

Boucle de synchronisation

1. Première lecture : sans paramètre (ou start=EARLIEST), le flux repart des événements des 29 derniers jours ; start=LATEST ne renvoie aucun événement mais le curseur d'aujourd'hui, pour ne suivre que ce qui suit. start et cursor s'excluent.
2. Traitez les événements d'une page, puis enregistrez son nextCursor. Le curseur est toujours renvoyé, même sur une page vide : rejouez-le tel quel.
3. Reprenez au curseur enregistré, à la cadence qui vous convient, en respectant les limites de débit.

Reprise après une longue absence

Les événements sont conservés 30 jours. Un curseur plus ancien répond 410 CURSOR_EXPIRED : resynchronisez en lisant d'abord GET /events?start=LATEST (enregistrez son curseur), puis parcourez GET /rentals page par page pour reconstruire l'état, et reprenez le flux au curseur enregistré. Rien de ce qui a changé pendant le parcours n'est perdu.

Versions et évolutions

La version majeure est dans l'adresse : /api/external/v1. La documentation décrit le contrat en vigueur ; son numéro (info.version) suit le versionnage sémantique, par exemple 1.0.0. La date de chaque changement figure dans le changelog publié de l'API.

Évolutions sans préavis

Elles ne cassent aucun client qui respecte ces règles : ignorez les champs de réponse que vous ne connaissez pas.

• nouvelle opération ;
• nouveau champ de réponse ;
• nouveau paramètre ou nouveau champ de requête facultatif ;
• nouveau code d'erreur (traitez un code inconnu selon son statut HTTP) ;
• nouveau type d'événement (voir « Synchronisation par événements »).

Nouvelle valeur d'une énumération en sortie

Elle est annoncée 30 jours avant. Tolérez une valeur inconnue : ne basez pas un switch sans branche par défaut sur une énumération de sortie.

Correctifs de contrat

Un correctif de sécurité, d'intégrité des données ou de bug, ou l'alignement de la référence sur le comportement réel, s'applique à la v1 sans préavis. Il est daté dans le changelog, avec la marche à suivre.

Évolutions cassantes

Hors correctif de contrat, elles ne paraissent que dans une nouvelle version majeure (v2), servie en parallèle. La v1 reste disponible 6 mois après l'annonce, et ses réponses portent les en-têtes Deprecation et Sunset.

Erreurs

Toute réponse 4xx ou 5xx est un objet RFC 9457 (application/problem+json). Le code est la référence stable, lisible par une machine ; title et detail sont rédigés en français et peuvent évoluer : ne les analysez pas.

{
  "type": "https://api.lexio.rent/errors/rental-busy",
  "title": "Location occupée",
  "status": 409,
  "code": "RENTAL_BUSY",
  "detail": "Une autre opération est en cours sur cette location.",
  "instance": "/api/external/v1/rentals/9c2d…/cancel",
  "requestId": "9b2d6c1e-4f3a-4e8b-a1d7-3c5e9f0a2b46"
}

• code : valeur d'une énumération fermée, la liste ci-dessous. Une opération ne répond que par les codes qu'elle déclare, plus un socle commun (clé, scope, abonnement, débit, erreur interne, validation).
• type : adresse stable du code, la même partout.
• Les membres supplémentaires d'un code (reasons, conflictingId, expectedTotalTTC…) sont typés et propres à ce code ; la colonne « Champs supplémentaires » les liste.
• errors[] accompagne les refus de validation : chaque élément porte un pointer (RFC 6901, /startAt, /options/0/optionId), un code stable et un detail.
• requestId : à communiquer au support. Il est aussi dans l'en-tête X-Request-Id.
• Retry-After (secondes) accompagne les codes rejouables (colonne « Retry-After » du catalogue). Un 500 n'en porte pas mais se rejoue aussi (voir le tableau) ; les autres codes ne se rejouent pas à l'identique.

Que faire selon le statut

Un même refus a le même statut et le même code sur toutes les routes.

Catalogue des codes

Intégration broker

Parcours d'une plateforme de réservation qui vend des véhicules de plusieurs loueurs Lexio.

Une clé par loueur

Une clé appartient à une seule organisation : il n'existe pas de clé multi-organisation. Chaque loueur crée la sienne (Paramètres → Développeur) et vous la transmet. Contrôlez-la avec GET /organization : devise, fuseau, TVA, horaires d'ouverture, règles de réservation et scopes de la clé.

Identifiant partenaire

Une clé peut porter un identifiant partenaire (partnerCode), fixé à sa création et non modifiable. Il cloisonne votre espace :

• vos locations, devis, fiches clients et événements portent ce code ; vous ne voyez jamais ceux du loueur ni d'un autre partenaire. Une location hors de votre périmètre répond 404, comme un identifiant inconnu ;
• partnerReference est unique par identifiant partenaire : deux partenaires peuvent utiliser la même référence sans collision ;
• un devis ne se consomme que par une clé du même identifiant partenaire ;
• le client est repris par son email (casse ignorée) parmi les fiches de votre espace, sinon une fiche est créée dans votre espace ; customerId n'est pas accepté en écriture. Un client bloqué chez le loueur fait répondre 409 BOOKING_REFUSED, sans cause ;
• les créneaux occupés par d'autres locations ne sont montrés que comme plages anonymes.

Scopes accordables à une clé partenaire : catalog.read, offers.read, quotes.write, rentals.read, rentals.write et payments.write (limité aux paiements Stripe). Les autres sont refusés à la création de la clé.

Parcours de réservation

1. GET /availability : véhicules réservables et prix pour la période, selon les règles de réservation du loueur (422 BOOKING_RULE_VIOLATION). Prix et disponibilité ne sont pas garantis.
2. POST /quotes : prix garanti 24 h (expiresAt), consommable une seule fois. Le devis ne réserve rien.
3. POST /rentals avec quoteId, votre numéro de commande en partnerReference et une Idempotency-Key. La disponibilité est revérifiée (409 VEHICLE_UNAVAILABLE) ; si le prix recalculé s'écarte du devis, 409 PRICE_CHANGED et rien n'est créé.
4. Lisez le total TTC dans totalTTC et le reste à payer dans balance de la location.

Votre numéro de commande est la référence de la réservation : n'y mettez pas un identifiant de paiement. Pour retrouver une location : GET /rentals?partnerReference=… ou GET /rentals?number=… (numéro Lexio).

Paiement

Enregistrez un paiement par POST /rentals/{rentalId}/payments. Une clé partenaire n'enregistre que des paiements Stripe, par leur identifiant de paiement ; les remboursements sont réservés au loueur. Si une modification fait passer le total sous le montant encaissé, la réponse est 409 OVERPAYMENT_RESOLUTION_REQUIRED avec resolvableByKey: false : le loueur traite la baisse dans Lexio.

Suivi, modification, annulation

• Suivez les changements par GET /events puis relisez la location (voir « Synchronisation par événements »). Il n'y a pas de webhook.
• Annulez par POST /rentals/{rentalId}/cancel avec un reason, pas par DELETE. Une location déjà annulée répond 200 sans effet. effects.cancellation donne les avoirs émis et le remboursement dû.
• Changez la période par reschedule et le véhicule par change-vehicle : aperçu avec ?dryRun=true, puis appel réel avec expectedTotalTTC égal au total de l'aperçu (voir « Idempotence et reprise »).
• PATCH /rentals/{rentalId} ne modifie que les notes et les lieux.

Effets sur le client final

Une clé partenaire n'envoie jamais d'email de confirmation au client final. Le loueur est alerté de chaque création.

Pas de bac à sable

Testez sur une organisation de test du loueur, avec des dates futures, puis annulez.

Rotation de clé

Voir « Authentification et scopes » : deux clés actives avec le même identifiant partenaire pendant la bascule. Vos références, devis, clients et événements sont liés à l'identifiant partenaire, pas à la clé.

Ce qui se gère dans Lexio

Principe : tout ce qui bloque une action de l'API est lisible par l'API (la cause figure dans l'erreur et la ressource est consultable), et modifiable par l'API, sauf les exceptions ci-dessous. Elles se gèrent dans l'application Lexio, par le loueur.

Exceptions publiées

• Langue. La documentation, les title et les detail des erreurs sont en français. Les contrats lisibles par machine (code, errors[].code, énumérations, type) sont stables et indépendants de la langue ; il n'y a pas de négociation Accept-Language.
• Calendrier des saisons. Le calendrier des saisons est un gabarit annuel, par mois et par jour, sans année : il s'applique à toutes les années. Une hausse ponctuelle ou une fête mobile (Pâques, par exemple) ne se représente pas par date : maintenez-la côté intégrateur en modifiant puis en rétablissant le calendrier, ou faites-la gérer par le loueur.