Lexio Événements API

openapi: 3.2.0
info:
  title: Lexio Événements API
  version: 1.0.5
  description: '# API Lexio v1


    L’API Lexio permet à un loueur de véhicules, ou à une plateforme partenaire autorisée par lui, d’obtenir des prix, réserver, suivre et administrer ses locations depuis un serveur. Chaque appel agit sur l’organisation Lexio d’un seul loueur.


    - **Adresse de base** : `https://api.lexio.rent/api/external/v1`

    - **Authentification** : `Authorization: Bearer lck_…`, une clé créée par le loueur dans Lexio.

    - **Format** : JSON en UTF-8 ; erreurs RFC 9457 avec un `code` stable.

    - Réponses : `{ "data" }` ; listes `{ "data", "nextCursor" }` (Pagination) ; actions `{ "data", "effects" }`, `effects` décrivant ce que l’appel a déclenché (détaillé dans la référence).

    - Dates : `startAt` et `endAt` en heure locale du loueur (`timezone`), sans décalage (`2026-11-28T10:00`, sinon `400 offset_not_allowed`) ; les réponses les rendent avec décalage, retirez-le avant de les renvoyer. Instants réels (`actualStartAt`, `actualEndAt`, `paidAt`, `takenAt`, `effectiveAt`) en RFC 3339 avec décalage (sinon `400 offset_required`).

    - `PATCH` : champ omis inchangé, `null` efface ; un objet imbriqué est remplacé en entier, sauf s’il est dit « fusionné » sur l’opération.

    - Corps de 1 Mio au plus, en `application/json` (`application/merge-patch+json` aussi sur `PATCH`). Trop gros : `413` ; autre type : `415` ; JSON illisible : `400` ; champ inconnu : `400` (dans une réponse, ignorez-le : Versions et évolutions).

    - Chaque réponse porte `X-Request-Id`, repris dans `requestId` des erreurs. Vous pouvez fournir le vôtre (8 à 128 caractères parmi `A-Za-z0-9._:-`), sinon le serveur en génère un. Joignez-le à toute demande à contact@lexio.rent.

    - **Spécification OpenAPI 3.1** : https://docs.lexio.rent/openapi.json, à importer dans votre client HTTP ou à utiliser pour générer un client.

    - **Contact** (support technique, demande d’accès, organisation de démonstration) : contact@lexio.rent.


    Vocabulaire : le **loueur** est l’entreprise de location, son **organisation** est son compte Lexio ; une **location** (`/rentals`) est un contrat de location d’un véhicule ; un **lieu** (`/locations`) est une adresse de départ ou de retour (le type `AGENCY` n’est qu’un type de lieu, pas le loueur).'
  contact:
    name: Support Lexio
    email: contact@lexio.rent
    url: https://docs.lexio.rent
servers:
- url: https://api.lexio.rent/api/external/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Événements
  description: Flux des changements à relire pour synchroniser votre système, sans webhook.
paths:
  /events:
    get:
      operationId: listEvents
      summary: Lister les changements des locations
      description: '**Accès** : `rentals.read`


        Flux ordonné des changements de locations : `rental.created`, `rental.updated`, `rental.cancelled` et `rental.deleted`. Les événements sont minces : relisez la location par `GET /rentals/{rentalId}`. Une clé partenaire ne reçoit que ceux de ses locations.


        **Lecture** : sans `cursor`, le flux part des 29 derniers jours (`start=EARLIEST`) ou du moment présent (`start=LATEST`). Traitez les événements dans l’ordre de la page, puis reprenez au `nextCursor` tel quel : sur ce flux, il n’est jamais nul, même sur une page vide.


        **Refus** : curseur de plus de 30 jours → 410 `CURSOR_EXPIRED`, voir Synchronisation.'
      tags:
      - Événements
      security:
      - ApiKey: []
      x-required-scopes:
      - rentals.read
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Taille de la page, de 1 à 100 ; 50 par défaut.
      - in: query
        name: cursor
        schema:
          type: string
          minLength: 1
          maxLength: 4096
        description: Valeur `nextCursor` de la page précédente ; omis pour la première page.
      - in: query
        name: start
        schema:
          description: 'Point de départ sans `cursor` : `EARLIEST` (défaut) repart des événements des 29 derniers jours ; `LATEST` ne renvoie aucun événement, seulement le curseur du moment. Exclusif avec `cursor`.'
          type: string
          enum:
          - EARLIEST
          - LATEST
        description: 'Point de départ sans `cursor` : `EARLIEST` (défaut) repart des événements des 29 derniers jours ; `LATEST` ne renvoie aucun événement, seulement le curseur du moment. Exclusif avec `cursor`.'
      - in: query
        name: types
        schema:
          type: string
        description: 'Valeurs séparées par des virgules parmi : rental.created, rental.updated, rental.cancelled, rental.deleted.'
      responses:
        '200':
          description: Une page de résultats.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    maxItems: 100
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  nextCursor:
                    type: string
                    minLength: 1
                    description: Position à reprendre telle quelle au prochain appel ; jamais nulle, même sur une page vide ; expire après 30 jours. Voir [Synchronisation](https://docs.lexio.rent/synchronisation).
                    examples:
                    - eyJpZCI6IjljMmQ3ZTRhIn0
                required:
                - data
                - nextCursor
        '400':
          description: '`VALIDATION_FAILED`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationFailedProblem'
        '401':
          description: '`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_INVALID`, `API_KEY_MISSING`, `API_KEY_REVOKED`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            WWW-Authenticate:
              $ref: '#/components/headers/WwwAuthenticate'
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApiKeyDisabledProblem'
                - $ref: '#/components/schemas/ApiKeyExpiredProblem'
                - $ref: '#/components/schemas/ApiKeyInvalidProblem'
                - $ref: '#/components/schemas/ApiKeyMissingProblem'
                - $ref: '#/components/schemas/ApiKeyRevokedProblem'
        '403':
          description: '`FEATURE_NOT_AVAILABLE`, `INSUFFICIENT_SCOPE`, `ORGANIZATION_SUSPENDED`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FeatureNotAvailableProblem'
                - $ref: '#/components/schemas/InsufficientScopeProblem'
                - $ref: '#/components/schemas/OrganizationSuspendedProblem'
        '410':
          description: '`CURSOR_EXPIRED`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CursorExpiredProblem'
        '429':
          description: '`RATE_LIMITED`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/RateLimitedProblem'
        '500':
          description: '`INTERNAL_ERROR`'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalErrorProblem'
      x-mint:
        href: /api-reference/evenements/list-events
        metadata:
          title: Lister les changements des locations
          sidebarTitle: Lister les changements des locations
components:
  schemas:
    InsufficientScopeProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/insufficient-scope
        title:
          type: string
          examples:
          - Scope insuffisant
        status:
          type: number
          const: 403
        code:
          type: string
          const: INSUFFICIENT_SCOPE
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
        requiredScopes:
          minItems: 1
          maxItems: 20
          type: array
          items:
            type: string
            enum:
            - offers.read
            - quotes.write
            - rentals.read
            - rentals.write
            - rentals.operate
            - rentals.delete
            - payments.write
            - payments.refund
            - customers.read
            - customers.write
            - customers.delete
            - vehicles.read
            - vehicles.write
            - vehicles.delete
            - catalog.read
            - catalog.write
            - pricing.read
            - pricing.write
            - maintenance.read
            - maintenance.write
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
      - requiredScopes
    OrganizationSuspendedProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/organization-suspended
        title:
          type: string
          examples:
          - Organisation suspendue
        status:
          type: number
          const: 403
        code:
          type: string
          const: ORGANIZATION_SUSPENDED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    ApiKeyInvalidProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/api-key-invalid
        title:
          type: string
          examples:
          - Clé API invalide
        status:
          type: number
          const: 401
        code:
          type: string
          const: API_KEY_INVALID
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    CursorExpiredProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/cursor-expired
        title:
          type: string
          examples:
          - Curseur expiré
        status:
          type: number
          const: 410
        code:
          type: string
          const: CURSOR_EXPIRED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    ApiKeyMissingProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/api-key-missing
        title:
          type: string
          examples:
          - Clé API absente
        status:
          type: number
          const: 401
        code:
          type: string
          const: API_KEY_MISSING
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    ApiKeyRevokedProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/api-key-revoked
        title:
          type: string
          examples:
          - Clé API révoquée
        status:
          type: number
          const: 401
        code:
          type: string
          const: API_KEY_REVOKED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    ValidationFailedProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/validation-failed
        title:
          type: string
          examples:
          - Requête invalide
        status:
          type: number
          const: 400
        code:
          type: string
          const: VALIDATION_FAILED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
        errors:
          minItems: 1
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
              code:
                type: string
                enum:
                - required
                - invalid_type
                - invalid_format
                - invalid_value
                - too_small
                - too_big
                - too_many_decimals
                - out_of_range
                - unknown_field
                - null_not_allowed
                - empty_string
                - empty_patch
                - mutually_exclusive
                - not_applicable
                - duplicate
                - end_before_start
                - date_in_past
                - nonexistent_local_time
                - offset_not_allowed
                - offset_required
                - upload_expired
                - upload_incomplete
                - upload_conflict
              detail:
                type: string
            required:
            - pointer
            - code
            - detail
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
      - errors
    InternalErrorProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/internal-error
        title:
          type: string
          examples:
          - Erreur interne
        status:
          type: number
          const: 500
        code:
          type: string
          const: INTERNAL_ERROR
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    ApiKeyExpiredProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/api-key-expired
        title:
          type: string
          examples:
          - Clé API expirée
        status:
          type: number
          const: 401
        code:
          type: string
          const: API_KEY_EXPIRED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Identifiant de l’événement.
        type:
          type: string
          enum:
          - rental.created
          - rental.updated
          - rental.cancelled
          - rental.deleted
          description: '`rental.created` : location créée ; `rental.updated` : location modifiée (statut, dates, véhicule, prix, options, paiements, lieux, notes…) ; `rental.cancelled` : location annulée ; `rental.deleted` : location supprimée.'
        occurredAt:
          type: string
          format: date-time
          examples:
          - '2027-11-10T10:00:00+01:00'
          description: Instant du changement. L’ordre du flux est celui de la page, pas cet instant.
        resource:
          type: object
          properties:
            type:
              type: string
              const: RENTAL
              description: Type de la ressource concernée.
            id:
              type: string
              format: uuid
              examples:
              - 9c2d7e4a-5b1f-4d3c-8a6e-0f1b2c3d4e5f
              description: Identifiant de la location (`rentalId`).
            partnerReference:
              description: Numéro de commande du partenaire ; null si absent.
              type:
              - string
              - 'null'
          required:
          - type
          - id
          - partnerReference
          description: Location concernée, à relire par `GET /rentals/{rentalId}`.
      required:
      - id
      - type
      - occurredAt
      - resource
      description: Changement d’une location ; relisez-la pour obtenir son état.
      examples:
      - id: 4e1a6b2c-9d3e-4f5a-8b7c-6d5e4f3a2b1c
        type: rental.updated
        occurredAt: '2027-11-10T10:12:31+01:00'
        resource:
          type: RENTAL
          id: 9c2d7e4a-5b1f-4d3c-8a6e-0f1b2c3d4e5f
          partnerReference: AV-884213
    ApiKeyDisabledProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/api-key-disabled
        title:
          type: string
          examples:
          - Clé API désactivée
        status:
          type: number
          const: 401
        code:
          type: string
          const: API_KEY_DISABLED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
    FeatureNotAvailableProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/feature-not-available
        title:
          type: string
          examples:
          - Fonctionnalité non incluse
        status:
          type: number
          const: 403
        code:
          type: string
          const: FEATURE_NOT_AVAILABLE
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
        feature:
          type: string
          minLength: 1
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
      - feature
    RateLimitedProblem:
      type: object
      properties:
        type:
          type: string
          const: https://api.lexio.rent/errors/rate-limited
        title:
          type: string
          examples:
          - Trop de requêtes
        status:
          type: number
          const: 429
        code:
          type: string
          const: RATE_LIMITED
        detail:
          type: string
          examples:
          - Explication lisible, propre à cette requête.
        instance:
          type: string
          examples:
          - /api/external/v1/rentals
        requestId:
          type: string
          examples:
          - 5b0e2a1c-8f3d-4c7e-9a6b-1d2e3f4a5b6c
        limit:
          type: string
          enum:
          - PRE_AUTH
          - PER_KEY
          - WRITE
          - QUOTE
        windowSeconds:
          type: integer
          minimum: 1
        retryAfter:
          type: integer
          minimum: 0
      required:
      - type
      - title
      - status
      - code
      - detail
      - instance
      - requestId
      - limit
      - windowSeconds
      - retryAfter
  headers:
    RateLimitReset:
      description: Secondes avant la remise à zéro du compteur `PER_KEY`.
      schema:
        type: integer
        minimum: 0
    RetryAfter:
      description: Secondes à attendre avant de renvoyer la requête ; présent seulement avec `IDEMPOTENCY_IN_FLIGHT`, `RENTAL_BUSY`, `RATE_LIMITED` et `SERVICE_UNAVAILABLE`.
      schema:
        type: integer
        minimum: 0
    XRequestId:
      description: Identifiant de la requête, à communiquer au support.
      schema:
        type: string
    WwwAuthenticate:
      description: Schéma d’authentification attendu (`Bearer`), avec `error="invalid_token"` pour une clé refusée.
      schema:
        type: string
    RateLimitRemaining:
      description: Requêtes encore permises sur le compteur `PER_KEY` dans la fenêtre en cours.
      schema:
        type: integer
        minimum: 0
    RateLimitLimit:
      description: 'Plafond du compteur `PER_KEY` de la clé (requêtes par minute). Les compteurs `WRITE` et `QUOTE` ne se signalent que par un `429` : voir [Limites de débit](https://docs.lexio.rent/limites).'
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: lck_…
      description: 'Clé API `lck_…` créée dans Lexio (Paramètres → Développeur), envoyée en `Authorization: Bearer`. Voir [Authentification](https://docs.lexio.rent/authentification).'