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

# Conversões

> Vendas atribuídas ao relacionamento com o cliente — o elo entre campanha, cliente e pedido

Uma **conversão** é uma venda que a Repediu atribuiu ao relacionamento com o cliente — na maioria das vezes, uma compra feita depois de o cliente receber uma mensagem de campanha. É a rota mais conectada da API: cada item referencia a campanha (`campaignId`), o cliente (`customerId`) e a venda (`saleId`).

<Info>
  `isReactivation` marca as conversões de **reativação**: clientes que estavam inativos e voltaram a comprar. `daysSinceMessage` diz quantos dias se passaram entre a mensagem e a compra, e `rfvStatusAtConversion` registra o status RFV do cliente **no momento da conversão** (o status atual pode ser outro).
</Info>

<Note>
  A resposta inclui `meta.attributionWindow` com a **janela de atribuição em dias por status RFV** — o prazo máximo entre mensagem e compra para a venda contar como conversão. Clientes em status diferentes têm janelas diferentes.
</Note>

Filtre pelo período com `from`/`to` (datas inclusivas nas duas pontas) e pagine com `cursor`/`nextCursor`, como nas demais rotas de dado bruto.

<Tip>
  Se você só precisa do **total** de conversões ou da **receita** do período, as [métricas prontas](/metricas/total-de-conversoes) respondem em uma chamada, sem paginar. Use esta rota quando precisar do detalhe por venda.
</Tip>

`campaignId` e `campaignMessageId` vêm `null` quando a conversão não está ligada a uma mensagem de campanha — filtre antes de agrupar por campanha. `saleId` é o mesmo `id` de `GET /od/v2/orders/{orderId}` (lá como string); `customerId` cruza com `/customers`, `/coupons` e `/ratings` da mesma loja. `meta.attributionWindow` tem as chaves `champion`, `loyal`, `promising`, `risk` e `lost`, cada uma com a janela em dias (inteiro). `channel` é o canal da mensagem que gerou a conversão (por exemplo `WhatsApp`, `SMS`, `Email`), ou `null`.

## Erros

| HTTP  | `code` no corpo | Quando acontece                                | O que fazer                                                            |
| ----- | --------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
| `400` | `BAD_REQUEST`   | `from`/`to` mal formatados ou janela invertida | Corrija o parâmetro indicado em `details`                              |
| `401` | `UNAUTHORIZED`  | Token ausente, inválido ou expirado            | Gere um novo token em [Obter token](/open-delivery/obter-token)        |
| `403` | `FORBIDDEN`     | Token sem o escopo exigido pela rota           | Confirme as permissões da credencial com a Repediu                     |
| `404` | `NOT_FOUND`     | Merchant inexistente **ou fora do escopo**     | Confirme o `id` em [Listar merchants](/open-delivery/listar-merchants) |

<CardGroup cols={2}>
  <Card title="Campanhas" icon="megaphone" href="/crm-parceiro/campanhas">
    O cadastro das campanhas referenciadas por `campaignId`.
  </Card>

  <Card title="Obter pedido" icon="receipt" href="/open-delivery/obter-pedido">
    O pedido completo por trás de cada `saleId` — itens, valores e modalidade.
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi.yaml GET /v1/stores/{merchantId}/conversions
openapi: 3.0.1
info:
  title: Repediu — API de integração
  description: >-
    API de integração da Repediu: rotas Open Delivery 2.0 (capabilities CRM),
    dado bruto do CRM do parceiro (/v1/stores) e métricas agregadas
    (/v1/stores/.../metrics). A autenticação usa o fluxo client_credentials: o
    token identifica a aplicação integradora e dá acesso a todos os
    estabelecimentos (merchants) que ativaram a integração.
  version: v2
servers:
  - url: https://public-api.repediu.com.br
    description: Produção
security:
  - Bearer: []
paths:
  /v1/stores/{merchantId}/conversions:
    get:
      tags:
        - CRM do parceiro
      summary: Conversões
      description: >-
        Vendas atribuídas ao relacionamento com o cliente. Cada item referencia
        a campanha (campaignId), o cliente (customerId) e a venda (saleId).
        meta.attributionWindow traz a janela de atribuição em dias por status
        RFV.
      operationId: listStoreConversions
      parameters:
        - $ref: '#/components/parameters/MerchantIdPath'
        - $ref: '#/components/parameters/CrmFrom'
        - $ref: '#/components/parameters/CrmTo'
        - $ref: '#/components/parameters/CrmCursor'
        - $ref: '#/components/parameters/CrmLimit'
      responses:
        '200':
          description: Página de conversões do período.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionListResponse'
              example:
                items:
                  - conversionId: 90311
                    saleId: 1107300
                    customerId: 18452
                    convertedAt: '2026-08-14T20:30:00'
                    amount: 75.9
                    isReactivation: true
                    campaignMessageId: 55701
                    campaignId: 12
                    channel: WhatsApp
                    daysSinceMessage: 2
                    rfvStatusAtConversion: Em risco
                nextCursor: null
                meta:
                  attributionWindow:
                    champion: 3
                    loyal: 3
                    promising: 3
                    risk: 7
                    lost: 7
        '400':
          $ref: '#/components/responses/InvalidDateRange'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/MerchantNotFound'
components:
  parameters:
    MerchantIdPath:
      name: merchantId
      in: path
      required: true
      description: Identificador (UUID) do merchant — o mesmo id de GET /od/v2/merchants.
      schema:
        type: string
        format: uuid
    CrmFrom:
      name: from
      in: query
      description: Início do período (data, inclusive). Deve ser anterior ou igual a to.
      schema:
        type: string
        format: date
    CrmTo:
      name: to
      in: query
      description: Fim do período (data, inclusive).
      schema:
        type: string
        format: date
    CrmCursor:
      name: cursor
      in: query
      description: >-
        Cursor opaco da próxima página, retornado em nextCursor. Omita na
        primeira chamada.
      schema:
        type: string
    CrmLimit:
      name: limit
      in: query
      description: Itens por página. Valores acima de 500 são limitados a 500.
      schema:
        type: integer
        format: int32
        default: 100
        maximum: 500
  schemas:
    ConversionListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ConversionItem'
        nextCursor:
          type: string
          nullable: true
          description: Cursor da próxima página. Null quando não há próxima página.
        meta:
          type: object
          properties:
            attributionWindow:
              type: object
              description: Janela de atribuição em dias, por status RFV do cliente.
              properties:
                champion:
                  type: integer
                  format: int32
                loyal:
                  type: integer
                  format: int32
                promising:
                  type: integer
                  format: int32
                risk:
                  type: integer
                  format: int32
                lost:
                  type: integer
                  format: int32
    ConversionItem:
      type: object
      properties:
        conversionId:
          type: integer
          format: int32
        saleId:
          type: integer
          format: int32
          nullable: true
          description: >-
            Venda convertida — mesmo id (numérico) do pedido em GET
            /od/v2/orders/{orderId}.
        customerId:
          type: integer
          format: int32
          nullable: true
        convertedAt:
          type: string
          format: date-time
        amount:
          type: number
          description: Valor da venda, em reais.
        isReactivation:
          type: boolean
          description: True quando o cliente estava inativo e voltou a comprar.
        campaignMessageId:
          type: integer
          format: int32
          nullable: true
        campaignId:
          type: integer
          format: int32
          nullable: true
          description: >-
            Campanha de origem. Null quando a conversão não veio de mensagem de
            campanha.
        channel:
          type: string
          nullable: true
          description: Canal da mensagem que gerou a conversão (WhatsApp, SMS, Email…).
        daysSinceMessage:
          type: integer
          format: int32
          nullable: true
        rfvStatusAtConversion:
          type: string
          nullable: true
          description: Status RFV do cliente no momento da conversão.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Código do erro (BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
            INTERNAL_SERVER_ERROR).
        message:
          type: string
        details:
          type: array
          nullable: true
          description: Lista de mensagens de validação, quando aplicável.
          items:
            type: string
  responses:
    InvalidDateRange:
      description: from/to mal formatados, janela invertida ou cursor inválido.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: BAD_REQUEST
            message: One or more validation errors occurred
            details:
              - from should be less than or equal to to
    Unauthorized:
      description: Token ausente, inválido ou expirado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: UNAUTHORIZED
            message: Invalid client credentials.
            details: null
    InsufficientScope:
      description: Token sem o escopo exigido pela rota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: FORBIDDEN
            message: The access token does not have the required scope.
            details: null
    MerchantNotFound:
      description: Merchant inexistente ou fora do escopo da aplicação.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: NOT_FOUND
            message: Merchant not found.
            details: null
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token de acesso emitido por POST /od/v2/oauth/token (fluxo
        client_credentials). Envie no header Authorization como `Bearer
        <token>`.

````