> ## 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.
# Como as rotas se relacionam
> O mapa da API: de onde vem o merchantId, quando usar métrica pronta ou dado bruto, e como cruzar as rotas entre si
A API da Repediu tem três famílias de rotas, e quase toda pergunta de negócio se responde combinando duas ou três delas. Esta página é o mapa: como ir de "quero saber X" até a chamada certa, sem tentativa e erro.
## Tudo começa pelo `merchantId`
Toda rota de CRM e de métricas trabalha sobre **uma loja por vez**, identificada pelo `merchantId` no caminho da URL. Esse identificador é o mesmo `id` retornado por [Listar merchants](/open-delivery/listar-merchants) — que por isso é sempre a **primeira chamada** de qualquer integração, seja Open Delivery ou CRM do parceiro.
Gere um token em [Obter token](/open-delivery/obter-token) e reutilize-o em todas as chamadas até expirar. O mesmo token vale para as três famílias de rotas.
Chame [Listar merchants](/open-delivery/listar-merchants) e guarde o `id` de cada estabelecimento. É esse valor que entra como `merchantId` nas URLs de CRM e métricas.
Se a pergunta já tem uma métrica pronta, use-a direto. Se precisa de detalhe linha a linha, vá ao dado bruto — as seções abaixo mostram como decidir.
Um `merchantId` inexistente **ou de loja que não ativou a sua integração** responde `404` com `{"code": "NOT_FOUND", "message": "Merchant not found."}` — a API não revela a existência de lojas fora do seu escopo, o mesmo comportamento de [Obter merchant](/open-delivery/obter-merchant).
## Métrica pronta ou dado bruto?
Antes de buscar dado bruto e calcular por conta própria, verifique se a pergunta já bate com uma das [métricas prontas](/metricas/total-de-conversoes): elas retornam o número calculado pela Repediu, numa única chamada, sem paginação. É mais simples, mais rápido e elimina o risco de o seu cálculo divergir do painel da Repediu.
| Se a pergunta é… | Use direto |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| Quantas conversões as campanhas geraram no período? | [Total de conversões](/metricas/total-de-conversoes) |
| Quanto de receita as campanhas geraram? | [Receita gerada](/metricas/receita-gerada) |
| Quantos clientes inativos voltaram a comprar? | [Clientes recuperados](/metricas/clientes-recuperados) |
| Quanto de receita veio de clientes recuperados? | [Receita recuperada](/metricas/receita-recuperada) |
| E de clientes que já eram ativos? | [Receita recorrente](/metricas/receita-recorrente) |
| Quantas mensagens de campanha foram enviadas? | [Mensagens enviadas](/metricas/mensagens-enviadas) |
| Qual o ticket médio da loja? | [Ticket médio](/metricas/ticket-medio) |
| Qualquer uma das acima, quebrada por campanha? | [Métricas por campanha](/metricas/conversoes-por-campanha) |
| Qual campanha converte melhor por mensagem enviada? | [Taxa de conversão por campanha](/metricas/taxa-de-conversao-por-campanha) |
O dado bruto entra em cena quando a pergunta **não** bate com nenhuma métrica: analisar clientes individualmente, cruzar conversões com avaliações, montar séries temporais próprias, alimentar um data warehouse. Aí você combina as rotas de [dado bruto](/crm-parceiro/clientes) usando os identificadores que elas compartilham.
## Os elos entre as rotas de dado bruto
Três identificadores costuram as rotas entre si. Pense neles como as chaves de um banco de dados:
Nasce em **Campanhas** e aparece em Conversões e Estatísticas de campanha.
Nasce em **Clientes** e aparece em Conversões, Cupons e Avaliações.
Aparece em Conversões, Cupons e Avaliações — e é o `id` do pedido no Open Delivery.
* **Análise de campanha**: o `campaignId` de [Campanhas](/crm-parceiro/campanhas) identifica a mesma campanha em [Conversões](/crm-parceiro/conversoes) (quando a venda veio de uma mensagem de campanha) e em [Estatísticas de campanha](/crm-parceiro/estatisticas-de-campanha). Juntando as três, você sabe o que a campanha é, quanto custou por dia e quanto vendeu.
* **Histórico por cliente**: o `customerId` de [Clientes](/crm-parceiro/clientes) identifica o mesmo cliente em [Conversões](/crm-parceiro/conversoes), [Cupons](/crm-parceiro/cupons) e [Avaliações](/crm-parceiro/avaliacoes). Como os dados de cliente são pseudonimizados (sem nome, telefone ou e-mail), esse é o elo para montar a jornada de um cliente sem expor dado pessoal.
* **Do CRM ao pedido completo**: o `saleId` presente em Conversões, Cupons e Avaliações é o mesmo `id` retornado por [Listar pedidos](/open-delivery/listar-pedidos). Quando precisar dos itens, valores e modalidade de uma venda específica, busque-a em [Obter pedido](/open-delivery/obter-pedido) com esse identificador.
### Receita técnica de join entre rotas
Chaves exatas para cruzar respostas (todas dentro do mesmo `merchantId`):
| Join | Campo na origem | Campo no destino |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ |
| Campanha → conversões | `/campaigns` → `items[].campaignId` | `/conversions` → `items[].campaignId` (null quando a conversão não veio de campanha) |
| Campanha → desempenho diário | `/campaigns` → `items[].campaignId` | `/campaign-stats` → `items[].campaignId` (uma linha por campanha × dia) |
| Cliente → conversões | `/customers` → `items[].customerId` | `/conversions` → `items[].customerId` |
| Cliente → cupons usados | `/customers` → `items[].customerId` | `/coupons` → `items[].customerId` |
| Cliente → avaliações | `/customers` → `items[].customerId` | `/ratings` → `items[].customerId` |
| Conversão → pedido completo | `/conversions` → `items[].saleId` | OD2 `GET /od/v2/orders/{orderId}` (o `saleId` é o `id` do pedido) |
| Cupom → pedido completo | `/coupons` → `items[].saleId` | idem |
| Avaliação → pedido completo | `/ratings` → `items[].saleId` | idem |
| Loja (CRM) → loja (OD2) | `merchantId` do path | OD2: `merchantId` no cliente e `storeId` no pedido |
Exemplos de perguntas compostas:
* **ROI de uma campanha**: `spend = Σ /campaign-stats.totalCost` (filtrando `campaignId`) e `revenue = Σ /conversions.amount` (filtrando o mesmo `campaignId`); ROI = (revenue − spend) / spend. Alternativa sem cálculo: `/metrics/revenue-generated-per-campaign` já entrega a receita por campanha.
* **Taxa de conversão de campanha**: preferir `/metrics/campaign-conversion-rate` (já vem em %). Manualmente: conversões com o `campaignId` ÷ Σ `sent` em `/campaign-stats` × 100.
* **Nota média dos clientes convertidos por campanha**: `/conversions` (filtrar `campaignId`) → juntar com `/ratings` por `saleId` → média de `stars`.
* **Ticket médio de clientes reativados**: `/conversions` com `isReactivation = true` → média de `amount`; ou juntar por `customerId` com `/customers` para ler `avgTicket` histórico de cada um.
Casos de borda:
* `campaignId` e `campaignMessageId` em `/conversions` são `null` para conversões atribuídas fora de campanha — filtre antes de agrupar por campanha.
* A janela de atribuição varia por status RFV: `meta.attributionWindow` em `/conversions` traz os dias considerados por status, nas chaves `champion`, `loyal`, `promising`, `risk`, `lost`.
* `/coupons` só retorna vendas com cupom preenchido — a ausência de um `saleId` ali não significa que a venda não existe.
* `/customers/{customerId}` responde `404` se o cliente não pertence àquela loja — o `customerId` não é global entre merchants. Atenção: o detalhe retorna um shape diferente da listagem, incluindo dados de contato.
* `saleId`, `customerId` e `campaignId` são numéricos nas rotas de CRM; no OD2 o `id` do pedido é string com o mesmo valor numérico — converta antes de comparar.
* Paginação de `/customers`, `/conversions`, `/campaigns`, `/ratings` e `/coupons` é por cursor opaco: repita a chamada com `cursor = nextCursor` até `nextCursor: null`. Não construa cursores manualmente. `/sales-daily` e `/campaign-stats` não paginam — retornam a janela inteira.
* Datas `from`/`to` são inclusivas nas duas pontas. Em `/sales-daily` e `/campaign-stats`, omitir ambas retorna os últimos 30 dias e a janela máxima é 12 meses. Nas métricas com período, `from` e `to` são **obrigatórios** (`average-ticket` e `campaign-conversion-rate` não aceitam período — cobrem o histórico completo).
## Exemplo fim a fim: receita de reativação no mês
Pergunta: *"quanto as campanhas de reativação trouxeram de receita este mês?"*
`GET /od/v2/merchants` — guarde o `id` da loja que você quer analisar.
`GET /v1/stores/{merchantId}/metrics/recovered-revenue?from=2026-08-01&to=2026-08-31` retorna `{ "value": ... }` — a resposta pronta, em uma chamada.
`GET /v1/stores/{merchantId}/conversions?from=2026-08-01&to=2026-08-31`, ficando com os itens de `isReactivation = true`. Para ver os itens e valores de cada venda, busque o pedido em `GET /od/v2/orders/{orderId}` usando o `saleId` da conversão.
O passo 2 sozinho resolve a maioria dos casos. Desça ao dado bruto apenas quando a pergunta exigir o detalhe — e, quando descer, confira se a soma bate com a métrica pronta: é um bom teste de sanidade da sua integração.