Visão geral do dashboard do Merchant

O endpoint de estatísticas por trás da tela inicial do dashboard do merchant — volumes de pedidos, taxas de aprovação e falha, dados de tendência e pedidos recentes de uma janela de datas.

A tela inicial do dashboard do Merchant é alimentada por um único endpoint de estatísticas. Dada uma janela de datas, ele retorna os números agregados que o dashboard renderiza como blocos de destaque (total de pedidos, taxa de aprovação, taxa de falha), além dos conjuntos de dados por trás de seus gráficos: uma série de tendência de pedidos, uma distribuição por status e os pedidos mais recentes.

Todos os números são calculados sobre pedidos — o registro comercial que agrupa uma ou mais tentativas de cobrança — não sobre transações individuais. Um pedido que falhou no primeiro provedor e teve sucesso em um fallback conta uma única vez, como um pedido bem-sucedido. Consulte Pedidos para saber como os pedidos se relacionam com as transações.

Os endpoints do Dashboard alimentam a Tokeflow Dashboard UI. Eles são autenticados por sessão: faça login para obter um JWT e envie-o como um token bearer. Eles não aceitam chaves de API sk_ ou pk_ — para relatórios programáticos, use a API pública.

O objeto de estatísticas

A resposta é um único objeto de estatísticas (sem envelope):

Campo	Tipo	Descrição
`total_orders`	number	Todos os pedidos na janela, incluindo tentativas rejeitadas. Este é o denominador de `approval_rate` e `failure_rate`.
`successful_orders`	number	Pedidos que atingiram autorização — `authorized`, `refunded`, `partially_refunded`, `charged_back` e `refund_pending`. Exclui tentativas `failed` e `canceled`, e pedidos ainda em andamento.
`approval_rate`	number	Pedidos autorizados / total, como uma porcentagem com 1 casa decimal.
`failure_rate`	number	Pedidos com falha / total, como uma porcentagem com 1 casa decimal.
`success_rate`	number	Alias de `approval_rate`, mantido para compatibilidade com clientes. Sempre igual a `approval_rate`.
`order_trend`	array	Série temporal da atividade de pedidos ao longo da janela — um `OrderTrendPointDto` por ponto. Alimenta o gráfico de tendência do dashboard.
`status_distribution`	array	Distribuição dos pedidos por status — um `StatusDistributionItemDto` por grupo de status. Alimenta o gráfico de distribuição do dashboard.
`recent_orders`	array	Os pedidos mais recentes na janela — um `RecentOrderDto` por pedido. Alimenta a lista de atividade recente do dashboard.

Os oito campos estão sempre presentes na resposta.

Um pedido conta como bem-sucedido assim que atinge autorização, mesmo que seja posteriormente estornado ou contestado — pedidos refunded, partially_refunded e charged_back ainda foram cobranças aprovadas. approval_rate e failure_rate não somam necessariamente 100: pedidos cancelados ou ainda em andamento não pertencem a nenhum dos dois grupos.

Endpoints

GET`/api/v1/merchant/dashboard/stats`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Retorna as estatísticas do dashboard do Merchant para a janela de datas solicitada.

Parâmetros de cabeçalho

Campo	Tipo	Obrigatório	Descrição
`x-merchant-id`	string	Sim	O Merchant sobre o qual gerar o relatório, prefixado com `mrc_`. Seleciona o contexto de Merchant ativo quando sua conta pertence a mais de um Merchant.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
`date_from`	string	Sim	Início da janela de relatório (timestamp ISO 8601, inclusivo).
`date_to`	string	Sim	Fim da janela de relatório (timestamp ISO 8601, inclusivo).

A interface do dashboard solicita predefinições comuns — últimos 7 dias, últimos 30 dias, mês até a data atual. Ao chamar o endpoint você mesmo, mantenha a janela o mais restrita possível para o seu caso de uso; os agregados são calculados sobre todos os pedidos no intervalo.

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/dashboard/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  --data-urlencode "date_from=2026-07-01T00:00:00Z" \
  --data-urlencode "date_to=2026-07-31T23:59:59Z"

Exemplo de resposta — 200 OK

{
  "total_orders": 59,
  "successful_orders": 42,
  "approval_rate": 71.2,
  "failure_rate": 8.5,
  "success_rate": 71.2,
  "order_trend": [],
  "status_distribution": [],
  "recent_orders": []
}

Os três arrays são exibidos vazios acima por brevidade. Em uma resposta real, order_trend traz um ponto por intervalo dentro da janela, status_distribution traz um grupo por status de pedido presente na janela, e recent_orders traz os pedidos mais recentes — cada item seguindo, respectivamente, os formatos OrderTrendPointDto, StatusDistributionItemDto e RecentOrderDto.

Neste exemplo, 42 de 59 pedidos atingiram autorização (42 / 59 = 71,2%) e 5 falharam completamente (5 / 59 = 8,5%); os pedidos restantes foram cancelados ou ainda estavam em andamento, portanto não contam para nenhuma das duas taxas.

Erros

HTTP	Causa típica
`400`	`date_from` / `date_to` ausente ou inválido.
`401`	Token de sessão ausente, inválido ou expirado — faça login novamente.
`403`	A conta da sessão não é membro do Merchant informado em `x-merchant-id`.

Consulte Erros para o formato de erro usado em toda a API.

Relacionados

Pedidos — o recurso que estas estatísticas agregam.
Transações — tentativas de cobrança individuais por trás de cada pedido.
Organizations e Merchants — como funciona a associação a um Merchant.
Convites do Dashboard — convide colegas de equipe para o dashboard.