VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Análises

Canais de aquisição

Pedidos e receita por canal de origem (UTM), campanhas de cada canal e o custo de mídia para calcular o ROAS.

Cada pedido guarda de onde o cliente veio: a plataforma lê os parâmetros de campanha (UTM), os identificadores de clique de anúncios e o site de origem, e classifica o pedido em um dos oito canais. Estas rotas mostram a receita por canal e por campanha, e permitem lançar à mão o custo de mídia de cada mês, o que habilita o cálculo do ROAS (retorno sobre o investimento em anúncios).

Relatório por canal

GET/api/v1/admin/analytics/channelsAdmin

Receita e ROAS por canal

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Padrão: 30 dias atrás. Valor inválido é ignorado em silêncio.
tostring
Último dia, YYYY-MM-DD, inclusive. Padrão: agora. Valor inválido é ignorado em silêncio.

Exemplo de requisição (channels)

bash
curl "$BASE_URL/api/v1/admin/analytics/channels?from=2026-09-01&to=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (channels)

200Relatório retornado
json
{
  "rows": [
    { "channel": "direct", "orders_count": 8, "revenue_cents": 492287, "aov_cents": 61535, "cost_cents": 0, "roas_bps": null }
  ],
  "direct_share_bps": 10000
}

Campos da resposta

rowsarray
Um item por canal que teve pedidos.
rows[].channelstring
directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm
Chave do canal.
rows[].orders_countinteger
Pedidos atribuídos ao canal.
rows[].revenue_centsinteger
Receita, em centavos.
rows[].aov_centsinteger
Ticket médio, em centavos.
rows[].cost_centsinteger
Custo de mídia lançado para o canal nos meses do intervalo, em centavos.
rows[].roas_bpsinteger|null
Receita dividida por custo, em pontos-base (30000 = ROAS de 3,0). null quando o custo é zero.
direct_share_bpsinteger
Participação do canal direct na receita, em pontos-base. Valor alto indica pouca atribuição (links sem UTM).

Erros (channels)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Campanhas de um canal

GET/api/v1/admin/analytics/channels/campaignsAdmin

Campanhas de um canal

Parâmetros de consulta

channelstringobrigatório
directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm
Canal a detalhar.
fromstring
Primeiro dia, YYYY-MM-DD. Padrão: 30 dias atrás. Valor inválido é ignorado em silêncio.
tostring
Último dia, YYYY-MM-DD, inclusive. Padrão: agora. Valor inválido é ignorado em silêncio.

Exemplo de requisição (campaigns)

bash
curl "$BASE_URL/api/v1/admin/analytics/channels/campaigns?channel=paid_social&from=2026-09-01&to=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (campaigns)

200Campanhas retornadas
json
{
  "rows": [
    { "campaign": "(sem campanha)", "orders_count": 8, "revenue_cents": 492287, "cost_cents": 0, "roas_bps": null }
  ]
}

Campos da resposta

rowsarray
Uma linha por campanha do canal.
rows[].campaignstring
Nome da campanha (utm_campaign) ou o texto (sem campanha). Esse texto vem em português do servidor.
rows[].orders_countinteger
Pedidos da campanha.
rows[].revenue_centsinteger
Receita, em centavos.
rows[].cost_centsinteger
Custo lançado para a campanha, em centavos.
rows[].roas_bpsinteger|null
ROAS em pontos-base; null sem custo.

Erros (campaigns)

StatusQuandoCorpo
400Falta channel.{"error":"channel query param required"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Ler custos de mídia

GET/api/v1/admin/analytics/channel-costsAdmin

Custos de mídia de um mês

Parâmetros de consulta

monthstring
Mês, YYYY-MM. Padrão: o mês atual.

Exemplo de requisição (ler custos)

bash
curl "$BASE_URL/api/v1/admin/analytics/channel-costs?month=2026-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler custos)

200Custos retornados
json
[
  { "month": "2026-10-01", "channel": "paid_social", "campaign": "black-friday", "cost_cents": 150000 }
]

Campos da resposta

[]array
Linhas de custo do mês; [] se não houver nenhuma.
[].monthstring
Primeiro dia do mês, YYYY-MM-DD.
[].channelstring
directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm
Chave do canal.
[].campaignstring
Campanha; vazio para o custo geral do canal.
[].cost_centsinteger
Custo, em centavos.

Erros (ler custos)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Gravar custos de mídia

PUT/api/v1/admin/analytics/channel-costsAdmin

Gravar custos de mídia

Corpo da requisição

[]arrayobrigatório

O corpo é uma lista JSON de linhas de custo.

monthstringobrigatório
Mês, YYYY-MM ou YYYY-MM-DD. Sempre gravado como o primeiro dia do mês.
channelstringobrigatório
directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm
Chave do canal. Maiúsculas e espaços nas pontas são normalizados.
campaignstring
Campanha. Vazio para o custo geral do canal.
cost_centsintegerobrigatório
Custo do mês, em centavos.

Exemplo de requisição (gravar custos)

bash
curl -X PUT "$BASE_URL/api/v1/admin/analytics/channel-costs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"month": "2026-10", "channel": "paid_social", "campaign": "black-friday", "cost_cents": 150000}]'

Resposta (gravar custos)

200Custos gravados
json
{
  "ok": true
}

Campos da resposta

okboolean
true quando todas as linhas foram gravadas.

Erros (gravar custos)

StatusQuandoCorpo
400Corpo que não é uma lista JSON.{"error":"invalid body"}
400channel fora das oito chaves válidas.{"error":"invalid channel","detail":"invalid channel: \"Google\" (must be one of: direct, paid_search, paid_social, organic_search, organic_social, referral, whatsapp, crm)"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}
A chave do canal precisa ser exata

Custos com um canal fora da lista são recusados com 400. Antes, um nome livre como "Google" era gravado e nunca aparecia no ROAS. Use sempre as chaves em inglês da tabela, não os rótulos exibidos no painel.

A gravação é por substituição de chave

Cada linha é identificada por mês, canal e campanha. Enviar a mesma combinação outra vez atualiza o valor; as demais linhas do mês não são tocadas. Não existe rota para apagar uma linha: grave cost_cents igual a 0.

Veja também

  • Lucro real
  • Coortes de retenção
Anterior
Lucro real
Próxima
Comparação com o mercado
Nesta página
  • Relatório por canal
  • Exemplo de requisição (channels)
  • Resposta (channels)
  • Erros (channels)
  • Campanhas de um canal
  • Exemplo de requisição (campaigns)
  • Resposta (campaigns)
  • Erros (campaigns)
  • Ler custos de mídia
  • Exemplo de requisição (ler custos)
  • Resposta (ler custos)
  • Erros (ler custos)
  • Gravar custos de mídia
  • Exemplo de requisição (gravar custos)
  • Resposta (gravar custos)
  • Erros (gravar custos)
  • Veja também