openapi.yaml

openapi: 3.1.0
servers:
  - url: https://{environment}.ciklik.co/api/v3
    description: Serveur API
    variables:
      environment:
        default: app
        enum:
          - app # URL de Production
          - demonstration # URL de Test/Démonstration
info:
  title: Ciklik API
  version: 1.0.0
  description: "# Bienvenue sur l'API Ciklik. Vous pouvez l'utiliser pour accéder aux ressources de votre compte, ou lancer des actions de base.\n## API Endpoints\nThe base endpoint is https://{environment}.ciklik.co/api/v3\n## Authentification\nL'API s'authentifie par un jeton d'API Ciklik (jeton opaque, ce n'est pas un JWT) envoyé dans l'en-tête `Authorization: Bearer`.\n\nExemple :\n  ```curl\n  curl --location 'https://{environment}.ciklik.co/api/v3/whoiam' --header 'Authorization: Bearer <Ciklik Token>'\n  ```\n\nUne requête sans jeton ou avec un jeton invalide reçoit `401` ; un jeton valide qui n'a pas accès à la ressource reçoit `403`.\n## Request Limit\nLe nombre de requêtes est limité à 200 par minute, compté par adresse IP (toutes les requêtes émises depuis la même adresse IP partagent ce quota). Si la limite est atteinte, la réponse http sera `429 Too Many Requests`.\n## Filtres\nCertains endpoints de l'API prennent en charge le filtrage des résultats sur un ensemble spécifié de champs. Chaque endpoint qui prend en charge le filtrage énumérera les champs qui peuvent être filtrés. Plusieurs champs peuvent être combinés en utilisant un caractère esperluette &\n\nExemple: `/subscriptions?filter[activated]=1&filter[created_at_after]=2026-01-01&sort=-created_at`\n\nUn filtre ou un tri qui n'est pas dans la liste de l'endpoint est refusé avec une réponse `400 Bad Request` (les endpoints qui valident eux-mêmes le paramètre `sort` répondent `422` pour un tri hors liste). Une valeur de filtre au mauvais format peut être refusée en `422`.\n## Pagination\nLes listes de résultats de l'API sont paginées. La pagination est fixe : 20 éléments par page, quelle que soit la valeur d'un éventuel paramètre `per_page` (ignoré). Vous pouvez obtenir les différentes pages avec la query string `page`, default value `1`.\n\nLe nombre total d'éléments dans une liste est disponible dans le champ `meta.total`.\n\nExemple: `?page=2`\n"

tags:
  - name: tenant
    description: Opérations liées à l'entité "Website".
  - name: products
    description: Opérations liées aux produits
  - name: webhooks
    description: Opérations liées aux webhooks
  - name: subscriptions
    description: Opérations liées aux abonnements
  - name: deliveries
    description: Opérations liées aux bons de livraison
  - name: kpis
    description: Opérations liées aux indicateurs de performance
  - name: addresses
    description: Opérations liées aux adresses
  - name: customers
    description: Opérations liées aux comptes utilisateurs
  - name: transactions
    description: Opérations liées aux transactions
  - name: rebill-errors
    description: Opérations liées aux erreurs de rebill
  - name: orders
    description: Opérations liées aux commandes
paths:
  /whoiam:
    get:
      summary: Récupérer les données de l'entité "Website"
      description: Renvoie le site du jeton, enveloppé dans `data`. Le champ `metadata` contient toutes les clés de métadonnées du site, y compris celles qui n'ont pas été posées par l'API.
      tags:
        - tenant
      security:
        - bearerAuth: []
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteEntity"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
    put:
      summary: Mettre à jour les métadonnées d'un site web (WebsiteEntity)
      description: Permet de mettre à jour les métadonnées d'un site web (WebsiteEntity) en modifiant ou ajoutant des clés/valeurs au champ "metadata". Les clés envoyées sont fusionnées avec les métadonnées existantes ; les clés absentes du corps sont conservées (elles ne sont pas effacées). La réponse renvoie le site complet, enveloppé dans `data`.
      tags:
        - tenant
      security:
        - bearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties:
                    type: [string, "null"]
                    maxLength: 5000
                  description: |
                    Métadonnées personnalisées. Les valeurs doivent être des chaînes de caractères (max 5000 caractères) ou null.
                    Seules les clés envoyées sont modifiées, les autres clés du site sont conservées.
                    Les clés commençant par "ciklik_encrypted_" seront automatiquement encryptées.
              example:
                metadata:
                  key1: "value1"
                  key2: "value2"
                  ciklik_encrypted_key2: "value-encrypted"
      responses:
        200:
          description: Succès - Les métadonnées ont été mises à jour avec succès.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteEntity"
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
  /installation:
    get:
      operationId: getInstallation
      summary: Récupérer l'état d'installation de l'espace
      description: |
        Route destinée au back-office du module PrestaShop : elle renvoie l'état d'installation de l'espace du jeton (espace de test ou de production, étapes franchies, ce qui reste à faire et adresse de la page de suivi d'installation).
        Les libellés sont traduits dans la langue de la requête. L'état est lu tel qu'il a été relevé lors des dernières vérifications : aucune vérification n'est lancée pendant la requête.
      tags:
        - tenant
      security:
        - bearerAuth: [ ]
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/InstallationState"
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        429:
          $ref: '#/components/responses/TooManyRequests'
  /products:
    get:
      summary: Récupérer une liste de produits
      tags:
        - products
      security:
        - bearerAuth: [ ]
      parameters:
        - name: filter[id]
          in: query
          description: Filtrer par ID du produit
          schema:
            type: integer
          example: 1
        - name: filter[name]
          in: query
          description: Filtrer par nom du produit
          schema:
            type: string
          example: "Produit exemple"
        - name: filter[id_category]
          in: query
          description: Filtrer par ID de catégorie
          schema:
            type: integer
          example: 5
        - name: filter[quantity]
          in: query
          description: Filtrer par quantité
          schema:
            type: integer
          example: 10
        - name: filter[price]
          in: query
          description: Filtrer par prix
          schema:
            type: number
          example: 29.99
        - name: filter[active]
          in: query
          description: Filtrer par état d'activité
          schema:
            type: boolean
          example: true
        - name: filter[slug]
          in: query
          description: Filtrer par slug
          schema:
            type: string
          example: "produit-exemple"
        - name: filter[virtual_product]
          in: query
          description: Filtrer par produit virtuel (correspondance exacte)
          schema:
            type: boolean
        - name: filter[salable]
          in: query
          description: Filtrer par produit vendable
          schema:
            type: boolean
        - name: filter[gift_card]
          in: query
          description: Filtrer par carte cadeau
          schema:
            type: boolean
        - name: filter[gift_plan]
          in: query
          description: Filtrer par plan cadeau (UUID du plan, correspondance partielle)
          schema:
            type: string
        - name: filter[disable_seo]
          in: query
          description: Filtrer par désactivation SEO (correspondance exacte)
          schema:
            type: boolean
        - name: filter[ref]
          in: query
          description: Filtrer par référence
          schema:
            type: string
        - name: filter[composable]
          in: query
          description: Filtrer par composable
          schema:
            type: boolean
        - name: sort
          in: query
          description: "Trier les résultats (ex: -name pour un tri descendant). Tri par défaut : `-id` (plus récent en premier)."
          schema:
            type: string
            enum:
              - id
              - name
              - id_category
              - quantity
              - price
              - active
              - slug
              - virtual_product
              - salable
              - gift_card
              - gift_plan
              - disable_seo
              - ref
              - composable
              - created_at
              - updated_at
              - -id
              - -name
              - -id_category
              - -quantity
              - -price
              - -active
              - -slug
              - -virtual_product
              - -salable
              - -gift_card
              - -gift_plan
              - -disable_seo
              - -ref
              - -composable
              - -created_at
              - -updated_at
        - name: page
          in: query
          description: Numéro de la page pour la pagination
          schema:
            type: integer
        - name: per_page
          in: query
          description: Ignoré. La pagination est fixe à 20 éléments par page.
          schema:
            type: integer
      responses:
        200:
          description: Liste de produits récupérée avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProductEntity"
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: "#/components/schemas/PaginationMeta"
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        429:
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Créer ou mettre à jour un produit
      description: |
        Crée le produit, ou le met à jour s'il existe déjà. Le produit est cherché par `external_id` s'il est fourni, sinon par `ref`.

        Deux formes de corps sont acceptées :
        - un produit seul (champs à la racine) : la réponse contient le produit dans `data`, avec le statut `201` s'il vient d'être créé et `200` s'il a été mis à jour ;
        - un lot `{"products": [...]}` : chaque élément suit le schéma d'un produit seul, la réponse contient la liste des produits dans `data` avec le statut `200`.

        À chaque enregistrement par cette route, le `slug` du produit est remplacé par un identifiant aléatoire (la valeur envoyée est ignorée) et `meta_title` reprend `name`.
        Si `description` est absente, un produit existant garde la sienne et un nouveau produit en reçoit une vide.
      tags:
        - products
      security:
        - bearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ProductEntityCreation"
                - type: object
                  description: Création ou mise à jour en lot
                  required:
                    - products
                  properties:
                    products:
                      type: array
                      items:
                        $ref: "#/components/schemas/ProductEntityCreation"
      responses:
        200:
          description: Produit mis à jour (corps unitaire), ou lot traité (corps `products`, `data` est alors une liste)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                      - $ref: "#/components/schemas/ProductEntity"
                      - type: array
                        items:
                          $ref: "#/components/schemas/ProductEntity"
        201:
          description: Produit créé (corps unitaire uniquement)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/ProductEntity"
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
  /products/{ref}:
    get:
      summary: Récupérer un produit par référence (SKU)
      tags:
        - products
      security:
        - bearerAuth: [ ]
      parameters:
        - name: ref
          in: path
          description: Référence du produit (SKU)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Produit récupéré avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/ProductEntity"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        404:
          description: Produit non trouvé
        429:
          $ref: '#/components/responses/TooManyRequests'
    patch:
      summary: Mettre à jour un produit par référence (SKU)
      description: |
        Met à jour le produit dont la référence est dans le chemin. Si `external_id` est fourni dans le corps, le produit est cherché par `external_id` et la référence du chemin est ignorée.
        `name`, `ref` et `price` sont obligatoires, même pour une mise à jour partielle.
      tags:
        - products
      security:
        - bearerAuth: [ ]
      parameters:
        - name: ref
          in: path
          description: Référence du produit (SKU)
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductEntityUpdate"
      responses:
        200:
          description: Produit mis à jour avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/ProductEntity"
        404:
          description: Produit non trouvé (par référence du chemin, ou par `external_id` s'il est fourni)
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
  /webhooks:
    get:
      summary: Lister les derniers webhooks envoyés
      description: Renvoie les trois derniers webhooks envoyés pour cet évènement, du plus récent au plus ancien. Chaque élément est la charge utile (payload) envoyée. Un `event_type` absent ou inconnu répond 404.
      tags:
        - webhooks
      security:
        - bearerAuth: [ ]
      parameters:
        - name: event_type
          in: query
          description: Nom de l'évènement à avoir
          required: true
          schema:
            type: string
            enum:
              - created_subscription
              - updated_subscription
              - deleted_subscription
              - created_checkoutorder
              - updated_checkoutorder
              - created_checkouttransaction
              - updated_checkouttransaction
              - created_checkoutinvoice
              - created_address
              - updated_address
              - created_shippingbox
              - updated_shippingbox
              - deleted_shippingbox
              - created_user
              - updated_user
              - deleted_user
              - created_optin
              - updated_optin
      responses:
        200:
          description: Les trois derniers webhooks envoyés pour cet évènement (liste vide si aucun)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Charges utiles envoyées, de la plus récente à la plus ancienne
                    items:
                      type: object
                      additionalProperties: true
        404:
          description: Paramètre `event_type` absent ou nom d'évènement inconnu
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Ajouter un webhook
      description: |
        Enregistre l'adresse appelée pour un type d'évènement. Il n'y a qu'une adresse par type d'évènement : un nouvel enregistrement remplace l'adresse précédente pour ce type, y compris celle posée par le module PrestaShop.
        La réponse renvoie le site, enveloppé dans `data`, avec la liste des webhooks actifs.
      tags:
        - webhooks
      security:
        - bearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event_type:
                  type: string
                  enum:
                    - created_subscription
                    - updated_subscription
                    - deleted_subscription
                    - created_checkoutorder
                    - updated_checkoutorder
                    - created_checkouttransaction
                    - updated_checkouttransaction
                    - created_checkoutinvoice
                    - created_address
                    - updated_address
                    - created_shippingbox
                    - updated_shippingbox
                    - deleted_shippingbox
                    - created_user
                    - updated_user
                    - deleted_user
                    - created_optin
                    - updated_optin
                hook_url:
                  type: string
                  format: uri
                  description: URL http ou https publique, joignable depuis internet. Les adresses internes, privées ou réservées (localhost, 10.x, 192.168.x, 169.254.x...) sont refusées en 422.
              required:
                - hook_url
                - event_type
      responses:
        200:
          description: Webhook ajouté avec succès (site enveloppé dans `data`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteEntity"
        422:
          description: Erreur de validation (`event_type` inconnu, `hook_url` absente, mal formée ou non publique)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Supprimer un webhook
      description: Retire l'adresse enregistrée pour ce type d'évènement. La réponse renvoie le site, enveloppé dans `data`.
      tags:
        - webhooks
      security:
        - bearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event_type:
                  type: string
                  enum:
                    - created_subscription
                    - updated_subscription
                    - deleted_subscription
                    - created_checkoutorder
                    - updated_checkoutorder
                    - created_checkouttransaction
                    - updated_checkouttransaction
                    - created_checkoutinvoice
                    - created_address
                    - updated_address
                    - created_shippingbox
                    - updated_shippingbox
                    - deleted_shippingbox
                    - created_user
                    - updated_user
                    - deleted_user
                    - created_optin
                    - updated_optin
              required:
                - event_type
      responses:
        200:
          description: Webhook supprimé avec succès
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebsiteEntity"
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
  /subscriptions/{id}:
    get:
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Obtenir les détails d'un abonnement
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement
          required: true
          schema:
            type: string
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        404:
          description: Abonnement introuvable
        429:
          $ref: '#/components/responses/TooManyRequests'
    put:
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Mettre à jour un abonnement
      description: |
        Permet de mettre à jour un abonnement, le résilier, le mettre en pause pour 1, 2 ou 3 mois, ou le relancer.
        L'adresse (`address_id`), le transporteur (`transporter`) et la déclinaison (`declinaison_id`) sont contrôlés avant toute écriture : une référence inconnue ou qui n'appartient pas au site répond 404 et l'abonnement n'est pas modifié.
        Les autres refus (422 sur `content` ou `next_billing`, par exemple) peuvent intervenir après l'application des changements qui les précèdent : n'envoyez qu'un changement par requête si vous avez besoin d'un résultat tout ou rien.
        La réponse renvoie l'abonnement relu après les modifications, enveloppé dans `data`.
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement à mettre à jour
          required: true
          schema:
            type: string
      requestBody:
        description: Données à modifier sur l'abonnement
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address_id:
                  type: integer
                  description: ID d'une adresse du site à affecter à l'abonnement (404 si elle n'appartient pas au site).
                declinaison_id:
                  type: integer
                  description: ID d'une déclinaison du site à affecter à l'abonnement (404 si elle n'appartient pas au site).
                transporter:
                  type: integer
                  description: ID d'un transporteur du site (404 s'il n'appartient pas au site). Peut être accompagné d'un objet `relay` décrivant le point relais choisi.
                relay:
                  type: object
                  additionalProperties: true
                  description: Point relais, lu uniquement avec `transporter`.
                voucher:
                  type: boolean
                  description: Si vrai, applique l'offre de rétention (bon de réduction) proposée au désabonnement.
                break:
                  type: boolean
                  description: Accepté par la validation, sans effet (la mise en pause passe par `pause` et `months`).
                months:
                  type: number
                  format: float
                  minimum: 1
                  maximum: 3
                  description: Nombre de mois pour mettre en pause l'abonnement (1, 2 ou 3 mois) (!= résiliation). Obligatoire si `pause` vaut true.
                active:
                  type: boolean
                  description: Indique si l'abonnement est actif.
                notification:
                  type: boolean
                  description: Lors de la résiliation d'un abonnement, notifier ou non par email.
                  default: true
                pause:
                  type: boolean
                  description: Indique si l'abonnement doit être mis en pause.
                next_billing:
                  type: string
                  format: date
                  description: Modifier la date du prochain paiement (date postérieure à aujourd'hui). Refusé en 422 si une commande du cycle est en attente avec une relance programmée.
                content:
                  type: array
                  description: nouveau contenu de l'abonnement, via external_id
                  items:
                    type: object
                    required:
                      - external_id
                      - quantity
                      - interval
                      - interval_count
                    properties:
                      external_id:
                        type: [string, integer]
                        maxLength: 255
                        description: Identifiant externe du produit, chaîne ou entier (255 caractères max). Les identifiants PrestaShop au format `produit:déclinaison` sont acceptés.
                      quantity:
                        type: integer
                        minimum: 1
                        description: Quantité du produit
                      interval:
                        type: string
                        description: Intervalle de renouvellement (`month`, `week` ou `day` attendus ; la valeur n'est pas contrôlée)
                      interval_count:
                        type: integer
                        minimum: 1
                        description: Nombre d'intervalles
                    example:
                      external_id: "123"
                      quantity: 1
                      interval: month
                      interval_count: 1
                interval:
                  type: string
                  description: Nouvel intervalle de renouvellement (`month`, `week` ou `day`), lu seulement avec `interval_count`.
                interval_count:
                  type: integer
                  description: Nouveau nombre d'intervalles, lu seulement avec `interval`.
                upsells:
                  type: array
                  description: Produits complémentaires (PrestaShop) enregistrés dans l'empreinte du panier de l'abonnement.
                  items:
                    type: object
                    properties:
                      product_id:
                        type: integer
                      product_attribute_id:
                        type: integer
                      quantity:
                        type: integer
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                    maxLength: 5000
                  description: |
                    Métadonnées personnalisées pour l'abonnement. Les valeurs doivent être des chaînes de caractères (max 5000 caractères).
                    Les clés commençant par "ciklik_encrypted_" seront automatiquement encryptées.
            example:
              active: true
              metadata:
                key1: "value1"
                key2: "value2"
                ciklik_encrypted_key2: "value-encrypted"

      responses:
        200:
          description: Succès - Abonnement mis à jour.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'

        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Abonnement introuvable, ou adresse, transporteur ou déclinaison qui n'appartient pas au site.
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteSubscription
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Supprimer un abonnement
      description: >-
        Supprime un abonnement (soft delete). L'abonnement doit être inactif
        (active = false) et appartenir au tenant authentifié pour pouvoir être supprimé.
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement à supprimer.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Succès - Abonnement supprimé.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Non trouvé - Abonnement introuvable ou n'appartenant pas au tenant authentifié.
        422:
          description: Erreur de validation - L'abonnement est encore actif.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        429:
          $ref: '#/components/responses/TooManyRequests'
  /subscriptions/{id}/products/{external_id}:
    patch:
      operationId: updateSubscriptionProduct
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Modifier la quantité d'un produit dans un abonnement
      description: Met à jour la quantité d'un produit spécifique déjà rattaché à l'abonnement. Les produits avec personnalisation (customization hash) ne sont pas modifiables.
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement
          required: true
          schema:
            type: string
        - name: external_id
          in: path
          description: Identifiant externe du produit (exodus_id)
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - quantity
              properties:
                quantity:
                  type: integer
                  minimum: 1
                  maximum: 9999
                  description: Nouvelle quantité du produit
            example:
              quantity: 3
      responses:
        200:
          description: Quantité mise à jour avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Abonnement ou produit introuvable
        422:
          description: Erreur de validation (quantité invalide, produit personnalisé, abonnement inactif). Un abonnement inactif ou un produit personnalisé répond avec un corps `{message}` sans `errors`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - $ref: "#/components/schemas/ErrorMessage"
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: removeSubscriptionProduct
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Retirer un produit d'un abonnement
      description: Retire un produit spécifique de l'abonnement. Impossible de retirer le dernier produit. Les produits avec personnalisation ne sont pas modifiables.
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement
          required: true
          schema:
            type: string
        - name: external_id
          in: path
          description: Identifiant externe du produit (exodus_id)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Produit retiré avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Abonnement ou produit introuvable
        422:
          description: Erreur de validation (dernier produit, produit personnalisé, abonnement inactif). Un abonnement inactif ou un produit personnalisé répond avec un corps `{message}` sans `errors`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - $ref: "#/components/schemas/ErrorMessage"
        429:
          $ref: '#/components/responses/TooManyRequests'
  /subscriptions/{id}/products:
    post:
      operationId: addSubscriptionProduct
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Ajouter un produit à un abonnement
      description: |
        Ajoute un produit à l'abonnement ou met à jour la quantité si le produit est déjà rattaché (upsert).
        Si le produit existe déjà en base (via son `external_id`), il est simplement rattaché ; les champs `price` et `tax` du corps sont alors ignorés.
        Si le produit n'existe pas, il est créé automatiquement : `price` devient **obligatoire**, `tax` défaut à 0 si absent.
        Les produits avec personnalisation (customization hash) ne sont pas acceptés.
        Retourne 201 pour un nouvel attachement (nouveau produit créé ou produit existant nouvellement rattaché), 200 pour une mise à jour de quantité sur un produit déjà rattaché.
      parameters:
        - name: id
          in: path
          description: UUID de l'abonnement
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - external_id
                - name
              properties:
                external_id:
                  type: string
                  maxLength: 255
                  description: Identifiant externe du produit (exodus_id)
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Nom du produit (utilisé lors de la création automatique, ignoré si le produit existe déjà)
                quantity:
                  type: integer
                  minimum: 1
                  maximum: 9999
                  default: 1
                  description: Quantité du produit (défaut 1)
                price:
                  type: number
                  minimum: 0
                  description: Prix HT du produit. **Obligatoire** si le produit n'existe pas encore en base et doit être créé. Ignoré si le produit existe déjà.
                tax:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Taux de TVA (ex. 0.2 pour 20%). Utilisé uniquement lors de la création ; défaut à 0 si absent. Ignoré si le produit existe déjà.
            example:
              external_id: "12345"
              name: "Produit mensuel"
              quantity: 2
              price: 19.99
              tax: 0.2
      responses:
        200:
          description: Quantité mise à jour (upsert - produit déjà rattaché)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'
        201:
          description: Produit ajouté à l'abonnement
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionEntity'
        401:
          description: Authentification requise (jeton absent ou invalide)
        404:
          description: Abonnement introuvable
        403:
          description: Accès interdit
        422:
          description: Erreur de validation (champs manquants, produit personnalisé, abonnement inactif, `price` manquant lors de la création d'un produit). Un abonnement inactif ou un produit personnalisé répond avec un corps `{message}` sans `errors`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - $ref: "#/components/schemas/ErrorMessage"
        429:
          $ref: '#/components/responses/TooManyRequests'
  /subscriptions:
    get:
      tags:
        - subscriptions
      security:
        - bearerAuth: [ ]
      summary: Récupérer une liste d'abonnement
      description: Permet de récupérer une liste d'abonnements avec différents filtres et options de tri. Sans paramètre `sort`, la liste est triée par `id` croissant (plus ancien en premier).
      parameters:
        - name: filter[activated]
          in: query
          description: Filtre par abonnements activés.
          schema:
            type: boolean
        - name: filter[canceled]
          in: query
          description: Filtre par abonnements annulés.
          schema:
            type: boolean
        - name: filter[created_at_before]
          in: query
          description: Filtre par date de création avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Filtre par date de création après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_before]
          in: query
          description: Filtre par date de mise à jour avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_after]
          in: query
          description: Filtre par date de mise à jour après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[canceled_since_before]
          in: query
          description: Filtre par date d'annulation avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[canceled_since_after]
          in: query
          description: Filtre par date d'annulation après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[expired]
          in: query
          description: Filtre par abonnements expirés.
          schema:
            type: boolean
          example: false
        - name: filter[in_grace_period]
          in: query
          description: Filtre par abonnements en période de grâce.
          schema:
            type: boolean
          example: false
        - name: filter[engaged_before]
          in: query
          description: Filtre par date d'engagement avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[engaged_after]
          in: query
          description: Filtre par date d'engagement après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[next_billing_before]
          in: query
          description: Filtre par date de prochaine facturation avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[next_billing_after]
          in: query
          description: Filtre par date de prochaine facturation après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[end_date_before]
          in: query
          description: Filtre par date de fin d'abonnement avant la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[end_date_after]
          in: query
          description: Filtre par date de fin d'abonnement après la date spécifiée.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[subscriptions_by_email]
          in: query
          description: Filtre par adresse e-mail.
          schema:
            type: string
            format: email
          example: "user@example.com"
        - name: filter[plan_id]
          in: query
          description: Filtre par ID (numérique) du plan, correspondance exacte.
          schema:
            type: string
            maxLength: 255
          example: "12"
        - name: filter[customer_id]
          in: query
          description: Filtre par ID de client.
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[interval]
          in: query
          description: Filtre par intervalle de facturation (correspondance partielle, insensible à la casse).
          schema:
            type: string
          example: "month"
        - name: filter[interval_count]
          in: query
          description: Filtre par nombre d'intervalles (correspondance exacte).
          schema:
            type: integer
          example: 1
        - name: sort
          in: query
          description: "Trier les résultats (préfixer par - pour un tri descendant). Tri par défaut : `id` croissant."
          schema:
            type: string
            enum:
              - plan_id
              - customer_id
              - canceled_at
              - active
              - start_date
              - first_renewal_date
              - end_date
              - created_at
              - updated_at
              - grace_period
              - grace_months
              - auto_pause_at
              - engaged_date
              - gift_activation_code
              - update_transporter_at
              - transporter_id
              - next_transporter_id
              - next_coupon_id
              - next_billing
              - interval
              - interval_count
              - -plan_id
              - -customer_id
              - -canceled_at
              - -active
              - -start_date
              - -first_renewal_date
              - -end_date
              - -created_at
              - -updated_at
              - -grace_period
              - -grace_months
              - -auto_pause_at
              - -engaged_date
              - -gift_activation_code
              - -update_transporter_at
              - -transporter_id
              - -next_transporter_id
              - -next_coupon_id
              - -next_billing
              - -interval
              - -interval_count
          example: "-created_at"
      responses:
        200:
          description: Liste de abonnements récupérée avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SubscriptionEntity"
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: "#/components/schemas/PaginationMeta"
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        429:
          $ref: '#/components/responses/TooManyRequests'
  /deliveries:
    get:
      operationId: listDeliveries
      summary: Liste des bons de livraison
      tags:
        - deliveries
      security:
        - bearerAuth: [ ]
      description: Récupère la liste de tous les bons de livraison de l'application. Les filtres exacts acceptent plusieurs valeurs séparées par des virgules (`filter[order_id]=12,13`).
      parameters:
        - name: filter[uuid]
          in: query
          description: Filtrer par UUID du bon de livraison.
          schema:
            type: string
        - name: filter[subscription_uuid]
          in: query
          description: Filtrer par UUID de la souscription associée.
          schema:
            type: string
        - name: filter[address_id]
          in: query
          description: Filtrer par ID de l'adresse.
          schema:
            type: integer
        - name: filter[phone]
          in: query
          description: Filtrer par numéro de téléphone.
          schema:
            type: string
        - name: filter[tracking_number]
          in: query
          description: Filtrer par numéro de suivi.
          schema:
            type: string
        - name: filter[customer_id]
          in: query
          description: Filtrer par ID du client.
          schema:
            type: string
        - name: filter[transporter_reference]
          in: query
          description: Filtrer par référence du transporteur.
          schema:
            type: string
        - name: filter[transporter_id]
          in: query
          description: Filtrer par ID du transporteur.
          schema:
            type: integer
        - name: filter[first_name]
          in: query
          description: Filtrer par prénom.
          schema:
            type: string
        - name: filter[last_name]
          in: query
          description: Filtrer par nom de famille.
          schema:
            type: string
        - name: filter[postcode]
          in: query
          description: Filtrer par code postal.
          schema:
            type: string
        - name: filter[address1]
          in: query
          description: Filtrer par adresse ligne 1.
          schema:
            type: string
        - name: filter[address2]
          in: query
          description: Filtrer par adresse ligne 2.
          schema:
            type: string
        - name: filter[city]
          in: query
          description: Filtrer par ville.
          schema:
            type: string
        - name: filter[country]
          in: query
          description: Filtrer par pays.
          schema:
            type: string
        - name: filter[mail]
          in: query
          description: Filtrer par adresse e-mail (correspondance exacte).
          schema:
            type: string
            maxLength: 255
        - name: filter[transporter_name]
          in: query
          description: Filtrer par nom du transporteur.
          schema:
            type: string
        - name: filter[plan]
          in: query
          description: Filtrer par nom du plan.
          schema:
            type: string
        - name: filter[iso_code]
          in: query
          description: Filtrer par code ISO du pays.
          schema:
            type: string
        - name: filter[relay_id]
          in: query
          description: Filtrer par ID du relais (chaîne, les identifiants de point relais ne sont pas tous numériques).
          schema:
            type: string
        - name: filter[orderable_name]
          in: query
          description: Filtrer par nom de l'élément commandable.
          schema:
            type: string
        - name: filter[orderable_id]
          in: query
          description: Filtrer par ID de l'élément commandable.
          schema:
            type: string
        - name: filter[orderable_type]
          in: query
          description: Filtrer par type de l'élément commandable.
          schema:
            type: string
        - name: filter[order_id]
          in: query
          description: Filtrer par ID de commande.
          schema:
            type: integer
        - name: filter[tracking_url]
          in: query
          description: Filtrer par URL de suivi.
          schema:
            type: string
        - name: filter[quantity]
          in: query
          description: Filtrer par quantité.
          schema:
            type: string
        - name: filter[ref]
          in: query
          description: Filtrer par référence.
          schema:
            type: string
        - name: filter[status]
          in: query
          description: Filtrer par statut du bon de livraison.
          schema:
            type: string
        - name: filter[division]
          in: query
          description: Filtrer par état/province.
          schema:
            type: string
        - name: filter[company_name]
          in: query
          description: Filtrer par nom de l'entreprise.
          schema:
            type: string
        - name: filter[created_at_before]
          in: query
          description: Filtrer par date de création antérieure.
          schema:
            type: string
            format: date-time
        - name: filter[created_at_after]
          in: query
          description: Filtrer par date de création ultérieure.
          schema:
            type: string
            format: date-time
        - name: filter[updated_at_before]
          in: query
          description: Filtrer par date de mise à jour antérieure.
          schema:
            type: string
            format: date-time
        - name: filter[updated_at_after]
          in: query
          description: Filtrer par date de mise à jour ultérieure.
          schema:
            type: string
            format: date-time
        - name: filter[scheduled_at_before]
          in: query
          description: Filtrer par date prévue antérieure.
          schema:
            type: string
            format: date-time
        - name: filter[scheduled_at_after]
          in: query
          description: Filtrer par date prévue ultérieure.
          schema:
            type: string
            format: date-time
        - name: sort
          in: query
          description: "Trier les résultats (préfixer par - pour un tri descendant)"
          schema:
            type: string
            enum:
              - uuid
              - subscription_uuid
              - address_id
              - phone
              - tracking_number
              - customer_id
              - transporter_reference
              - transporter_id
              - created_at
              - updated_at
              - first_name
              - last_name
              - postcode
              - address1
              - address2
              - city
              - country
              - mail
              - transporter_name
              - plan
              - iso_code
              - relay
              - relay_id
              - orderable_name
              - orderable_id
              - orderable_type
              - order_id
              - scheduled_at
              - tracking_url
              - quantity
              - ref
              - status
              - division
              - company_name
              - -uuid
              - -subscription_uuid
              - -address_id
              - -phone
              - -tracking_number
              - -customer_id
              - -transporter_reference
              - -transporter_id
              - -created_at
              - -updated_at
              - -first_name
              - -last_name
              - -postcode
              - -address1
              - -address2
              - -city
              - -country
              - -mail
              - -transporter_name
              - -plan
              - -iso_code
              - -relay
              - -relay_id
              - -orderable_name
              - -orderable_id
              - -orderable_type
              - -order_id
              - -scheduled_at
              - -tracking_url
              - -quantity
              - -ref
              - -status
              - -division
              - -company_name
          example: "-created_at"
      responses:
        200:
          description: Succès - Liste des bons de livraison récupérée avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliverySchema'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        429:
          $ref: '#/components/responses/TooManyRequests'
  /deliveries/{id}:
    get:
      operationId: getDelivery
      summary: Récupérer les détails d'un bon de livraison
      tags:
        - deliveries
      security:
        - bearerAuth: [ ]
      description: Récupère les détails d'un bon de livraison. `data` est une liste (un bon de livraison peut porter plusieurs lignes partageant le même UUID).
      parameters:
        - name: id
          in: path
          description: UUID du bon de livraison (champ `uuid`, pas l'identifiant numérique `id`)
          required: true
          schema:
            type: string
      responses:
        200:
          description: Succès - Bon de livraison récupéré avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliverySchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Aucun bon de livraison du site avec cet UUID
        429:
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: updateDelivery
      summary: Mettre à jour un bon de livraison
      tags:
        - deliveries
      security:
        - bearerAuth: [ ]
      description: |
        Permet de le considérer comme expédié, et associer un numéro et un lien de suivi.
        Un `tracking_number` est enregistré sur le bon de livraison (et renvoyé dans `tracking_number`), le lien de suivi est construit à partir du transporteur et le statut passe à `shipped`.
        La réponse renvoie les lignes du bon relues après la mise à jour, dans une liste `data`.
      parameters:
        - name: id
          in: path
          description: UUID du bon de livraison (champ `uuid`, pas l'identifiant numérique `id`)
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tracking_number:
                  type: [string, "null"]
                  maxLength: 255
                  description: Numéro de suivi à associer au bon de livraison. Il est enregistré et renvoyé dans le champ `tracking_number`.
                notification:
                  type: boolean
                  default: false
                  description: Facultatif. Envoyer au client la notification d'expédition avec le lien de suivi (faux par défaut). Lu uniquement avec `tracking_number`.
                status:
                  type: [string, "null"]
                  description: Nouveau statut du BL
                  enum:
                    - created
                    - pending
                    - shipped
                    - delivered
                    - scheduled
                    - canceled
      responses:
        200:
          description: Succès - Bon de livraison mis à jour avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliverySchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: Aucun bon de livraison du site avec cet UUID
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteDelivery
      tags:
        - deliveries
      security:
        - bearerAuth: [ ]
      summary: Supprimer un élément d'un bon de livraison
      description: Supprime un élément du bon de livraison en utilisant son identifiant numérique `id` (et non l'UUID utilisé par GET et POST).
      parameters:
        - name: id
          in: path
          description: Identifiant numérique (`id`) de l'élément du bon de livraison à supprimer
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Succès
          content:
            application/json:
              example:
                data:
                  success: true
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        404:
          description: Élément du bon de livraison non trouvé, ou appartenant à un autre site
        429:
          $ref: '#/components/responses/TooManyRequests'
  /orders:
    get:
      tags:
        - orders
      security:
        - bearerAuth: [ ]
      summary: Récupérer la liste des commandes
      parameters:
        - name: filter[user_id]
          in: query
          description: Filtrer par ID de l'utilisateur
          schema:
            type: integer
          example: 123
        - name: filter[address_id]
          in: query
          description: Filtrer par ID de l'adresse
          schema:
            type: integer
          example: 456
        - name: filter[invoice_address_id]
          in: query
          description: Filtrer par ID de l'adresse de facturation
          schema:
            type: integer
          example: 789
        - name: filter[transporter_id]
          in: query
          description: Filtrer par ID du transporteur
          schema:
            type: integer
          example: 10
        - name: filter[status]
          in: query
          description: >-
            Filtrer par statut de la commande. in_process : paiement en attente de la réponse de la passerelle, par
            exemple un renouvellement Mollie dont l'issue n'est pas encore confirmée.
          schema:
            type: string
            enum:
              - canceled
              - completed
              - failed
              - in_creation
              - in_process
              - pending
              - need_action
          example: "pending"
        - name: filter[subscription_uuid]
          in: query
          description: Filtrer par UUID de l'abonnement
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[invoice_id]
          in: query
          description: Filtrer par ID de la facture
          schema:
            type: integer
          example: 100
        - name: filter[total_paid]
          in: query
          description: Filtrer par montant total payé
          schema:
            type: number
          example: 29.99
        - name: filter[next_try]
          in: query
          description: Filtrer par prochaine tentative
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_before]
          in: query
          description: Filtrer par date de création avant
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Filtrer par date de création après
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_before]
          in: query
          description: Filtrer par date de mise à jour avant
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_after]
          in: query
          description: Filtrer par date de mise à jour après
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[next_try_before]
          in: query
          description: Filtrer par prochaine tentative avant
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[next_try_after]
          in: query
          description: Filtrer par prochaine tentative après
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[by_customer_uuid]
          in: query
          description: Filtrer par UUID du client
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[source]
          in: query
          description: Filtrer par source de la commande
          schema:
            type: string
            enum:
              - utm
              - referral
              - regain
              - retry
              - renew
              - backend
              - unsub_voucher
              - unsub_postpone
              - reactivation_offer
              - followup
              - gift_conversion
          example: "utm"
        - in: query
          name: sort
          description: "Trier les résultats (préfixer par - pour un tri descendant)"
          schema:
            type: string
            enum:
              - user_id
              - address_id
              - invoice_address_id
              - transporter_id
              - status
              - subscription_uuid
              - invoice_id
              - total_paid
              - next_try
              - source
              - created_at
              - updated_at
              - -user_id
              - -address_id
              - -invoice_address_id
              - -transporter_id
              - -status
              - -subscription_uuid
              - -invoice_id
              - -total_paid
              - -next_try
              - -source
              - -created_at
              - -updated_at
          example: "-created_at"
        - name: filter[prestashop_order_id]
          in: query
          description: Filtrer par correspondance commande PrestaShop
          schema:
            type: integer
          example: 500
      responses:
        200:
          description: Succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderSchema'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        403:
          description: Accès interdit
        401:
          description: Authentification requise (jeton absent ou invalide)
        429:
          $ref: '#/components/responses/TooManyRequests'
  /orders/{id}:
    get:
      summary: Récupérer le détail d'une commande
      tags:
        - orders
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          description: ID de la commande à récupérer
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OrderSchema'

        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La commande n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
  /addresses:
    get:
      summary: Liste des adresses
      tags:
        - addresses
      security:
        - bearerAuth: [ ]
      description: Cette route permet de lister des adresses.
      parameters:
        - name: filter[created_at_before]
          in: query
          description: Date de création avant laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Date de création après laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_before]
          in: query
          description: Date de mise à jour avant laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_after]
          in: query
          description: Date de mise à jour après laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[by_customer_uuid]
          in: query
          description: Filtrer par UUID du client.
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[region_id]
          in: query
          description: Filtrer par ID de la région.
          schema:
            type: integer
          example: 1
        - name: filter[user_id]
          in: query
          description: Filtrer par ID de l'utilisateur.
          schema:
            type: integer
          example: 123
        - name: filter[address]
          in: query
          description: Filtrer par adresse.
          schema:
            type: string
            maxLength: 32
          example: "123 Main St"
        - name: filter[address1]
          in: query
          description: Filtrer par adresse 1.
          schema:
            type: string
            maxLength: 32
          example: "123 Main St"
        - name: filter[postcode]
          in: query
          description: Filtrer par code postal.
          schema:
            type: string
            maxLength: 255
          example: "75001"
        - name: filter[city]
          in: query
          description: Filtrer par ville.
          schema:
            type: string
            maxLength: 255
          example: "Paris"
        - name: filter[first_name]
          in: query
          description: Filtrer par prénom.
          schema:
            type: string
            maxLength: 255
          example: "John"
        - name: filter[last_name]
          in: query
          description: Filtrer par nom.
          schema:
            type: string
            maxLength: 255
          example: "Doe"
        - name: filter[company_name]
          in: query
          description: Filtrer par nom de la société.
          schema:
            type: string
            maxLength: 255
          example: "Acme Corp"
        - name: filter[division]
          in: query
          description: Filtrer par état.
          schema:
            type: string
            maxLength: 255
          example: "Ile-de-France"
        - name: filter[phone]
          in: query
          description: Filtrer par numéro de téléphone.
          schema:
            type: string
            maxLength: 255
          example: "+33123456789"
        - in: query
          name: sort
          description: "Trier les résultats (préfixer par - pour un tri descendant)"
          schema:
            type: string
            enum:
              - region_id
              - user_id
              - address
              - address1
              - postcode
              - city
              - first_name
              - last_name
              - company_name
              - division
              - phone
              - created_at
              - updated_at
              - -region_id
              - -user_id
              - -address
              - -address1
              - -postcode
              - -city
              - -first_name
              - -last_name
              - -company_name
              - -division
              - -phone
              - -created_at
              - -updated_at
          example: "-created_at"
      responses:
        200:
          description: Réponse en cas de succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Address'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Créer une adresse
      tags:
        - addresses
      security:
        - bearerAuth: [ ]
      description: |
        Cette route permet de créer une adresse pour un client du site.
        Le client (`user_id`) doit appartenir au site du jeton et le pays (`region_id`) doit être ouvert sur le site.
        Le code postal est contrôlé selon le pays ; le téléphone doit être un mobile valide du pays si le contrôle des numéros est actif sur le site.
        Pour un pays que la bibliothèque de numérotation ne connaît pas (Terres australes françaises par exemple), le téléphone n'est pas contrôlé et il est enregistré tel que saisi.
        Les champs texte sont normalisés (majuscules, sans accents ni ponctuation). Tout champ non listé est ignoré.
        La création déclenche le webhook `created_address`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - region_id
                - address
                - postcode
                - city
                - first_name
                - last_name
                - phone
              properties:
                user_id:
                  type: integer
                  description: ID du client (champ `id` du client), qui doit appartenir au site du jeton.
                  example: 123
                region_id:
                  type: integer
                  description: ID du pays, parmi les pays ouverts sur le site.
                  example: 1
                address:
                  type: string
                  maxLength: 32
                  example: "12 rue de la Paix"
                address1:
                  type: [string, "null"]
                  maxLength: 32
                  description: Complément d'adresse.
                  example: "Bâtiment B"
                postcode:
                  type: string
                  maxLength: 20
                  description: Code postal, au format du pays.
                  example: "75002"
                city:
                  type: string
                  maxLength: 255
                  example: "Paris"
                first_name:
                  type: string
                  maxLength: 255
                  example: "Jeanne"
                last_name:
                  type: string
                  maxLength: 255
                  example: "Martin"
                company_name:
                  type: [string, "null"]
                  maxLength: 255
                  example: "Acme"
                phone:
                  type: string
                  maxLength: 30
                  description: Téléphone mobile, au format national ou international.
                  example: "0612345678"
                division:
                  type: [string, "null"]
                  maxLength: 10
                  description: Code de subdivision (état). Requis pour les États-Unis, parmi les codes d'État (par exemple NY).
                  example: "NY"
      responses:
        201:
          description: Adresse créée
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit (jeton qui n'est pas celui d'un site)
        404:
          description: Le client n'a pas été trouvé (supprimé entre la validation et la création ; un client inconnu ou d'un autre site renvoie 422)
        422:
          description: Erreur de validation (client inconnu ou d'un autre site, pays non ouvert, code postal ou téléphone invalide, champ manquant ou trop long)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /addresses/{id}:
    put:
      summary: Mettre à jour une adresse
      tags:
        - addresses
      security:
        - bearerAuth: [ ]
      description: Cette route permet de mettre à jour une adresse.
      parameters:
        - in: path
          name: id
          required: true
          description: ID de l'adresse à mettre à jour.
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - postcode
                - city
                - first_name
                - last_name
                - phone
                - region_id
              properties:
                address:
                  type: string
                  maxLength: 32
                address1:
                  type: [string, "null"]
                  maxLength: 32
                postcode:
                  type: string
                  maxLength: 20
                city:
                  type: string
                  maxLength: 255
                first_name:
                  type: string
                  maxLength: 255
                last_name:
                  type: string
                  maxLength: 255
                company_name:
                  type: [string, "null"]
                  maxLength: 255
                phone:
                  type: string
                  maxLength: 30
                region_id:
                  type: integer
                division:
                  type: [string, "null"]
                  maxLength: 10
                  description: Code de subdivision (état/province). Requis pour les États-Unis.
      responses:
        200:
          description: Réponse en cas de succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: L'adresse n'a pas été trouvée
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
    get:
      summary: Récupérer les données d'une adresse
      tags:
        - addresses
      security:
        - bearerAuth: [ ]
      description: Cette route permet de récupérer une adresse.
      parameters:
        - in: path
          name: id
          required: true
          description: ID de l'adresse à récupérer.
          schema:
            type: integer
      responses:
        200:
          description: Réponse en cas de succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: L'adresse n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Supprimer une adresse
      tags:
        - addresses
      security:
        - bearerAuth: [ ]
      description: Cette route permet de supprimer une adresse. Une adresse qui n'est pas supprimable (champ `deletable` à false) répond 403.
      parameters:
        - in: path
          name: id
          required: true
          description: ID de l'adresse à supprimer.
          schema:
            type: integer
      responses:
        200:
          description: Succès
          content:
            application/json:
              example:
                data:
                  success: true
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Adresse non supprimable (champ `deletable` à false), ou accès interdit
        404:
          description: L'adresse n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
  /customers:
    get:
      summary: Liste des utilisateurs
      tags:
        - customers
      security:
        - bearerAuth: [ ]
      description: Cette route permet de récupérer une liste d'utilisateurs.
      parameters:
        - name: filter[created_at_before]
          in: query
          description: Date de création avant laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Date de création après laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_before]
          in: query
          description: Date de mise à jour avant laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_after]
          in: query
          description: Date de mise à jour après laquelle filtrer.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[uuid]
          in: query
          description: Filtrer par UUID de l'utilisateur.
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[id]
          in: query
          description: Filtrer par ID de l'utilisateur.
          schema:
            type: integer
          example: 123
        - name: filter[email]
          in: query
          description: Filtrer par adresse e-mail de l'utilisateur.
          schema:
            type: string
          example: "user@example.com"
        - name: filter[external_id]
          in: query
          description: Filtrer par ID externe de l'utilisateur.
          schema:
            type: string
          example: "ext_12345"
        - name: filter[disabled]
          in: query
          description: Filtrer par statut de désactivation de l'utilisateur.
          schema:
            type: boolean
          example: false
        - name: filter[referrer]
          in: query
          description: Filtrer par référent de l'utilisateur.
          schema:
            type: string
          example: "referral_code_123"
        - in: query
          name: sort
          description: "Trier les résultats (préfixer par - pour un tri descendant)"
          schema:
            type: string
            enum:
              - id
              - uuid
              - email
              - created_at
              - updated_at
              - -id
              - -uuid
              - -email
              - -created_at
              - -updated_at
          example: "-created_at"
      responses:
        200:
          description: Réponse en cas de succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserSchema'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Créer un nouvel utilisateur
      tags:
        - customers
      description: Cette route permet de créer un nouveau compte utilisateur. Si l'adresse email existe déjà sur le site, la réponse contient l'utilisateur associé (statut 200, `external_id` n'est pas modifié). Dans le cas contraire, le compte est créé et renvoyé (statut 201). Le client est enveloppé dans `data`.
      security:
        - bearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Adresse e-mail de l'utilisateur
                  example: user@example.com
                external_id:
                  type: [string, integer, "null"]
                  maxLength: 255
                  description: Identifiant externe facultatif à enregistrer (chaîne ou entier, 255 caractères max), utilisé seulement à la création
                  example: some_external_id
              required:
                - email
      responses:
        200:
          description: Le client existait déjà sur le site, il est renvoyé tel quel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserSchema'
        201:
          description: Client créé
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserSchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /customers/{id}:
    get:
      summary: Récupérer les détails d'un utilisateur
      tags:
        - customers
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          description: UUID de l'utilisateur (l'identifiant numérique n'est pas accepté)
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserSchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La ressource n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
  /transactions:
    get:
      summary: Récupérer la liste des transactions
      tags:
        - transactions
      security:
        - bearerAuth: [ ]
      parameters:
        - name: filter[order_id]
          in: query
          description: Filtrer par ID de la commande.
          schema:
            type: integer
          example: 456
        - name: filter[gateway]
          in: query
          description: >-
            Filtrer par moyen de paiement (clé de classe, correspondance exacte), par exemple
            `StripeCreditCard`, `PayPlugCreditCard`, `MollieCreditCard`, `PaypalVault`, `GoCardlessDirectDebit`.
          schema:
            type: string
          example: "MollieCreditCard"
        - name: filter[transaction_id]
          in: query
          description: Filtrer par identifiant de la transaction.
          schema:
            type: string
          example: "ch_123456"
        - name: filter[detail]
          in: query
          description: Filtrer par détail de la transaction (correspondance exacte).
          schema:
            type: string
        - name: filter[token]
          in: query
          description: Filtrer par jeton de la transaction.
          schema:
            type: string
        - name: filter[paid]
          in: query
          description: Filtrer par transactions payées.
          schema:
            type: boolean
          example: true
        - name: filter[amount]
          in: query
          description: Filtrer par montant (correspondance exacte).
          schema:
            type: number
          example: 29.99
        - name: filter[refunded]
          in: query
          description: Filtrer par transactions remboursées.
          schema:
            type: boolean
          example: false
        - name: filter[user_id]
          in: query
          description: Filtrer par ID de l'utilisateur.
          schema:
            type: integer
          example: 123
        - name: filter[failure_code]
          in: query
          description: >-
            Filtrer par code d'échec de la transaction (correspondance exacte). Le code est celui qu'écrit la
            passerelle : code de refus Stripe (`card_declined`, `insufficient_funds`...), motif de refus de Mollie
            (`authentication_failed`, `card_expired`...) ou code posé par Ciklik (`mandate_revoked`,
            `merchant_forbidden`, `forbidden`, `payment_method_missing`...).
          schema:
            type: string
            maxLength: 255
          example: "mandate_revoked"
        - name: filter[invoice_id]
          in: query
          description: Filtrer par ID de la facture.
          schema:
            type: integer
          example: 100
        - name: filter[created_at_before]
          in: query
          description: Filtrer par date de création avant.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Filtrer par date de création après.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_before]
          in: query
          description: Filtrer par date de mise à jour avant.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[updated_at_after]
          in: query
          description: Filtrer par date de mise à jour après.
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[by_customer_uuid]
          in: query
          description: Filtrer par UUID du client.
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[source_id]
          in: query
          description: Filtrer par ID de la source.
          schema:
            type: string
            maxLength: 255
          example: "src_12345"
        - name: filter[amount_refunded]
          in: query
          description: Filtrer par montant remboursé.
          schema:
            type: number
          example: 10.50
        - name: filter[payment_intent_id]
          in: query
          description: Filtrer par ID de l'intention de paiement.
          schema:
            type: string
            maxLength: 255
          example: "card_declined"
        - name: sort
          in: query
          description: "Trier les résultats (préfixer par - pour un tri descendant)"
          schema:
            type: string
            enum:
              - order_id
              - gateway
              - transaction_id
              - detail
              - token
              - paid
              - amount
              - refunded
              - source_id
              - failure_code
              - invoice_id
              - amount_refunded
              - user_id
              - payment_intent_id
              - created_at
              - updated_at
              - -order_id
              - -gateway
              - -transaction_id
              - -detail
              - -token
              - -paid
              - -amount
              - -refunded
              - -source_id
              - -failure_code
              - -invoice_id
              - -amount_refunded
              - -user_id
              - -payment_intent_id
              - -created_at
              - -updated_at
          example: "-created_at"
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionSchema'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La ressource n'a pas été trouvée
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /transactions/{transaction_id}:
    get:
      summary: Récupérer une transaction par ID
      tags:
        - transactions
      security:
        - bearerAuth: [ ]
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: L'identifiant de la transaction à récupérer (champ `transaction_id`).
          schema:
            type: string
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TransactionSchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La ressource n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
    put:
      summary: Demander le remboursement d'une transaction par ID
      description: |
        Rembourse tout ou partie d'une transaction payée. La réponse renvoie la transaction, enveloppée dans `data`.
        Un remboursement refusé (transaction échouée, montant supérieur au restant, solde insuffisant, refus de Stripe) répond 422 avec le motif dans `errors.error`. Un refus d'une autre passerelle peut répondre 500.
      tags:
        - transactions
      security:
        - bearerAuth: [ ]
      parameters:
          - name: transaction_id
            in: path
            required: true
            description: L'identifiant de la transaction à rembourser.
            schema:
              type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
              properties:
                amount:
                  type: number
                  minimum: 0.01
                  description: Le montant à rembourser (numérique, minimum 0.01).
      responses:
        200:
          description: Réponse réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TransactionSchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La ressource n'a pas été trouvée
        422:
          description: Erreur de validation du montant (`errors.amount`), ou remboursement refusé (motif dans `errors.error`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                message: Vous ne pouvez pas rembourser une transaction échouée.
                errors:
                  error:
                    - Vous ne pouvez pas rembourser une transaction échouée.
        429:
          $ref: '#/components/responses/TooManyRequests'
  /kpis:
    get:
      tags:
        - kpis
      security:
        - bearerAuth: [ ]
      summary: Récupérer les indicateurs de performance
      description: Permet de récupérer les indicateurs de performance avec différents filtres.
      parameters:
        - name: filter[created_at_before]
          in: query
          description: Filtre les KPIs créés avant cette date
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Filtre les KPIs créés après cette date
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: sort
          in: query
          description: Tri des résultats (prefix - pour ordre décroissant)
          schema:
            type: string
            enum: [created_at, -created_at]
      responses:
        200:
          description: Liste des KPIs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        users_subscribed:
                          type: integer
                          description: Nombre d'utilisateurs inscrits à la date donnée
                        subscriptions:
                          type: integer
                          description: Nombre d'abonnements créés à la date donnée
                        sum_subscriptions:
                          type: integer
                          description: Montant total des abonnements créés à la date donnée (en centimes)
                        purchases:
                          type: integer
                          description: Nombre d'achats uniques (hors abonnements) à la date donnée
                        sum_purchases:
                          type: integer
                          description: Montant total des achats uniques à la date donnée (en centimes)
                        subscriptions_paused:
                          type: integer
                          description: Nombre d'abonnements mis en pause
                        subscriptions_restarted:
                          type: integer
                          description: Nombre d'abonnements réactivés
                        subscription_grace_total:
                          type: integer
                          description: Nombre total d'abonnements en période de grâce
                        subscription_grace_ending:
                          type: integer
                          description: Nombre d'abonnements dont la période de grâce se termine
                        lives:
                          type: integer
                          description: Nombre d'abonnements actifs
                        active_expired:
                          type: integer
                          description: Nombre d'abonnements actifs mais expirés
                        source_updated_count:
                          type: integer
                          description: Nombre de mises à jour de source
                        voided_unsub_voucher_count:
                          type: integer
                          description: Nombre de bons annulés pour désabonnement
                        voided_unsub_postpone_count:
                          type: integer
                          description: Nombre de reports annulés pour désabonnement
                        amount_utm:
                          type: integer
                          description: Montant des achats via UTM (en centimes)
                        amount_referral:
                          type: integer
                          description: Montant des achats via parrainage (en centimes)
                        amount_regain:
                          type: integer
                          description: Montant des achats via récupération (en centimes)
                        amount_retry:
                          type: integer
                          description: Montant des achats via nouvelle tentative (en centimes)
                        amount_renew:
                          type: integer
                          description: Montant des renouvellements (en centimes)
                        amount_backend:
                          type: integer
                          description: Montant des achats via backend (en centimes)
                        amount_unsub_voucher:
                          type: integer
                          description: Montant des bons de désabonnement (en centimes)
                        amount_unsub_postpone:
                          type: integer
                          description: Montant des reports de désabonnement (en centimes)
                        amount_reactivation_offer:
                          type: integer
                          description: Montant des offres de réactivation (en centimes)
                        count_utm:
                          type: integer
                          description: Nombre d'achats via UTM
                        count_referral:
                          type: integer
                          description: Nombre d'achats via parrainage
                        count_regain:
                          type: integer
                          description: Nombre d'achats via récupération
                        count_retry:
                          type: integer
                          description: Nombre d'achats via nouvelle tentative
                        count_renew:
                          type: integer
                          description: Nombre de renouvellements
                        count_backend:
                          type: integer
                          description: Nombre d'achats via backend
                        count_unsub_voucher:
                          type: integer
                          description: Nombre de bons de désabonnement
                        count_unsub_postpone:
                          type: integer
                          description: Nombre de reports de désabonnement
                        count_reactivation_offer:
                          type: integer
                          description: Nombre d'offres de réactivation
                        count_followup:
                          type: integer
                          description: Nombre de suivis
                        amount_followup:
                          type: integer
                          description: Montant des suivis (en centimes)
                        amount_renew_failed:
                          type: integer
                          description: Montant des renouvellements échoués (en centimes)
                        count_renew_failed:
                          type: integer
                          description: Nombre de renouvellements échoués
                        created_at:
                          type: string
                          format: date-time
                          description: Date de création
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: La ressource n'a pas été trouvée
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /rebill-errors:
    get:
      operationId: listRebillErrors
      tags:
        - rebill-errors
      security:
        - bearerAuth: [ ]
      summary: Récupérer la liste des erreurs de rebill
      description: Permet de récupérer la liste des erreurs de rebill avec différents filtres.
      parameters:
        - name: filter[type]
          in: query
          description: Filtrer par type d'erreur
          schema:
            type: string
            enum:
              - api
              - partial
              - failed
          example: "api"
        - name: filter[by_subscription_uuid]
          in: query
          description: Filtrer par UUID de l'abonnement
          schema:
            type: string
            maxLength: 255
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: filter[order_id]
          in: query
          description: Filtrer par ID de la commande
          schema:
            type: integer
          example: 456
        - name: filter[error_code]
          in: query
          description: Filtrer par code d'erreur
          schema:
            type: integer
          example: 500
        - name: filter[created_at_before]
          in: query
          description: Filtrer par date de création avant
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: filter[created_at_after]
          in: query
          description: Filtrer par date de création après
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: sort
          in: query
          description: Trier les résultats (prefix - pour ordre décroissant)
          schema:
            type: string
            enum:
              - id
              - -id
              - type
              - -type
              - order_id
              - -order_id
              - error_code
              - -error_code
              - created_at
              - -created_at
              - updated_at
              - -updated_at
        - name: page
          in: query
          description: Numéro de la page pour la pagination
          schema:
            type: integer
      responses:
        200:
          description: Liste des erreurs de rebill récupérée avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RebillErrorLogsSchema'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        422:
          description: Erreur de validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /rebill-errors/{id}:
    get:
      operationId: getRebillError
      tags:
        - rebill-errors
      security:
        - bearerAuth: [ ]
      summary: Récupérer le détail d'une erreur de rebill
      description: Permet de récupérer les détails d'une erreur de rebill spécifique.
      parameters:
        - name: id
          in: path
          description: ID de l'erreur de rebill
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Détails de l'erreur de rebill récupérés avec succès
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RebillErrorLogsSchema'
        401:
          description: Authentification requise (jeton absent ou invalide)
        403:
          description: Accès interdit
        404:
          description: L'erreur de rebill n'a pas été trouvée
        429:
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Jeton d'API Ciklik (jeton opaque, pas un JWT), envoyé dans l'en-tête `Authorization: Bearer <jeton>`."
  headers:
    X-RateLimit-Limit:
      description: Nombre maximum de requêtes autorisées par minute et par adresse IP.
      schema:
        type: integer
        example: 200
    X-RateLimit-Remaining:
      description: Nombre de requêtes restantes dans la fenêtre courante.
      schema:
        type: integer
        example: 195
    Retry-After:
      description: Nombre de secondes avant la réinitialisation de la fenêtre de rate limiting.
      schema:
        type: integer
        example: 60
  responses:
    TooManyRequests:
      description: Limite de débit atteinte (200 requêtes par minute, comptées par adresse IP).
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        text/plain:
          schema:
            type: string
            example: "Too many requests"
  schemas:
    TransactionSchema:
      type: object
      properties:
        order_id:
          type: integer
          description: L'identifiant de la commande.
        order:
          $ref: '#/components/schemas/TransactionOrderSchema'
        gateway:
          type: string
          description: >-
            Moyen de paiement de la transaction (clé de classe), par exemple `StripeCreditCard`, `PayPlugCreditCard`, `MollieCreditCard`, `PaypalVault`, `GoCardlessDirectDebit`.
          example: "MollieCreditCard"
        transaction_id:
          type: string
          description: >-
            L'identifiant de la transaction chez la passerelle. Pour Mollie, l'identifiant du paiement (`tr_...`).
        detail:
          type: string
          description: >-
            Détails de la transaction. Valeurs propres à Mollie : `pending` (renouvellement dont Mollie n'a pas encore
            confirmé l'issue, la commande est alors `in_process`) et `replaced` (tentative en cours reprise par un
            prélèvement suivant, qui porte le même paiement).
        token:
          type: string
          description: Le jeton de la transaction.
        tenant_id:
          type: integer
          description: L'identifiant du locataire.
        paid:
          type: boolean
          description: Indique si la transaction a été payée.
        amount:
          type: string
          description: Le montant de la transaction.
        refunded:
          type: boolean
          description: Indique si la transaction a été remboursée.
        source_id:
          type: string
          description: >-
            L'identifiant de la source (moyen de paiement débité). Pour Mollie, en général le mandat de la carte
            enregistrée (`mdt_...`).
        failure_message:
          type: string
          description: Message d'échec de la transaction.
        failure_code:
          type: string
          description: >-
            Code d'échec de la transaction. Pour Mollie : le motif de refus donné par Mollie, ou un code posé par
            Ciklik quand la requête de prélèvement est refusée (`mandate_revoked` : carte retirée ou mandat révoqué,
            `merchant_forbidden` : clé API du site refusée par Mollie, `forbidden` : requête refusée,
            `payment_method_missing` : aucun client Mollie enregistré).
        invoice_id:
          type: integer
          description: L'identifiant de la facture associée à la transaction.
        amount_refunded:
          type: string
          description: Montant remboursé de la transaction.
        statement_descriptor:
          type: string
          description: Description de l'état de compte.
        user_id:
          type: integer
          description: L'identifiant de l'utilisateur associé à la transaction.
        created_at:
          type: string
          format: date-time
          description: Date et heure de création de la transaction.
        updated_at:
          type: string
          format: date-time
          description: Date et heure de mise à jour de la transaction.
        payment_intent_id:
          type: string
          description: >-
            L'identifiant de l'intention de paiement associée à la transaction. Pour Mollie, l'identifiant du paiement
            (`tr_...`).
    TransactionOrderSchema:
      type: object
      description: >
        Commande détaillée de la transaction. Elle diffère de la commande renvoyée par /orders : mêmes champs de base
        (order_id, user_id, user_uuid, first_name, last_name, phone, email, status, created, items, shipping, count,
        total_tax_paid, total_discount_inc, total_paid, total_shipping_paid, created_at, coupon, subscription_uuid,
        retry_link, paid_transaction_id, paid_class_key, prestashop_order_id), sans `updated_at`, avec des articles
        au format interne et des statistiques client et abonnement en plus.
      additionalProperties: true
      properties:
        order_id:
          type: integer
          description: ID de la commande
        status:
          type: string
          description: Statut de la commande
        items:
          type: array
          description: Articles de la commande
          items:
            type: object
            additionalProperties: true
        revenue:
          type: [string, 'null']
          description: Revenu de l'abonnement (payé moins remboursé), chaîne formatée, null hors abonnement
        refunded:
          type: [string, 'null']
          description: Montant remboursé sur l'abonnement, chaîne formatée, null hors abonnement
        customerRevenue:
          type: string
          description: Revenu du client (payé moins remboursé), chaîne formatée avec séparateur de milliers
        customerRefund:
          type: string
          description: Montant remboursé au client, chaîne formatée avec séparateur de milliers
        totalTransactionsSuccess:
          type: integer
          description: Nombre de transactions réussies du client
        subTransactionsSuccess:
          type: [integer, 'null']
          description: Nombre de transactions payées sur l'abonnement
        next_billing:
          type: [string, 'null']
          format: date-time
          description: Prochaine échéance de l'abonnement lié
        countTransactions:
          type: integer
          description: Nombre de transactions de la commande
        choices:
          description: Choix de l'abonnement lié, null hors abonnement
    DeliverySchema:
      type: object
      properties:
        tenant_id:
          type: integer
          description: ID du site.
        id:
          type: integer
          description: ID du bon de livraison.
        uuid:
          type: string
          description: UUID du bon de livraison.
        address:
          $ref: '#/components/schemas/Address'
          description: Informations sur l'adresse de livraison.
        transporter:
          $ref: '#/components/schemas/Transporter'
          description: Informations sur le transporteur.
        created_at:
          type: string
          format: date-time
          description: Date de création du bon de livraison.
        updated_at:
          type: string
          format: date-time
          description: Date de dernière mise à jour du bon de livraison.
        scheduled_at:
          type: string
          format: date-time
          description: Date prévue de livraison.
        tracking_link:
          type: string
          description: Lien de suivi.
        subscription_uuid:
          type: string
          description: UUID de la souscription associée.
        address_id:
          type: integer
          description: ID de l'adresse.
        phone:
          type: string
          description: Numéro de téléphone.
        status:
          type: string
          description: Statut du bon de livraison.
          enum:
            - created
            - pending
            - shipped
            - delivered
            - scheduled
            - canceled
        tracking_number:
          type: string
          description: Numéro de suivi du transporteur.
        customer_id:
          type: string
          description: ID du client.
        supply_id:
          type: [string, "null"]
          description: Référence du transporteur chez le logisticien (filtrable et triable sous le nom `transporter_reference`).
        transporter_id:
          type: [integer, "null"]
          description: ID du transporteur.
        first_name:
          type: string
          description: Prénom du destinataire.
        last_name:
          type: string
          description: Nom de famille du destinataire.
        postcode:
          type: string
          description: Code postal de l'adresse de livraison.
        address1:
          type: string
          description: Adresse ligne 1.
        address2:
          type: string
          description: Adresse ligne 2.
        division:
          type: string
          description: Etat.
        city:
          type: string
          description: Ville de l'adresse de livraison.
        country:
          type: string
          description: Pays de l'adresse de livraison.
        mail:
          type: string
          description: Adresse e-mail du destinataire.
        subscriptions_count:
          type: string
          description: Nombre total de souscriptions pour l'abonné.
        transporter_name:
          type: string
          description: Nom du transporteur.
        shipped_count:
          type: string
          description: Nombre de livraisons expédiées.
        site_name:
          type: string
          description: Nom du site associé.
        options:
          type: string
          description: Options spécifiques au bon de livraison.
        iso_code:
          type: string
          description: Code ISO du pays.
        relay:
          type: [object, "null"]
          additionalProperties: true
          description: Point relais de livraison, null sans point relais.
        relay_id:
          type: [string, "null"]
          description: ID du relais de livraison.
        orderable_name:
          type: string
          description: Nom de l'élément commandable.
        orderable_id:
          type: string
          description: ID de l'élément commandable.
        orderable_type:
          type: string
          description: Type de l'élément commandable.
          enum:
            - App\Product
            - App\AddonPlan
            - App\Plan
        order_id:
          type: integer
          description: ID de la commande associée.
        ref:
          type: string
          description: Référence du produit dans le BL au moment de la commande.
        customization_products:
          type: array
          description: >
            Composition de base de la box, issue de la sélection de personnalisation de l'abonnement.
            Chaque entrée est une ligne produit identifiée par son customizationId.
          items:
            type: object
            properties:
              customizationId:
                type: integer
                description: Identifiant unique de la ligne de personnalisation (clé de rapprochement avec extra_customization_products).
              productId:
                type: integer
                description: ID du produit.
              quantity:
                type: integer
                description: Quantité de base de la ligne.
              ref:
                type: string
                description: Référence du produit.
        extra_customization_products:
          type: array
          description: >
            Surcharges propres à ce bon de livraison (modifications manuelles de la box).
            IMPORTANT : chaque entrée est un OVERRIDE ABSOLU par customizationId, pas un delta.
            Quand une ligne figure ici, sa quantity REMPLACE celle de customization_products pour le
            même customizationId ; elle ne s'y ajoute jamais. Les lignes absentes de ce tableau
            conservent la quantité de customization_products. La composition finale se calcule donc en
            partant de customization_products, puis en remplaçant chaque customizationId présent dans
            extra_customization_products (ou en l'ajoutant s'il n'existe pas en base). Ne jamais
            additionner les deux tableaux.
          items:
            type: object
            properties:
              customizationId:
                type: integer
                description: Identifiant de la ligne de personnalisation surchargée (matche un customizationId de customization_products pour un remplacement, ou en ajoute un nouveau).
              productId:
                type: integer
                description: ID du produit.
              quantity:
                type: integer
                description: Quantité finale absolue de la ligne (remplace la quantité de base).
              ref:
                type: string
                description: Référence du produit.
    WebsiteEntity:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: L'identifiant unique de l'entité "Website".
            name:
              type: string
              description: Le nom de l'entité "Website".
            host:
              type: string
              description: Le nom de domaine du site.
            paymentMethods:
              type: array
              items:
                $ref: "#/components/schemas/PaymentMethodEntity"
              description: >-
                Les moyens de paiement actifs du site (rattachés au site et dont la passerelle est configurée et
                activée), un par clé de classe.
            webhooks:
              type: object
              description: Liste des évènements actifs et URL correspondante
              additionalProperties:
                type: string
            metadata:
              type: object
              additionalProperties:
                type: string

    InstallationState:
      type: object
      description: État d'installation de l'espace, tel qu'affiché dans le back-office du module PrestaShop.
      properties:
        space:
          type: object
          properties:
            id:
              type: integer
              description: Identifiant de l'espace (site).
            name:
              type: string
              description: Nom de l'espace.
            domain:
              type: string
              description: Domaine de l'espace.
            kind:
              type: string
              enum:
                - sandbox
                - production
              description: Espace de test (sandbox) ou de production.
        complete:
          type: boolean
          description: Vrai quand toutes les étapes applicables sont franchies.
        stalled:
          type: boolean
          description: Vrai quand l'installation est en pause (aucune nouvelle étape franchie depuis soixante jours alors qu'il reste quelque chose à faire).
        collision:
          type: [object, "null"]
          description: Autre espace déclaré avec la même adresse de boutique, null s'il n'y en a pas.
          properties:
            normalized_host:
              type: string
            current_tenant_id:
              type: integer
            current_is_sandbox:
              type: boolean
            other_tenant_id:
              type: integer
            other_tenant_name:
              type: string
            other_tenant_domain:
              type: string
            other_is_sandbox:
              type: boolean
        counts:
          type: object
          properties:
            done:
              type: integer
              description: Nombre d'étapes franchies.
            broken:
              type: integer
              description: Nombre d'étapes bloquées.
            upcoming:
              type: integer
              description: Nombre d'étapes restant à faire.
        summary:
          type: string
          description: Résumé traduit de l'état d'installation.
        last_probed_at:
          type: [string, "null"]
          format: date-time
          description: Date de la dernière vérification (ISO 8601), null si aucune vérification n'a encore eu lieu.
        steps:
          type: array
          description: Étapes applicables à l'espace.
          items:
            type: object
            properties:
              key:
                type: string
                description: Clé de l'étape.
              group:
                type: string
                enum:
                  - site
                  - email
                description: Groupe de l'étape.
              label:
                type: string
                description: Libellé traduit de l'étape.
              state:
                type: string
                enum:
                  - verified
                  - in_progress
                  - todo
                  - claimed_not_observed
                  - broken
                  - not_applicable
                  - unverified
                description: État affiché de l'étape.
              state_label:
                type: string
                description: Libellé traduit de l'état.
              is_blocking:
                type: boolean
                description: Vrai si l'étape conditionne la mise en ligne de l'espace (étapes du groupe site ; le groupe email ne bloque rien).
              observed_at:
                type: [string, "null"]
                format: date-time
                description: Date à laquelle l'état a été observé (ISO 8601).
        remaining:
          type: array
          description: Clés des étapes qui restent à faire.
          items:
            type: string
        tracking_url:
          type: string
          description: Adresse de la page de suivi d'installation.
        tracking_url_valid_until:
          type: [string, "null"]
          format: date-time
          description: Date de fin de validité de l'adresse de suivi (ISO 8601), null si elle n'expire pas.
    PaymentMethodEntity:
      type: object
      properties:
        id:
          type: integer
          description: L'identifiant unique de la méthode de paiement.
        name:
          type: object
          properties:
            fr:
              type: string
              description: Le nom de la méthode de paiement en français.
        description:
          type: object
          properties:
            fr:
              type: string
              description: La description de la méthode de paiement en français.
        class_key:
          type: string
          description: >-
            Clé de classe du moyen de paiement, par exemple `StripeCreditCard`, `PayPlugCreditCard`, `MollieCreditCard`, `PaypalVault`, `GoCardlessDirectDebit`. `MollieCreditCard` : carte bancaire
            via le compte Mollie du marchand, paiement sur la page hébergée par Mollie.
          example: "MollieCreditCard"
        gateway_id:
          type: integer
          description: L'identifiant de la passerelle de paiement associée à la méthode de paiement.
        created_at:
          type: string
          description: La date de création de la méthode de paiement au format ISO 8601.
        updated_at:
          type: string
          description: La date de mise à jour de la méthode de paiement au format ISO 8601.
        deleted_at:
          type: string
          description: La date de suppression de la méthode de paiement au format ISO 8601 ou la valeur nulle si la méthode n'a pas été supprimée.
        checkout_manager:
          type: string
          description: Le gestionnaire de paiement associé à la méthode de paiement.
        need_payable:
          type: boolean
          description: Indique si la méthode de paiement nécessite un élément payable.
        pivot:
          type: object
          properties:
            tenant_id:
              type: integer
              description: L'identifiant du locataire.
            payment_method_id:
              type: integer
              description: L'identifiant de la méthode de paiement.
            created_at:
              type: string
              description: La date de création de la liaison au format ISO 8601.
            updated_at:
              type: string
              description: La date de mise à jour de la liaison au format ISO 8601
    ProductEntityUpdate:
      type: object
      description: Champs acceptés par PATCH /products/{ref}. Tout autre champ est ignoré.
      properties:
        name:
          type: string
          maxLength: 255
        ref:
          type: string
          maxLength: 255
          description: Référence du produit (SKU).
        external_id:
          type: string
          maxLength: 255
          description: Identifiant du produit chez le vendeur connecté (identifiant de déclinaison pour PrestaShop).
        slug:
          type: string
          maxLength: 255
          description: Slug du produit.
        description:
          type: string
          maxLength: 255
          description: Facultative.
        id_category:
          type: integer
        quantity:
          type: integer
        price:
          type: number
        tax:
          type: number
          enum:
            - 0
            - 0.2
            - 0.055
            - 0.1
            - 0.021
            - 0.21
            - 0.06
        active:
          type: boolean
        virtual_product:
          type: boolean
        frequencies:
          type: array
          items:
            type: object
            required:
              - interval
              - interval_count
            properties:
              interval:
                type: string
                enum:
                  - month
                  - week
                  - day
              interval_count:
                type: integer
                minimum: 1
                maximum: 28
      required:
        - name
        - ref
        - price
      example:
        ref: "REFABOPRODUIT"
        name: "Super nom produit"
        price: "17.50"
        description: "Petite description produit"
        tax: "0.2"
        frequencies:
          - interval: "month"
            interval_count: 2
    ProductEntityCreation:
      type: object
      description: Champs acceptés par POST /products. Tout autre champ est ignoré.
      properties:
        name:
          type: string
          maxLength: 255
        ref:
          type: string
          maxLength: 255
          description: Référence du produit (SKU).
        external_id:
          type: string
          maxLength: 255
          description: Identifiant du produit chez le vendeur connecté (identifiant de déclinaison pour PrestaShop).
        slug:
          type: string
          maxLength: 255
          description: "Ignoré : un slug aléatoire est attribué à chaque enregistrement par POST /products."
        description:
          type: string
          maxLength: 255
          description: Facultative. Recopiée dans la description courte et la meta description du produit.
        id_category:
          type: integer
        quantity:
          type: integer
        price:
          type: number
        tax:
          type: number
          enum:
            - 0
            - 0.2
            - 0.055
            - 0.1
            - 0.021
            - 0.21
            - 0.06
        active:
          type: boolean
        virtual_product:
          type: boolean
        frequencies:
          type: array
          items:
            type: object
            required:
              - interval
              - interval_count
            properties:
              interval:
                type: string
                enum:
                  - month
                  - week
                  - day
              interval_count:
                type: integer
                minimum: 1
                maximum: 28
      required:
        - name
        - ref
        - price
        - tax
      example:
        ref: "REFABOPRODUIT"
        name: "Super nom produit"
        price: "17.50"
        description: "Petite description produit"
        tax: "0.2"
        frequencies:
          - interval: "month"
            interval_count: 2
    ProductEntity:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
        position:
          type: integer
        short_description:
          type: [string, "null"]
          description: Description courte
        description:
          type: string
          maxLength: 255
        meta_title:
          type: string
          maxLength: 255
        meta_description:
          type: string
          maxLength: 255
        id_category:
          type: integer
        quantity:
          type: integer
        price:
          type: number
        tax:
          type: number
          enum:
            - 0
            - 0.2
            - 0.055
            - 0.1
            - 0.021
            - 0.21
            - 0.06
        active:
          type: boolean
        virtual_product:
          type: boolean
        salable:
          type: boolean
        gift_card:
          type: boolean
        gift_plan:
          type: string
        disable_seo:
          type: boolean
        ref:
          type: string
        external_id:
          type: string
        offers:
          type: array
          items:
            $ref: "#/components/schemas/OfferEntity"
        frequencies:
          type: array
          items:
            $ref: "#/components/schemas/FrequenceEntity"

    OfferEntity:
      type: object
      properties:
        id:
          type: integer
        quantity:
          type: integer
        percent_off:
          type: number
        price:
          type: number
        active:
          type: boolean
        product_id:
          type: integer
        deleted_at:
          type: string
        tenant_id:
          type: integer

    FrequenceEntity:
      type: object
      properties:
        id:
          type: integer
        interval:
          type: string
        interval_count:
          type: integer
        tenant_id:
          type: integer
        pivot:
          type: object
          properties:
            product_id:
              type: integer
            composable_frequence_id:
              type: integer

    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type: integer
        last_page:
          type: integer
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              label:
                type: string
              active:
                type: boolean
        path:
          type: string
        per_page:
          type: integer
        to:
          type: integer
        total:
          type: integer
    ErrorMessage:
      type: object
      description: Erreur sans détail par champ.
      properties:
        message:
          type: string
          description: Message d'erreur
    ValidationError:
      type: object
      properties:
        message:
          type: string
          description: Message d'erreur
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Détails des erreurs de validation
    Address:
      type: object
      properties:
        id:
          type: integer
          description: L'ID de l'adresse.
        user_id:
          type: integer
          description: L'ID de l'utilisateur auquel appartient cette adresse.
        company_name:
          type: string
          description: Nom de la société
        address:
          type: string
          description: L'adresse physique.
        address1:
          type: string
          description: Complément d'adresse.
        postcode:
          type: string
          description: Code postal de l'adresse.
        city:
          type: string
          description: Ville de l'adresse.
        phone:
          type: string
          description: Numéro de téléphone associé à l'adresse.
        first_name:
          type: string
          description: Prénom du destinataire de l'adresse.
        last_name:
          type: string
          description: Nom du destinataire de l'adresse.
        region_id:
          type: integer
          description: L'ID de la région de l'adresse.
        division:
          type: string
          description: Division associée à l'adresse.
        division_name:
          type: string
          description: Nom de la division associée à l'adresse.
        external_id:
          type: string
          description: Correspondance sur service tiers.
        deletable:
          type: boolean
          description: Indique si l'adresse peut être supprimée.
        country:
          type: object
          properties:
            id:
              type: integer
              description: L'ID du pays.
            name:
              type: string
              description: Nom du pays.
            alphaCode:
              type: string
              description: Code alpha du pays.

    Transporter:
      type: [object, "null"]
      description: Transporteur associé à la livraison.
      properties:
        id:
          type: integer
          description: ID du transporteur.
        countries:
          type: array
          description: Pays desservis.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
        plan_blacklisted:
          type: array
          description: Formules pour lesquelles le transporteur n'est pas proposé.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
        name:
          type: string
          description: Nom du transporteur.
        description:
          type: [string, "null"]
          description: Description du transporteur.
        price:
          type: number
          description: Prix TTC de la livraison.
        gift:
          type: boolean
          description: Proposé pour les cartes cadeaux.
        active:
          type: boolean
          description: Transporteur actif.
        shipped_count:
          type: [integer, "null"]
          description: Nombre d'envois du transporteur.
        type:
          type: [string, "null"]
          description: Type de transporteur.
        relayOptions:
          type: [object, "null"]
          description: Options de point relais (pilote et paramètres), null si le transporteur ne livre pas en point relais.
          properties:
            relayKey:
              type: [string, "null"]
            driver:
              type: string
              enum:
                - MondialRelay
                - ColissimoRelay
                - DpdRelay
            relayOptions:
              type: object
              additionalProperties: true

    User:
      type: object
      properties:
        id:
          type: integer
          description: L'ID de l'utilisateur.
        email:
          type: string
          description: Adresse e-mail de l'utilisateur.
        uuid:
          type: string
          description: UUID de l'utilisateur.
        refp:
          type: string
          description: Référence du parcours de l'utilisateur.
        has_active_subscription:
          type: boolean
          description: Indique si l'utilisateur a un abonnement actif.
        info:
          type: object
          properties:
            credits:
              type: string
              description: Crédits associés à l'utilisateur.
    Plan:
      type: object
      properties:
        id:
          type: integer
          description: L'ID du plan d'abonnement.
        uuid:
          type: string
          description: UUID du plan d'abonnement.
        name:
          type: string
          description: Nom du plan d'abonnement.
        short_name:
          type: string
          description: Nom court du plan d'abonnement.
        more:
          type: string
          description: Description détaillée du plan.
        image:
          type: string
          description: URL de l'image du plan.
        start_at:
          type: string
          format: date-time
          description: Date de début du plan.
        price:
          type: number
          description: Prix du plan.
        tax:
          type: number
          description: Taux de taxe applicable au plan.
        interval:
          type: string
          description: Intervalle de facturation du plan.
        interval_count:
          type: integer
          description: Nombre d'intervalle pour la facturation.
        shipped_count:
          type: integer
          description: Nombre de livraisons effectuées.
        position:
          type: integer
          description: Position du plan.
        engaged_interval:
          type: string
          description: Intervalle d'engagement du plan.
        engaged:
          type: boolean
          description: Indique si le plan est engagé.
        active:
          type: boolean
          description: Indique si le plan est actif.
    SubscriptionEntity:
      type: object
      properties:
        id:
          type: integer
          description: L'ID de l'abonnement.
        uuid:
          type: string
          description: UUID de l'abonnement.
        created_at:
          type: string
          format: date-time
          description: Date de création de l'abonnement.
        updated_at:
          type: string
          format: date-time
          description: Date de dernière mise à jour de l'abonnement.
        end_date:
          type: string
          format: date-time
          description: Date de fin de l'abonnement.
        engaged_date:
          type: string
          format: date-time
          description: Date d'engagement de l'abonnement.
        auto_pause_at:
          type: string
          format: date-time
          description: Date de mise en pause automatique de l'abonnement.
        start_date:
          type: string
          format: date-time
          description: Date de début de l'abonnement.
        active:
          type: boolean
          description: Indique si l'abonnement est actif.
        paused:
          type: boolean
          description: Indique si l'abonnement est en pause.
        next_billing:
          type: string
          format: date-time
          description: Date de la prochaine facturation de l'abonnement.
        update_transporter_at:
          type: string
          format: date-time
          description: Date de mise à jour du transporteur.
        relay:
          type: [object, 'null']
          additionalProperties: true
          description: Point relais associé à l'abonnement, null sans point relais.
        graceMonths:
          type: [integer, 'null']
          description: Nombre de mois de pause (période de grâce) de l'abonnement.
#        customerRevenue:
#          type: string
#          description: Revenu du client pour l'abonnement.
#        customerRefund:
#          type: string
#          description: Montant remboursé au client.
#        totalTransactionsSuccess:
#          type: integer
#          description: Nombre total de transactions réussies.
#        subTransactionsSuccess:
#          type: integer
#          description: Nombre de transactions réussies pour l'abonnement.
#        countTransactions:
#          type: integer
#          description: Nombre total de transactions.
#        customization_products:
#          type: array
#          description: Liste des produits de personnalisation associés à l'abonnement.
        retry_link:
          type: [string, 'null']
          description: >
            Lien de reprise de la dernière commande en attente de paiement de l'abonnement (renouvellement refusé),
            null s'il n'y a rien à régler. Le lien connecte le client à son compte : ne pas l'afficher ni le journaliser.
        pending_payment:
          type: [object, 'null']
          description: >
            Paiement en attente de l'abonnement : la dernière commande de renouvellement refusée, à régler par le lien
            de reprise. Null sans commande en attente ou sans lien de reprise.
          properties:
            order_id:
              type: integer
              description: Identifiant de la commande en attente.
            amount:
              type: number
              format: float
              description: Montant TTC à régler, celui que fait payer le lien de reprise.
            currency:
              type: [string, 'null']
              description: Code ISO 4217 de la devise, en majuscules (EUR).
            retry_link:
              type: string
              description: Lien de reprise de la commande, identique à retry_link.
            created_at:
              type: string
              format: date-time
              description: Date de création de la commande en attente.
            next_try:
              type: [string, 'null']
              format: date-time
              description: Date de la prochaine tentative de prélèvement automatique, null s'il n'y en a plus.
        interval:
          type: string
          description: Intervalle de facturation de l'abonnement.
        interval_count:
          type: integer
          description: Nombre d'intervalle pour la facturation de l'abonnement.
        switch_plan_uuid:
          type: string
          description: UUID du plan de changement.
        switch_plan_date:
          type: string
          format: date-time
          description: Date de changement de plan.
        referrer:
          type: string
          description: Source d'acquisition.
        address:
          $ref: "#/components/schemas/Address"
          description: Adresse de livraison de l'abonnement.
        user_uuid:
          type: string
          description: uuid de l'utilisateur.
        user_id:
          type: integer
          description: id de l'utilisateur.
        email:
          type: string
          description: email de l'utilisateur.
        display_interval:
          type: string
          description: Intervalle d'affichage de l'abonnement.
        display_content:
          type: string
          description: Contenu de l'abonnement sous forme de texte.
        external_fingerprint:
          type: string
          description: Emprinte de l'abonnement.
        content:
          type: array
          description: Contenu détaillé de l'abonnement.
          items:
            type: object
            properties:
              external_id:
                type: string
                description: Identifiant externe du produit, sans la partie personnalisation (ce qui précède le premier `_`).
              external_id_with_customizations:
                type: string
                description: Identifiant externe complet du produit, personnalisation comprise (identique à `external_id` pour un produit sans personnalisation).
              quantity:
                type: integer
                description: Quantité du produit.
              product_id:
                type: integer
                description: Identifiant du produit.
              subscription_id:
                type: integer
                description: Identifiant de l'abonnement.
              customizations:
                type: [array, object]
                description: Personnalisations du produit (tableau vide pour un produit sans personnalisation).
                items: {}
    OrderSchema:
      description: Schéma de données pour une commande
      type: object
      properties:
        order_id:
          description: ID de la commande
          type: integer
        user_id:
          description: ID de l'utilisateur
          type: integer
        user_uuid:
          description: UUID de l'utilisateur
          type: string
          format: uuid
        first_name:
          description: Prénom de l'utilisateur
          type: string
        last_name:
          description: Nom de l'utilisateur
          type: string
        phone:
          description: Numéro de téléphone de l'utilisateur
          type: string
        email:
          description: Adresse e-mail de l'utilisateur
          type: string
        status:
          description: Statut de la commande
          type: string
        created:
          description: Date de création de la commande
          type: string
          format: date-time
        items:
          description: Liste des articles de la commande
          type: array
          items:
            type: object
            properties:
              id:
                description: ID de l'article
                type: integer
              price:
                description: Prix HT de l'article, chaîne avec virgule décimale et deux décimales (ex. "12,50")
                type: string
                example: "12,50"
              tax:
                description: Taux de TVA applicable
                type: string
              quantity:
                description: Quantité de l'article commandée
                type: integer
              name:
                description: Nom de l'article
                type: string
              type:
                description: Type de l'article (par exemple, produit ou plan)
                type: string
              external_id:
                description: id du vendor connecté (id declinaison pour prestashop)
                type: string
              ref:
                description: Reference de l'article
                type: string

        shipping:
          description: Frais de livraison
          type: string
        count:
          description: Nombre total d'articles dans la commande
          type: integer
        total_tax_paid:
          description: Montant total des taxes payées, chaîne avec virgule décimale (ex. "2,08")
          type: string
          example: "2,08"
        total_discount_inc:
          description: Montant total de la remise incluse, chaîne avec virgule décimale (ex. "0,00")
          type: string
          example: "0,00"
        total_paid:
          description: Montant total payé, chaîne avec virgule décimale (ex. "12,50"), null si non renseigné
          type: [string, 'null']
          example: "12,50"
        total_shipping_paid:
          description: Frais de livraison totaux payés, chaîne avec virgule décimale (ex. "4,90")
          type: string
          example: "4,90"
        created_at:
          description: Date et heure de création de la commande
          type: string
          format: date-time
        coupon:
          description: Premier coupon appliqué à la commande (objet), ou tableau vide si aucun coupon
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              maxItems: 0
        subscription_uuid:
          description: UUID de l'abonnement associé (le cas échéant)
          type: string
        next_try:
          description: Prochaine tentative (le cas échéant)
          type: string
          format: date-time
        retry_link:
          description: "Lien de reprise du paiement de la commande, null s'il n'y en a pas. Le lien connecte le client à son compte : ne pas l'afficher ni le journaliser."
          type: [string, 'null']
        updated_at:
          description: Date et heure de dernière mise à jour de la commande
          type: string
          format: date-time
        paid_transaction_id:
          description: id transaction payée
          type: string
        paid_class_key:
          description: >-
            Moyen de paiement (clé de classe) de la transaction payée, par exemple `StripeCreditCard`, `PayPlugCreditCard`, `MollieCreditCard`, `PaypalVault`, `GoCardlessDirectDebit`.
          type: string
        prestashop_order_id:
          description: Correspondance commande PrestaShop
          type: [integer, 'null']
        prestashop_cart_id:
          description: Panier PrestaShop de la commande (tunnel ou renouvellement)
          type: [integer, 'null']
        payment_status:
          description: >-
            État du paiement. paid : une transaction est payée ; pending : paiement PayPal accepté mais pas encore
            encaissé (prélèvement bancaire), la commande est terminée sans être payée ; failed : dernière transaction en
            échec ; null : aucune transaction, ou renouvellement Mollie dont l'issue n'est pas encore confirmée (commande
            in_process, transaction au détail pending). Ne pas confondre avec pending_payment d'un abonnement (renouvellement
            refusé à régler).
          type: [string, 'null']
          enum: [paid, pending, failed, null]
        payment_class_key:
          description: >-
            Moyen de paiement (clé de classe) de la dernière transaction, payée ou non, par exemple
            `StripeCreditCard`, `PayPlugCreditCard`, `MollieCreditCard`, `PaypalVault`, `GoCardlessDirectDebit`.
          type: [string, 'null']
    UserSchema:
      type: object
      properties:
        id:
          type: integer
          description: ID de l'utilisateur.
        email:
          type: string
          format: email
          description: Adresse e-mail de l'utilisateur.
        uuid:
          type: string
          format: uuid
          description: UUID de l'utilisateur.
        refp:
          type: string
          description: Lien de parrainage de l'utilisateur.
        has_active_subscription:
          type: boolean
          description: Indique si l'utilisateur a un abonnement actif.
        info:
          type: [object, array, "null"]
          description: Informations complémentaires enregistrées sur l'utilisateur (commentaires), null si aucune.
        external_id:
          type: string
          description: ID externe de l'utilisateur.
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Liste des adresses de l'utilisateur.
        customerRevenue:
          type: string
          description: Revenu du client (payé moins remboursé), chaîne formatée avec point décimal et virgule comme séparateur de milliers.
          example: "1,234.56"
        customerRefund:
          type: string
          description: Montant remboursé au client, chaîne formatée avec point décimal et virgule comme séparateur de milliers.
          example: "0.00"
        totalTransactionsSuccess:
          type: integer
          description: Total des transactions réussies.
    RebillErrorLogsSchema:
      type: object
      description: Schéma de données pour une erreur de rebill. Tous les champs sont toujours présents, mais certains peuvent être null selon le type d'erreur.
      properties:
        id:
          type: integer
          description: ID de l'erreur de rebill
        type:
          type: string
          description: Type d'erreur
          enum:
            - api
            - partial
            - failed
        created_at:
          type: string
          description: Date de création de l'erreur, au format `Y-m-d H:i:s` (ex. "2026-01-15 08:30:00"), sans fuseau horaire
          example: "2026-01-15 08:30:00"
        subscription_id:
          type: [string, 'null']
          description: UUID de l'abonnement (malgré le nom du champ, ce n'est pas l'identifiant numérique), null si l'erreur n'est rattachée à aucun abonnement
        order_id:
          type: [integer, 'null']
          description: ID de la commande Ciklik
        error_code:
          type: [integer, 'null']
          description: Code d'erreur
        error_message:
          type: [string, 'null']
          description: Message d'erreur
        status:
          type: [string, 'null']
          description: Statut de la commande
        subscription_url:
          type: [string, 'null']
          description: URL de l'abonnement dans l'interface d'administration
        order_url:
          type: [string, 'null']
          description: URL de la commande dans l'interface d'administration
        email:
          type: [string, 'null']
          description: Email du client
        phone:
          type: [string, 'null']
          description: Téléphone du client
        address:
          type: [string, 'null']
          description: Adresse du client
        address1:
          type: [string, 'null']
          description: Complément d'adresse du client
        postcode:
          type: [string, 'null']
          description: Code postal du client
        city:
          type: [string, 'null']
          description: Ville du client
        country:
          type: [string, 'null']
          description: Pays du client
        first_name:
          type: [string, 'null']
          description: Prénom du client
        last_name:
          type: [string, 'null']
          description: Nom du client