openapi: 3.1.0
info:
  title: API Adapty Export Analytics
  version: 1.0.0
  description: |
    L'API Adapty Export Analytics vous permet d'exporter vos données d'analyse au format CSV ou JSON,
    vous offrant la flexibilité d'approfondir les métriques de performance de votre application, de personnaliser les rapports
    et d'analyser les tendances au fil du temps. Grâce à cette API, vous pouvez facilement extraire des données d'analyse détaillées,
    ce qui facilite le suivi, le partage et l'affinement de vos informations de données selon vos besoins.
servers:
  - url: https://api-admin.adapty.io
    description: Serveur de production
paths:
  /api/v1/client-api/metrics/analytics/:
    post:
      summary: Récupérer les données d'analyse
      description: "Récupère les données d'analyse pour obtenir des informations sur le comportement des utilisateurs et les métriques de performance, afin de les utiliser dans des graphiques.\n\nLes revenus de cet endpoint sont **basés sur les événements** : chaque valeur est attribuée à la **date de la transaction** — le jour où l'achat, le renouvellement ou le remboursement a eu lieu. Pour attribuer les revenus à la date d'installation de chaque utilisateur (par exemple, pour réconcilier avec Ads Manager), utilisez l'endpoint cohorte (`POST /api/v1/client-api/metrics/cohort/`).\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveAnalyticsData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsDataRequest'
            examples:
              basic:
                summary: Requête de données d'analyse de base
                value:
                  chart_id: "revenue"
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    country: ["us"]
                    attribution_channel: ["social_media_influencers"]
                  period_unit: "week"
                  segmentation: "attribution_campaign"
      responses:
        '200':
          description: Données d'analyse récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsDataResponse'
              example:
                data:
                  revenue:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
                  proceeds:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
                  net_revenue:
                    data: []
                    value: 0.0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: "revenue"
                    type: "multi"
                    default_aggregation: "sum"
                    description: "<div>Total money received from both subscriptions and one-time purchases. Does not include\nrevenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />\nFor example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />\nrevenue = 5*$10 + 1*$100 + 10*$50 = $650</div>"
                    metric_name: "Revenue"
                    is_json: true
                    unit: "USD"
                    recommended_period: null
            text/csv:
              schema:
                type: string
                description: Données d'analyse au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/metrics/cohort/:
    post:
      summary: Récupérer les données de cohorte
      description: "Récupère les données de cohorte pour suivre des groupes d'utilisateurs dans le temps.\n\nLes revenus de cet endpoint sont basés sur la **cohorte par date d'installation** : les revenus de chaque utilisateur sont attribués à leur **date d'installation**, et non à la date de la transaction. La réponse expose `total_revenue_usd` et `total_proceeds_usd`. Utilisez cet endpoint (plutôt que l'endpoint d'analyse) pour réconcilier les rapports internes avec Ads Manager, qui est également basé sur les cohortes/dates d'installation.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveCohortData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CohortDataRequest'
            examples:
              basic:
                summary: Requête de données de cohorte de base
                value:
                  filters:
                    date: ["2024-04-01", "2024-09-30"]
                    store: ["app_store"]
                    country: ["us"]
                  period_unit: "month"
                  period_type: "renewals"
                  value_type: "absolute"
                  value_field: "subscriptions"
      responses:
        '200':
          description: Données de cohorte récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CohortDataResponse'
              example:
                data:
                  - segment_start_date: "2024-04-01"
                    type: "total"
                    title: "Total"
                    total_installs: 0
                    total_subscriptions: 0
                    total_paid_subscribers: 0
                    total_revenue_usd: 0.0
                    total_proceeds_usd: 0.0
                    total_net_revenue_usd: 0.0
                    total_anrpas_usd: 0.0
                    total_appas_usd: 0.0
                    total_arpas_usd: 0.0
                    total_anrppu_usd: 0.0
                    total_apppu_usd: 0.0
                    total_arppu_usd: 0.0
                    total_anrpu_usd: 0.0
                    total_appu_usd: 0.0
                    total_arpu_usd: 0.0
                    predict: null
                    values:
                      - arpas_usd: 0.0
                        appas_usd: 0.0
                        anrpas_usd: 0.0
                        anrppu_usd: 0.0
                        apppu_usd: 0.0
                        arppu_usd: 0.0
                        anrpu_usd: 0.0
                        appu_usd: 0.0
                        arpu_usd: 0.0
                        installs: 0
                        period: 1
                        revenue_usd: 0.0
                        proceeds_usd: 0.0
                        net_revenue_usd: 0.0
                        revenue_relative: 0.0
                        proceeds_relative: 0.0
                        net_revenue_relative: 0.0
                        subscriptions: 0
                        subscriptions_relative: 0.0
                        subscribers: 0
                        subscribers_relative: 0.0
                        currently_active_period: false
            text/csv:
              schema:
                type: string
                description: Données de cohorte au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/metrics/conversion/:
    post:
      summary: Récupérer les données de conversion
      description: "Récupère les données de conversion pour analyser les actions des utilisateurs et mesurer l'efficacité des efforts marketing dans le temps.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveConversionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionDataRequest'
            examples:
              basic:
                summary: Requête de données de conversion de base
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                  from_period: 1
                  to_period: "6+"
                  period_unit: "month"
                  date_type: "purchase_date"
                  segmentation: "country"
                  format: "json"
      responses:
        '200':
          description: Données de conversion récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionDataResponse'
              example:
                data: []
                value: 0.0
                value_from: 0
                value_to: 0
                compare_value_from: null
                compare_value_to: null
                title: "Conversion rate from Paid to more than 6 months"
                type: "multi"
                default_aggregation: "sum"
                description: "If Х - the number of the 1st payments taken during the selected date, and Y - the amount of the renewals that happened after the 6 months since the selected date from those 1st payments, then Conversion = (Y / X) * 100%. For example, we had 100 1st subscriptions of various products on the 1st of January and among them 20 renewed on the 1st week of July (the 25th payment). On the 8th of July, we open the chart and see the conversion of the 1st of January = (20 / 100) * 100% = 20%. Then 30 more subscribers of the 1st of January renewed by the start of August (the 8th payment). We open the chart on the 1st of August and see that the conversion of the 1st of January = ((20+30) / 100) * 100% = 50%. This number shows which part of those who had their 1st payment on the 1st of January converted to the period > 6 months with any number of payments by the current moment."
                metric_name: "from_paid_to_6_months_conversion"
                is_json: true
                unit: "percent"
                recommended_period:
                  date_from: "2018-04-29"
                  date_to: "2024-12-31"
                  period_unit: "month"
            text/csv:
              schema:
                type: string
                description: Données de conversion au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/metrics/funnel/:
    post:
      summary: Récupérer les données d'entonnoir
      description: "Récupère les données d'entonnoir pour suivre la progression des utilisateurs à travers les étapes spécifiques d'un processus de conversion.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveFunnelData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelDataRequest'
            examples:
              basic:
                summary: Requête de données d'entonnoir de base
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                    offer_category: ["promotional"]
                  period_unit: "quarter"
                  show_value_as: "absolute"
                  format: "csv"
      responses:
        '200':
          description: Données d'entonnoir récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunnelDataResponse'
              example:
                data:
                  - title: "Total"
                    type: "total"
                    values:
                      - period: -2
                        title: "Install"
                        value: 2
                        value_relative: 100.0
                        relative_changes: 0.0
                        following_changes:
                          title: "Drop off"
                          value: 2
                          value_relative: 100.0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
                      - period: -1
                        title: "Paywall displayed"
                        value: 0
                        value_relative: 0.0
                        relative_changes: 0.0
                        following_changes:
                          title: "Drop off"
                          value: 0
                          value_relative: 0.0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
            text/csv:
              schema:
                type: string
                description: Données d'entonnoir au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/metrics/ltv/:
    post:
      summary: Récupérer les données de valeur vie client (LTV)
      description: "Récupère les données LTV pour évaluer le potentiel de revenus à long terme des clients sur leur période d'engagement.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveLTVData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LTVDataRequest'
            examples:
              basic:
                summary: Requête de données LTV de base
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                    offer_category: ["introductory"]
                    store: ["app_store"]
                    country: ["us"]
                    attribution_source: ["appsflyer"]
                    attribution_status: ["organic"]
                    attribution_channel: ["social_media"]
                  period_unit: "quarter"
                  period_type: "renewals"
                  segmentation: "store_product_id"
                  format: "csv"
      responses:
        '200':
          description: Données LTV récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LTVDataResponse'
              example:
                revenue:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
                proceeds:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
                net_revenue:
                  data:
                    - title: "Total"
                      type: "total"
                      value: 0.0
                      values: []
                      cohort_size: 0
                  description: "<div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.\n It's an actual, not predicted LTV.\n <a target=\"_blank\" rel=\"noopener noreferrer\" href='https://adapty.io/docs/ltv'> Read more</a>.</div>"
                  value: 0.0
                  unit: "USD"
                  title: "LTV"
            text/csv:
              schema:
                type: string
                description: Données LTV au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/metrics/retention/:
    post:
      summary: Récupérer les données de rétention
      description: "Récupère les données de rétention pour analyser la capacité d'un produit à maintenir l'engagement des utilisateurs dans le temps.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrieveRetentionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetentionDataRequest'
            examples:
              basic:
                summary: Requête de données de rétention de base
                value:
                  filters:
                    date: ["2024-01-01", "2024-12-31"]
                    compare_date: ["2023-01-01", "2023-12-31"]
                  period_unit: "quarter"
                  period_type: "renewals"
                  segmentation: "store_product_id"
                  format: "csv"
      responses:
        '200':
          description: Données de rétention récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionDataResponse'
              example:
                data: []
                title: "Subscription retention"
                metric_name: "Subscription retention"
                description: "Absolute value is the amount of users who entered the current step - subscribed for a trial or paid for a subscription. Relative is calculated as a percentage of these users among those who got a trial. So it starts with 100% for the trial step."
                value_type: null
            text/csv:
              schema:
                type: string
                description: Données de rétention au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

  /api/v1/client-api/exports/placements/:
    post:
      summary: Récupérer les informations de placement
      description: "Récupère des informations sur les placements de paywall ou d'onboarding : paywalls, segments, audiences et tests A/B. Cela peut vous aider à vous assurer que tout est correctement configuré sans avoir à ouvrir chaque placement séparément.\n\nLimite de débit : 2 requêtes par seconde."
      operationId: retrievePlacementInfo
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlacementInfoRequest'
            examples:
              basic:
                summary: Requête d'informations de placement de base
                value:
                  filters:
                    placement_type: "paywall"
      responses:
        '200':
          description: Informations de placement récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacementInfoResponse'
            text/csv:
              schema:
                type: string
                description: Informations de placement au format CSV
        '400':
          description: Requête incorrecte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Limite de débit dépassée. Maximum 2 requêtes par seconde par clé API.

components:
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Vous devez authentifier vos requêtes API avec votre clé API secrète en tant qu'en-tête Authorization.
        Vous pouvez la trouver dans les paramètres de l'application. Le format est `Api-Key {VOTRE_CLÉ_API_SECRÈTE}`,
        par exemple : `Api-Key secret_live_...`.

  schemas:
    AnalyticsDataRequest:
      type: object
      required:
        - chart_id
        - filters
      properties:
        chart_id:
          type: string
          enum: [revenue, mrr, arr, arppu, subscriptions_active, subscriptions_new, subscriptions_renewal_cancelled, subscriptions_expired, trials_active, trials_new, trials_renewal_cancelled, trials_expired, grace_period, billing_issue, refund_events, refund_money, non_subscriptions, arpu, installs]
          description: Indiquez le graphique dont vous avez besoin. Vous ne pouvez spécifier qu'un seul type de graphique par requête.
          example: "revenue"
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
          default: "month"
        date_type:
          type: string
          enum: [purchase_date, profile_install_date]
          description: Indiquez quelle date doit être considérée comme date d'entrée de l'utilisateur
          default: "purchase_date"
        segmentation:
          type: string
          description: Définit la base de la segmentation
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    CohortDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
          default: "month"
        period_type:
          type: string
          enum: [renewals, days]
          description: Analysez les données par renouvellements ou par jours
          default: "renewals"
        value_type:
          type: string
          enum: [absolute, relative]
          description: Indiquez comment les valeurs sont affichées
          default: "absolute"
        value_field:
          type: string
          enum: [revenue, arppu, arpu, arpas, subscribers, subscriptions]
          description: Indiquez le type de valeurs affichées
          default: "revenue"
        accounting_type:
          type: string
          enum: [revenue, proceeds, net_revenue]
          description: La méthode comptable utilisée
          default: "revenue"
        renewal_days:
          type: array
          items:
            type: integer
          description: Liste des jours depuis l'installation de l'application pour le type de cohorte period_type=days
        prediction_months:
          type: integer
          enum: [3, 6, 9, 12, 18, 24]
          description: Indiquez le nombre de mois de prédiction souhaité
          default: 12
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    ConversionDataRequest:
      type: object
      required:
        - filters
        - from_period
        - to_period
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        from_period:
          oneOf:
            - type: string
            - type: "null"
          description: L'état d'abonnement de départ de l'utilisateur dans la conversion
        to_period:
          type: string
          description: Le nouvel état d'abonnement de l'utilisateur après la conversion
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
          default: "month"
        date_type:
          type: string
          enum: [purchase_date, profile_install_date]
          description: Indiquez quelle date doit être considérée comme date d'entrée de l'utilisateur
          default: "purchase_date"
        segmentation:
          type: string
          description: Définit la base de la segmentation
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    FunnelDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
        show_value_as:
          type: string
          enum: [absolute, relative, both]
          description: Indiquez comment les valeurs sont affichées
        segmentation:
          type: string
          description: Définit la base de la segmentation
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    LTVDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
        period_type:
          type: string
          enum: [renewals, days]
          description: Analysez les données par renouvellements ou par jours
        segmentation:
          type: string
          description: Définit la base de la segmentation
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    RetentionDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/MetricsFilters'
        period_unit:
          type: string
          enum: [day, week, month, quarter, year]
          description: Indiquez l'intervalle de temps pour l'agrégation des données d'analyse
        segmentation:
          type: string
          description: Définit la base de la segmentation
        use_trial:
          type: boolean
          description: Valeur booléenne indiquant si un essai a été utilisé
          default: false
        format:
          type: string
          enum: [json, csv]
          description: Indiquez le format de fichier d'export
          default: "json"

    PlacementInfoRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          type: object
          required:
            - placement_type
          properties:
            placement_type:
              type: string
              enum: [paywall, onboarding]
              description: Filtrez les placements qui seront inclus dans la réponse

    PlacementInfoResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              developer_id:
                type: string
                description: Identifiant du placement
              placement_name:
                type: string
                description: Nom du placement
              audience_name:
                type: string
                description: Nom de l'audience
              segment_name:
                type: string
                description: Identifiant de l'audience
              cross_placement_ab_test_name:
                type: string
                nullable: true
                description: Nom du test A/B inter-placements
              ab_test_name:
                type: string
                nullable: true
                description: Nom du test A/B
              paywall_name:
                type: string
                description: Nom du paywall (retourné uniquement si placement_type est paywall)
              onboarding_name:
                type: string
                description: Nom de l'onboarding (retourné uniquement si placement_type est onboarding)

    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: Entrez la date ou la période pour laquelle vous souhaitez récupérer les données du graphique
        compare_date:
          type: array
          items:
            type: string
          description: Entrez la date ou la période de comparaison
        store:
          type: array
          items:
            type: string
          description: Filtrez par le store où l'achat a été effectué
        country:
          type: array
          items:
            type: string
          description: Filtrez par le code pays à 2 lettres où l'achat a eu lieu
        store_product_id:
          type: array
          items:
            type: string
          description: Identifiant unique d'un produit dans le store
        duration:
          type: array
          items:
            type: string
          description: Indiquez la durée de l'abonnement
        attribution_source:
          type: array
          items:
            type: string
          description: L'intégration source pour l'attribution
        attribution_status:
          type: array
          items:
            type: string
          description: Indique si l'attribution est organique ou non organique
        attribution_channel:
          type: array
          items:
            type: string
          description: Canal marketing ayant conduit à la transaction
        attribution_campaign:
          type: array
          items:
            type: string
          description: Campagne marketing ayant apporté la transaction
        attribution_adgroup:
          type: array
          items:
            type: string
          description: Groupe d'annonces d'attribution ayant apporté la transaction
        attribution_adset:
          type: array
          items:
            type: string
          description: Ensemble d'annonces d'attribution ayant conduit à la transaction
        attribution_creative:
          type: array
          items:
            type: string
          description: Éléments visuels ou textuels spécifiques d'une annonce ou d'une campagne, suivis pour mesurer leur efficacité
        offer_category:
          type: array
          items:
            type: string
          description: Indiquez les catégories d'offres pour lesquelles vous souhaitez récupérer des données
        offer_type:
          type: array
          items:
            type: string
          description: Indiquez les types d'offres pour lesquels vous souhaitez récupérer des données
        offer_id:
          type: array
          items:
            type: string
          description: Indiquez les offres spécifiques pour lesquelles vous souhaitez récupérer des données

    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer

    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer

    AnalyticsDataResponse:
      type: object
      description: Réponse contenant les données d'analyse pour le type de graphique demandé
      properties:
        data:
          type: object
          description: Objet contenant différents types de métriques (revenue, proceeds, net_revenue, etc.)
          additionalProperties:
            $ref: '#/components/schemas/MetricData'

    MetricData:
      type: object
      description: Données de métrique individuelle contenant les valeurs, les descriptions et les métadonnées
      properties:
        data:
          type: array
          description: Tableau de points de données pour la métrique (peut être vide pour les métriques agrégées)
          items:
            type: object
        value:
          type: number
          description: La valeur principale pour cette métrique
        value_from:
          type: number
          nullable: true
          description: Valeur de début pour la période (si applicable)
        value_to:
          type: number
          nullable: true
          description: Valeur de fin pour la période (si applicable)
        compare_value_from:
          type: number
          nullable: true
          description: Valeur de début pour la période de comparaison (si applicable)
        compare_value_to:
          type: number
          nullable: true
          description: Valeur de fin pour la période de comparaison (si applicable)
        title:
          type: string
          description: Titre d'affichage pour la métrique
        type:
          type: string
          description: Type de métrique (p. ex., 'multi', 'single')
        default_aggregation:
          type: string
          description: Méthode d'agrégation par défaut (p. ex., 'sum', 'average')
        description:
          type: string
          description: Description HTML expliquant ce que représente cette métrique et comment elle est calculée
        metric_name:
          type: string
          description: Nom interne de la métrique
        is_json:
          type: boolean
          description: Indique si les données sont au format JSON
        unit:
          type: string
          description: Unité de mesure (p. ex., 'USD', 'percent')
        recommended_period:
          type: object
          nullable: true
          description: Plage de dates recommandée pour cette métrique
          properties:
            date_from:
              type: string
              description: Date de début de la période recommandée
            date_to:
              type: string
              description: Date de fin de la période recommandée
            period_unit:
              type: string
              description: Unité de période recommandée (day, week, month, etc.)

    CohortDataResponse:
      type: object
      description: Réponse contenant les données d'analyse de cohorte montrant le comportement des utilisateurs dans le temps
      properties:
        data:
          type: array
          description: Tableau de segments de cohorte, chacun représentant un groupe d'utilisateurs ayant démarré durant la même période
          items:
            $ref: '#/components/schemas/CohortSegment'

    CohortSegment:
      type: object
      description: Un segment de cohorte représentant les utilisateurs ayant démarré durant la même période
      properties:
        segment_start_date:
          type: string
          description: La date de début de ce segment de cohorte
        type:
          type: string
          description: Type de segment ('total' pour les données agrégées, 'single' pour une cohorte individuelle)
        title:
          type: string
          description: Titre d'affichage pour ce segment de cohorte
        total_installs:
          type: integer
          description: Nombre total d'installations de l'application dans cette cohorte
        total_subscriptions:
          type: integer
          description: Nombre total d'abonnements dans cette cohorte
        total_paid_subscribers:
          type: integer
          description: Nombre total d'abonnés payants dans cette cohorte
        total_revenue_usd:
          type: number
          description: Revenu total en USD pour cette cohorte
        total_proceeds_usd:
          type: number
          description: Produits nets totaux en USD pour cette cohorte (après frais du store)
        total_net_revenue_usd:
          type: number
          description: Revenu net total en USD pour cette cohorte
        total_anrpas_usd:
          type: number
          description: Revenu net moyen par abonné actif (ANRPAS) total en USD
        total_appas_usd:
          type: number
          description: Produits nets moyens par abonné actif (APPAS) totaux en USD
        total_arpas_usd:
          type: number
          description: Revenu moyen par abonné actif (ARPAS) total en USD
        total_anrppu_usd:
          type: number
          description: Revenu net moyen par utilisateur payant (ANRPPU) total en USD
        total_apppu_usd:
          type: number
          description: Produits nets moyens par utilisateur payant (APPPU) totaux en USD
        total_arppu_usd:
          type: number
          description: Revenu moyen par utilisateur payant (ARPPU) total en USD
        total_anrpu_usd:
          type: number
          description: Revenu net moyen par utilisateur (ANRPU) total en USD
        total_appu_usd:
          type: number
          description: Produits nets moyens par utilisateur (APPU) totaux en USD
        total_arpu_usd:
          type: number
          description: Revenu moyen par utilisateur (ARPU) total en USD
        predict:
          type: object
          nullable: true
          description: Données de prédiction pour cette cohorte (si disponibles)
        values:
          type: array
          description: Tableau de valeurs par période montrant les performances de la cohorte dans le temps
          items:
            $ref: '#/components/schemas/CohortValue'

    CohortValue:
      type: object
      description: Valeur de période individuelle au sein d'un segment de cohorte affichant les métriques de performance pour une période donnée
      properties:
        arpas_usd:
          type: number
          description: Revenu moyen par abonné actif en USD pour cette période
        appas_usd:
          type: number
          description: Produits nets moyens par abonné actif en USD pour cette période
        anrpas_usd:
          type: number
          description: Revenu net moyen par abonné actif en USD pour cette période
        anrppu_usd:
          type: number
          description: Revenu net moyen par utilisateur payant en USD pour cette période
        apppu_usd:
          type: number
          description: Produits nets moyens par utilisateur payant en USD pour cette période
        arppu_usd:
          type: number
          description: Revenu moyen par utilisateur payant en USD pour cette période
        anrpu_usd:
          type: number
          description: Revenu net moyen par utilisateur en USD pour cette période
        appu_usd:
          type: number
          description: Produits nets moyens par utilisateur en USD pour cette période
        arpu_usd:
          type: number
          description: Revenu moyen par utilisateur en USD pour cette période
        installs:
          type: integer
          description: Nombre d'installations de l'application durant cette période
        period:
          type: integer
          description: Numéro de période (1 = première période, 2 = deuxième période, etc.)
        revenue_usd:
          type: number
          description: Revenu total en USD pour cette période
        proceeds_usd:
          type: number
          description: Produits nets totaux en USD pour cette période (après frais du store)
        net_revenue_usd:
          type: number
          description: Revenu net total en USD pour cette période
        revenue_relative:
          type: number
          description: Revenu en pourcentage par rapport à la première période (100% = première période)
        proceeds_relative:
          type: number
          description: Produits nets en pourcentage par rapport à la première période (100% = première période)
        net_revenue_relative:
          type: number
          description: Revenu net en pourcentage par rapport à la première période (100% = première période)
        subscriptions:
          type: integer
          description: Nombre d'abonnements durant cette période
        subscriptions_relative:
          type: number
          description: Abonnements en pourcentage par rapport à la première période (100% = première période)
        subscribers:
          type: integer
          description: Nombre d'abonnés durant cette période
        subscribers_relative:
          type: number
          description: Abonnés en pourcentage par rapport à la première période (100% = première période)
        currently_active_period:
          type: boolean
          description: Indique si cette période est la période actuellement active pour la cohorte

    ConversionDataResponse:
      type: object
      description: Réponse contenant les données de conversion montrant la progression des utilisateurs entre les états d'abonnement
      properties:
        data:
          type: array
          description: Tableau de points de données de conversion (peut être vide pour les métriques agrégées)
          items:
            type: object
        value:
          type: number
          description: La valeur du taux de conversion
        value_from:
          type: integer
          description: État d'abonnement de départ pour la conversion
        value_to:
          type: integer
          description: État d'abonnement cible pour la conversion
        compare_value_from:
          type: number
          nullable: true
          description: Valeur de début pour la période de comparaison
        compare_value_to:
          type: number
          nullable: true
          description: Valeur de fin pour la période de comparaison
        title:
          type: string
          description: Titre d'affichage décrivant le type de conversion
        type:
          type: string
          description: Type de métrique de conversion
        default_aggregation:
          type: string
          description: Méthode d'agrégation par défaut pour cette métrique
        description:
          type: string
          description: Explication détaillée du mode de calcul du taux de conversion
        metric_name:
          type: string
          description: Nom interne de la métrique de conversion
        is_json:
          type: boolean
          description: Indique si les données sont au format JSON
        unit:
          type: string
          description: Unité de mesure (généralement 'percent' pour les taux de conversion)
        recommended_period:
          type: object
          description: Plage de dates recommandée pour cette métrique de conversion
          properties:
            date_from:
              type: string
              description: Date de début de la période recommandée
            date_to:
              type: string
              description: Date de fin de la période recommandée
            period_unit:
              type: string
              description: Unité de période recommandée

    FunnelDataResponse:
      type: object
      description: Réponse contenant les données d'analyse d'entonnoir montrant la progression des utilisateurs à travers les étapes de conversion
      properties:
        data:
          type: array
          description: Tableau de segments d'entonnoir montrant les différentes étapes du processus de conversion
          items:
            $ref: '#/components/schemas/FunnelSegment'

    FunnelSegment:
      type: object
      description: Un segment d'entonnoir représentant une étape du processus de conversion
      properties:
        title:
          type: string
          description: Titre d'affichage pour ce segment d'entonnoir
        type:
          type: string
          description: Type de segment d'entonnoir ('total' pour les données agrégées)
        values:
          type: array
          description: Tableau de valeurs d'entonnoir montrant la progression à travers les étapes
          items:
            $ref: '#/components/schemas/FunnelValue'

    FunnelValue:
      type: object
      description: Valeur d'étape d'entonnoir individuelle montrant la progression des utilisateurs et le taux d'abandon
      properties:
        period:
          type: integer
          description: Numéro de période dans l'entonnoir (-2 = Installation, -1 = Paywall affiché, etc.)
        title:
          type: string
          description: Titre d'affichage pour cette étape de l'entonnoir
        value:
          type: integer
          description: Nombre d'utilisateurs ayant atteint cette étape
        value_relative:
          type: number
          description: Pourcentage d'utilisateurs ayant atteint cette étape par rapport à la première étape
        relative_changes:
          type: number
          description: Variation du taux de conversion par rapport à la période précédente
        following_changes:
          type: object
          description: Informations sur les utilisateurs ayant abandonné après cette étape
          properties:
            title:
              type: string
              description: Titre pour l'étape d'abandon
            value:
              type: integer
              description: Nombre d'utilisateurs ayant abandonné
            value_relative:
              type: number
              description: Pourcentage d'utilisateurs ayant abandonné
        churn_reason_title:
          type: string
          description: Titre décrivant la raison du désabonnement à cette étape
        churn_reasons:
          type: array
          description: Tableau des raisons spécifiques de désabonnement
          items:
            type: object
        values:
          type: array
          description: Valeurs imbriquées supplémentaires pour cette étape de l'entonnoir
          items:
            type: object

    LTVDataResponse:
      type: object
      description: Réponse contenant les données de valeur vie client (LTV) pour différents types de revenus
      properties:
        revenue:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculée à partir du revenu brut
        proceeds:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculée à partir des produits nets (après frais du store)
        net_revenue:
          $ref: '#/components/schemas/LTVMetric'
          description: LTV calculée à partir du revenu net

    LTVMetric:
      type: object
      description: Métrique LTV individuelle contenant les données de cohorte et les calculs
      properties:
        data:
          type: array
          description: Tableau de points de données LTV pour différentes cohortes
          items:
            $ref: '#/components/schemas/LTVData'
        description:
          type: string
          description: Description HTML expliquant comment la LTV est calculée
        value:
          type: number
          description: La valeur LTV globale
        unit:
          type: string
          description: Unité de mesure (généralement 'USD')
        title:
          type: string
          description: Titre d'affichage pour cette métrique LTV

    LTVData:
      type: object
      description: Point de données LTV individuel pour une cohorte spécifique
      properties:
        title:
          type: string
          description: Titre d'affichage pour ce point de données LTV
        type:
          type: string
          description: Type de données LTV ('total' pour les données agrégées)
        value:
          type: number
          description: Valeur LTV pour cette cohorte
        values:
          type: array
          description: Tableau de valeurs LTV par période
          items:
            type: object
        cohort_size:
          type: integer
          description: Nombre d'utilisateurs dans cette cohorte

    RetentionDataResponse:
      type: object
      description: Réponse contenant les données de rétention montrant l'engagement des utilisateurs dans le temps
      properties:
        data:
          type: array
          description: Tableau de points de données de rétention (peut être vide pour certains types de rétention)
          items:
            type: object
        title:
          type: string
          description: Titre d'affichage pour la métrique de rétention
        metric_name:
          type: string
          description: Nom interne de la métrique de rétention
        description:
          type: string
          description: Explication du mode de calcul de la rétention (valeurs absolues ou relatives)
        value_type:
          type: string
          nullable: true
          description: Type de valeur de rétention (absolue ou relative)

security:
  - apikeyAuth: []