Relatorios e indicadores

GET /v1/analytics/overview reune numa chamada so os indicadores da tela inicial do painel. Exige o escopo reports:read e vale para o ambiente da credencial.

curl "http://localhost:3333/v1/analytics/overview?period=7d" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Periodos

Os dias sao os do fuso da organizacao (veja Configuracoes): uma venda as 22h de Brasilia e do mesmo dia para quem vende, embora ja seja o dia seguinte em UTC. Cada total vem com o periodo anterior, que e a mesma janela deslocada em dias inteiros: em 7d, hoje ate as 14h compara com o mesmo dia da semana passada ate as 14h. Comparar com as ultimas 168 horas corridas faria a variacao oscilar com a hora da consulta, e nao com o negocio.

Valores em centavos; taxas em basis points (9240 = 92,40%).

Blocos da resposta

Os totais usam as mesmas definicoes de Transacoes:

• aprovado e o pagamento que o emissor aprovou em algum momento, inclusive se foi estornado, contestado ou cancelado depois;
• a taxa de aprovacao e aprovados sobre aprovados mais recusados - o que ainda esta em andamento fica fora - e vem null sem nenhuma decisao;
• volume e o valor capturado;
• recuperado separa fallback (aprovado em outra tentativa do mesmo pagamento) de retry (aprovado numa fatura cuja cobranca anterior falhou);
• estornos contam pela data do estorno, nao da venda.

Recusas

Cada item de declines.reasons traz o motivo canonico (reason), o rotulo e a acao recomendada pela tabela ABECS (label, retryAction), quantidade, valor, a quantidade no periodo anterior e a participacao no total (shareBps). O campo kind separa tres origens que pedem leituras diferentes:

A reversibilidade vem do que foi gravado em cada recusa, porque a mesma situacao muda de classe conforme a bandeira (o 57 e irreversivel na Visa e na Elo, reversivel na Mastercard). Quando as bandeiras divergem dentro do motivo, mixedReversibility vem true. Veja Retentativa e codigos de recusa.

Conectores

Contado por tentativa, e nao por pagamento: e o que mostra o adquirente que recusa mais, inclusive quando o fallback salvou a venda em outro. Cada conta traz tentativas, aprovadas, recusadas, falhas tecnicas, recuperadas, approvalRateBps contra previousApprovalRateBps, volume, latencia media, saude (health) e circuitOpen. Contas que autorizam aparecem mesmo sem tentativa; contas removidas aparecem enquanto tiverem tentativas no periodo.

Recorrencia

recurring nao depende do periodo: e a foto de agora. Traz o MRR (assinaturas active e past_due, convertidas para mes), o ARR (MRR vezes 12), as assinaturas por situacao (paying soma ativas e em atraso) e as faturas em aberto, a vencer em 7 dias, vencidas e incobraveis, com quantidade e valor. Sao as mesmas regras de GET /v1/billing/summary, em Assinaturas.

Alertas

alerts lista o que pede acao, do mais grave para o mais leve. A API devolve codigos, e nao textos: o painel monta a frase, e a sua integracao pode montar a dela.

Cada alerta traz count, e conforme o tipo: amount (valor envolvido), deltaBps (a variacao, nos alertas de queda), secondaryCount (quantos endpoints foram afetados, nos de webhook) e subject (a conta de conector).

Os limites minimos de volume existem de proposito: abaixo de cerca de 30 decisoes, uma recusa a mais move a taxa em pontos inteiros, e o alerta viraria ruido.

Outros indicadores

A visao geral nao substitui os resumos de cada assunto, que aceitam outros recortes: