Relatórios e indicadores

Esta pagina cobre dois grupos de indicadores, os dois com o escopo reports:read e validos para o ambiente da credencial:

• a visao geral, que reune numa chamada so os indicadores da tela inicial do painel (GET /v1/analytics/overview);
• os relatorios do menu Relatorios, cada um com periodo livre, filtros e exportacao em CSV (GET /v1/reports/{slug}), mais abaixo em Relatorios.

Visao geral

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.

Relatorios

O menu Relatorios do painel tem cinco relatorios. Todos aceitam periodo de ate 366 dias, devolvem linhas e total em JSON e exportam o mesmo conteudo em CSV. GET /v1/reports lista os relatorios com as colunas e os filtros de cada um; GET /v1/reports/{slug} gera o relatorio.

# JSON
curl "http://localhost:3333/v1/reports/approval?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

# CSV para planilha
curl "http://localhost:3333/v1/reports/approval?from=2026-10-01&to=2026-10-31&format=csv" \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -o aprovacao-outubro.csv

Periodo e filtros

Filtro que o relatorio nao tem e ignorado, e filters na resposta mostra o que valeu. Para o periodo:

• data vale no fuso da organizacao (veja Configuracoes) e inclui o dia inteiro nas duas pontas: from=2026-10-01&to=2026-10-31 traz outubro todo, inclusive a venda das 22h de 31/10 em Brasilia, que em UTC ja e novembro;
• instante com fuso e usado como veio, e o fim e exclusivo. Instante sem fuso e recusado, porque o servidor teria de adivinhar o fuso;
• sem from, o periodo e o dos "30 dias" da visao geral: 29 dias inteiros mais hoje ate agora. Assim o relatorio e a tela inicial batem para o mesmo recorte;
• mais de 366 dias, ou fim antes do inicio, responde 422.

Resposta

{
  "object": "report",
  "report": "approval",
  "title": "Aprovação por adquirente e bandeira",
  "environment": "sandbox",
  "currency": "BRL",
  "generatedAt": "2026-10-18T15:30:00.000Z",
  "period": {
    "from": "2026-10-01T03:00:00.000Z",
    "to": "2026-11-01T03:00:00.000Z",
    "days": 31,
    "timeZone": "America/Sao_Paulo"
  },
  "filters": { "connectorAccountId": null, "brand": null, "groupBy": "acquirer-brand" },
  "columns": [{ "key": "attempts", "label": "Tentativas", "type": "integer" }],
  "rows": [{ "acquirer": "Cielo - matriz", "brand": "Visa", "attempts": 100 }],
  "totals": { "attempts": 160 }
}

columns descreve cada coluna (key, label e type) e e a fonte da tabela do painel e do CSV. O type diz como ler o valor:

Colunas com csvOnly: true (ids e codigos canonicos) nao aparecem na tabela do painel, mas vem no JSON e no CSV. totals repete as colunas numericas com a soma do recorte; as taxas sao recalculadas sobre o total, nunca a media das linhas. Sem nenhuma linha, totals e null.

CSV

format=csv devolve text/csv pronto para abrir no Excel em portugues:

• UTF-8 com BOM, para os acentos do cabecalho sobreviverem;
• ; como separador de colunas e , como separador decimal;
• cabecalho em portugues, uma linha por linha do relatorio e, no fim, a linha Total;
• dinheiro em reais com duas casas e sem separador de milhar (1234,56), calculado a partir dos centavos inteiros, sem passar por ponto flutuante;
• taxa em percentual com duas casas (92,40); vazio quando nao ha base;
• texto que comeca com =, +, - ou @ (um nome de recebedor, por exemplo) ganha um apostrofo na frente, para a planilha nao executar como formula.

O arquivo sugerido e minstrel-relatorio-{slug}-{inicio}_{fim}.csv, com as datas no fuso da organizacao. O CSV e o JSON do mesmo pedido trazem os mesmos numeros.

Aprovacao por adquirente e bandeira

Contado por tentativa, como o cartao Conectores da visao geral, e agrupado por conta de adquirente e bandeira do cartao (groupBy troca para so conta ou so bandeira). Uma venda que o fallback aprovou em outra conta aparece como recusa na primeira e como aprovacao na segunda, que e o que mostra o adquirente que mais recusa.

Pix e boleto nao tem bandeira e ficam em none; cartao cuja bandeira o conector nao informou fica em unknown.

Recusas por motivo

A recusa final de cada transacao, a mesma contagem do cartao de motivos da visao geral, agrupada pelo motivo da tabela ABECS. A conta filtrada e a da ultima tentativa, que foi quem devolveu a resposta final.

Veja Retentativa e codigos de recusa.

Recuperacao por retentativa

Parte da primeira cobranca recusada de cada fatura dentro do periodo e acompanha o que aconteceu com a fatura depois, ate agora. Por isso o numero de uma fatura recusada ontem ainda pode mudar. Cada fatura termina em um destes estados:

Os valores sao o da cobranca recusada. recoveryRateBps e recuperadas sobre recuperadas mais perdidas: as em andamento ficam fora para nao derrubar a taxa de quem acabou de comecar a cobrar. secondCharge, thirdCharge e laterCharge dizem em qual cobranca da fatura a recuperacao aconteceu.

A visao geral conta de outro jeito: ela soma as vendas recuperadas aprovadas no periodo. Aqui o recorte e o das cobrancas recusadas no periodo.

MRR e churn

A ponte do MRR por plano: MRR no inicio, mais o novo, mais a expansao, menos a contracao, menos o perdido, igual ao MRR no fim. Cada assinatura cai em uma situacao so, entao a ponte fecha por construcao.

O MRR usa as mesmas regras do resumo de cobranca (veja Assinaturas): assinaturas anuais e trimestrais entram pelo equivalente mensal, arredondado por assinatura. Quando o periodo termina hoje, o MRR no fim e o da visao geral (assinaturas active e past_due), e uma assinatura unpaid conta como perdida. Para uma janela que terminou no passado, o fim e reconstituido pelas datas.

Nao ha tabela de historico de status: o estado do passado sai das datas de criacao, teste, pausa e encerramento, e o valor do passado, dos eventos subscription.updated que alteraram o valor. Uma assinatura pausada e ja retomada pode contar como ativa no passado. O churn deste relatorio usa como base quem pagava no inicio do periodo; o churnRateBps do resumo de cobranca usa quem paga hoje mais quem saiu em 30 dias, e por isso os dois nao coincidem.

Split e recebiveis

Uma linha por recebedor, com as divisoes de vendas capturadas no periodo (pela data da venda).

O liquido e estimado: a tarifa so existe depois que o adquirente liquida a divisao, e o Minstrel ainda nao concilia os repasses feitos. O relatorio mostra o que cabe a cada recebedor, nao o que ja foi pago. Veja Split.

Valores em reais (BRL), como na visao geral.

Outros indicadores

A visao geral e os relatorios nao substituem os resumos de cada assunto, que aceitam outros recortes: