> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ephra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar relatório de conversão

> Devolve o desempenho do checkout da empresa autenticada no período: funil do visitante até o pagamento, abandono, tempo médio até pagar, conversão por meio e por dispositivo, e o melhor horário do dia. Use para descobrir em qual etapa a venda escapa.



## OpenAPI

````yaml /openapi.yaml get /v1/reports/conversion
openapi: 3.0.3
info:
  title: Ephra API
  description: >-
    API pública da Ephra: cobranças (PIX, cartão e boleto), transações, webhooks
    e a API do vendedor sobre catálogo, checkout, vendas, reembolsos,
    financeiro, crescimento e plataforma.


    **Limite de requisições.** 1000 requisições por minuto por IP de origem.
    Toda resposta traz `x-ratelimit-limit`, `x-ratelimit-remaining` e
    `x-ratelimit-reset` (segundos até a janela zerar); ao estourar o limite a
    resposta é `429` com `retry-after`.


    **Erros.** Toda falha responde o mesmo envelope: `{ "success": false,
    "message": "..." }`.
  version: 1.0.0
servers:
  - url: https://api.ephra.io
    description: Servidor de produção
security: []
tags:
  - name: Catálogo
    description: Produtos, ofertas, categorias e cupons — o que a empresa vende.
  - name: Checkout
    description: Checkouts, order bumps, upsells e links de pagamento.
  - name: Vendas
    description: Vendas, clientes, assinaturas e entregas já realizadas.
  - name: Reembolsos
    description: Pedidos de reembolso, contestações e o quiz de retenção.
  - name: Financeiro
    description: Saldo, saques, antecipações, taxas e extratos da empresa.
  - name: Crescimento
    description: Afiliados, coprodução, indicações, pixels e integrações de marketing.
  - name: Plataforma
    description: Conta, membros, chaves de API, webhooks e configurações gerais.
paths:
  /v1/reports/conversion:
    get:
      tags:
        - Crescimento
      summary: Consultar relatório de conversão
      description: >-
        Devolve o desempenho do checkout da empresa autenticada no período:
        funil do visitante até o pagamento, abandono, tempo médio até pagar,
        conversão por meio e por dispositivo, e o melhor horário do dia. Use
        para descobrir em qual etapa a venda escapa.
      operationId: getConversionReport
      parameters:
        - schema:
            type: string
            format: date-time
          in: query
          name: from
          required: false
          description: Início do período, em ISO 8601. Sem período, vale a janela padrão.
        - schema:
            type: string
            format: date-time
          in: query
          name: to
          required: false
          description: Fim do período, em ISO 8601.
      responses:
        '200':
          description: Relatório de conversão do período.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Sempre `true` em uma resposta bem-sucedida.
                  data:
                    type: object
                    properties:
                      conversionRate:
                        type: object
                        properties:
                          rate:
                            type: number
                            description: >-
                              Percentual de checkouts iniciados que viraram
                              venda.
                          completedSales:
                            type: number
                            description: Vendas concluídas no período.
                          changeVsPreviousPeriod:
                            type: number
                            description: >-
                              Variação em pontos percentuais contra o período
                              anterior.
                        required:
                          - rate
                          - completedSales
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Taxa de conversão do checkout.
                      checkoutsStarted:
                        type: object
                        properties:
                          total:
                            type: number
                            description: Checkouts iniciados no período.
                          visitorsPercentage:
                            type: number
                            description: >-
                              Percentual dos visitantes que chegou a iniciar o
                              checkout.
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação contra o período anterior.
                        required:
                          - total
                          - visitorsPercentage
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Volume de checkouts iniciados.
                      checkoutAbandonment:
                        type: object
                        properties:
                          rate:
                            type: number
                            description: Percentual de checkouts iniciados e abandonados.
                          reductionNote:
                            type: string
                            nullable: true
                            description: >-
                              Observação sobre a queda do abandono, quando
                              houve.
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação contra o período anterior.
                        required:
                          - rate
                          - reductionNote
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Abandono de checkout.
                      averageTimeToPay:
                        type: object
                        properties:
                          minutes:
                            type: number
                            description: >-
                              Minutos, na parte inteira do tempo médio até o
                              pagamento.
                          seconds:
                            type: number
                            description: Segundos restantes do tempo médio até o pagamento.
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação contra o período anterior.
                        required:
                          - minutes
                          - seconds
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Tempo médio entre iniciar o checkout e pagar.
                      conversionFunnel:
                        type: object
                        properties:
                          totalVisitors:
                            type: number
                            description: Visitantes no topo do funil.
                          steps:
                            type: array
                            items:
                              type: object
                              properties:
                                label:
                                  type: string
                                  description: Nome da etapa do funil.
                                value:
                                  type: number
                                  description: Quantos chegaram a esta etapa.
                                percentage:
                                  type: number
                                  description: Percentual do topo do funil que chegou aqui.
                              required:
                                - label
                                - value
                                - percentage
                              additionalProperties: false
                            description: Etapas do funil, do topo para a base.
                        required:
                          - totalVisitors
                          - steps
                        additionalProperties: false
                        description: Funil de conversão.
                      deviceDistribution:
                        type: object
                        properties:
                          devices:
                            type: array
                            items:
                              type: object
                              properties:
                                device:
                                  type: string
                                  description: Tipo de dispositivo.
                                percentage:
                                  type: number
                                  description: Fatia dos checkouts vinda deste dispositivo.
                              required:
                                - device
                                - percentage
                              additionalProperties: false
                            description: Distribuição por dispositivo.
                        required:
                          - devices
                        additionalProperties: false
                        description: De onde os compradores acessam.
                      paymentMethodConversion:
                        type: object
                        properties:
                          methods:
                            type: array
                            items:
                              type: object
                              properties:
                                method:
                                  type: string
                                  description: Meio de pagamento.
                                rate:
                                  type: number
                                  description: Taxa de conversão neste meio, em percentual.
                                transactions:
                                  type: number
                                  description: Transações neste meio.
                              required:
                                - method
                                - rate
                                - transactions
                              additionalProperties: false
                            description: Conversão por meio de pagamento.
                        required:
                          - methods
                        additionalProperties: false
                        description: Qual meio converte melhor.
                      conversionEvolution:
                        type: object
                        properties:
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação da conversão contra o período anterior.
                          points:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  description: Data do ponto, em ISO 8601.
                                rate:
                                  type: number
                                  description: Taxa de conversão no dia, em percentual.
                              required:
                                - date
                                - rate
                              additionalProperties: false
                            description: Série diária da taxa de conversão.
                        required:
                          - changeVsPreviousPeriod
                          - points
                        additionalProperties: false
                        description: Evolução da conversão no período.
                      mobileConversion:
                        type: object
                        properties:
                          rate:
                            type: number
                            description: Taxa de conversão no celular, em percentual.
                          trafficPercentage:
                            type: number
                            description: Fatia do tráfego que vem do celular.
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação contra o período anterior.
                        required:
                          - rate
                          - trafficPercentage
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Conversão no celular.
                      peakHour:
                        type: object
                        properties:
                          hour:
                            type: number
                            description: Hora do dia com maior conversão, de 0 a 23.
                          conversionRate:
                            type: number
                            description: Taxa de conversão nessa hora, em percentual.
                        required:
                          - hour
                          - conversionRate
                        additionalProperties: false
                        description: Melhor horário de conversão.
                      brazilConversion:
                        type: object
                        properties:
                          rate:
                            type: number
                            description: >-
                              Taxa de conversão do tráfego brasileiro, em
                              percentual.
                          transactionsPercentage:
                            type: number
                            description: Fatia das transações vinda do Brasil.
                          changeVsPreviousPeriod:
                            type: number
                            description: Variação contra o período anterior.
                        required:
                          - rate
                          - transactionsPercentage
                          - changeVsPreviousPeriod
                        additionalProperties: false
                        description: Conversão do tráfego brasileiro.
                    required:
                      - conversionRate
                      - checkoutsStarted
                      - checkoutAbandonment
                      - averageTimeToPay
                      - conversionFunnel
                      - deviceDistribution
                      - paymentMethodConversion
                      - conversionEvolution
                      - mobileConversion
                      - peakHour
                      - brazilConversion
                    additionalProperties: false
                required:
                  - success
                  - data
                additionalProperties: false
                description: Relatório de conversão do período.
              example:
                success: true
                data:
                  conversionRate:
                    rate: 42.7
                    completedSales: 97
                    changeVsPreviousPeriod: 3.4
                  checkoutsStarted:
                    total: 227
                    visitorsPercentage: 18.2
                    changeVsPreviousPeriod: 12
                  checkoutAbandonment:
                    rate: 57.3
                    reductionNote: Queda após o Pix virar padrão
                    changeVsPreviousPeriod: -3.4
                  averageTimeToPay:
                    minutes: 4
                    seconds: 12
                    changeVsPreviousPeriod: -18
                  conversionFunnel:
                    totalVisitors: 1247
                    steps:
                      - label: Visitou o checkout
                        value: 1247
                        percentage: 100
                      - label: Preencheu os dados
                        value: 227
                        percentage: 18.2
                      - label: Pagou
                        value: 97
                        percentage: 7.8
                  deviceDistribution:
                    devices:
                      - device: mobile
                        percentage: 71.4
                      - device: desktop
                        percentage: 28.6
                  paymentMethodConversion:
                    methods:
                      - method: pix
                        rate: 61.2
                        transactions: 57
                  conversionEvolution:
                    changeVsPreviousPeriod: 3.4
                    points:
                      - date: '2026-09-11T00:00:00.000Z'
                        rate: 44.1
                  mobileConversion:
                    rate: 39.8
                    trafficPercentage: 71.4
                    changeVsPreviousPeriod: 2.1
                  peakHour:
                    hour: 20
                    conversionRate: 58.3
                  brazilConversion:
                    rate: 43.1
                    transactionsPercentage: 98.6
                    changeVsPreviousPeriod: 1.2
        '401':
          description: Token ausente, inválido, expirado ou de empresa bloqueada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Sempre `false` em uma resposta de erro.
                  message:
                    type: string
                    description: Mensagem legível explicando a falha.
                required:
                  - success
                  - message
                additionalProperties: false
                description: Token ausente, inválido, expirado ou de empresa bloqueada.
              example:
                success: false
                message: Token inválido ou expirado
        '422':
          description: A requisição não passou na validação de schema.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Sempre `false` em uma resposta de erro.
                  message:
                    type: string
                    description: Mensagem legível explicando a falha.
                required:
                  - success
                  - message
                additionalProperties: false
                description: A requisição não passou na validação de schema.
              example:
                success: false
                message: 'name: Nome é obrigatório'
        '429':
          description: >-
            Requisições demais: o limite é de 1000 requisições por minuto por IP
            de origem. Espere o número de segundos do header `retry-after` e
            repita com recuo exponencial.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Sempre `false` em uma resposta de erro.
                  message:
                    type: string
                    description: Mensagem legível explicando a falha.
                required:
                  - success
                  - message
                additionalProperties: false
                description: >-
                  Requisições demais: o limite é de 1000 requisições por minuto
                  por IP de origem. Espere o número de segundos do header
                  `retry-after` e repita com recuo exponencial.
              example:
                success: false
                message: Muitas requisições. Tente novamente em breve.
          headers:
            retry-after:
              $ref: '#/components/headers/retry-after'
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
        '500':
          description: >-
            Falha interna ao processar a requisição. Repita; se persistir, abra
            chamado com o horário e a rota.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Sempre `false` em uma resposta de erro.
                  message:
                    type: string
                    description: Mensagem legível explicando a falha.
                required:
                  - success
                  - message
                additionalProperties: false
                description: >-
                  Falha interna ao processar a requisição. Repita; se persistir,
                  abra chamado com o horário e a rota.
              example:
                success: false
                message: Erro interno do servidor
      security:
        - bearerAuth: []
components:
  headers:
    retry-after:
      description: Segundos a esperar antes de repetir a requisição.
      schema:
        type: integer
    x-ratelimit-limit:
      description: Teto de requisições na janela (1000). Presente em toda resposta.
      schema:
        type: integer
    x-ratelimit-remaining:
      description: >-
        Quantas requisições ainda cabem na janela atual. Presente em toda
        resposta.
      schema:
        type: integer
    x-ratelimit-reset:
      description: Segundos até o contador da janela zerar. Presente em toda resposta.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````