Dashboard

Séries temporais

MRR

Série temporal de MRR da carteira de assinaturas ativas. O mesmo endpoint serve as visões com granularidade mensal e diária.

GET/v1/analytics/mrr
Base URL Produção:https://api.validapay.com.br
Disponível apenas em produção. Esta rota não existe no sandbox: use credenciais e a URL de produção.

Valores monetários vêm como string decimal em reais (ex.: "12345.67").

Query

  • O campo granularity pode ser: month (default) ou day.
  • Se a granularidade for mensal, os campos startMonth e endMonth devem ser enviados no formato YYYY-MM. Se omitidos, serão considerados os últimos 12 meses. Se apenas um for enviado, será retornado o erro 400 INVALID_MONTH_RANGE.
  • Se a granularidade for diária, os campos startDate e endDate devem ser enviados no formato YYYY-MM-DD. Se omitidos, serão consideradas as últimas 4 semanas (últimos 28 dias). Se apenas um for enviado, será retornado o erro 400 INVALID_DATE_RANGE.
  • Não aceita productId / priceId / paymentType.

Identidade: o estoque de MRR é definido por mrr = recurringMrr + newMrr.

Série de assinantes

Não há rota própria para a série de assinantes. Ela sai desta mesma resposta, sem outra requisição, a partir de dois campos de cada item:

  • activeSubscriptions: assinaturas ativas naquele mês ou dia. É o valor do ponto na série.
  • newSubscriptions: quantas dessas ativas são novas. Na visão mensal, as criadas no mês; na diária, as criadas do dia 1 do mês até o period.

Para cada ponto, calcule:

  • Base = activeSubscriptions - newSubscriptions, os assinantes que já vinham de antes.
  • Variação = activeSubscriptions do ponto − activeSubscriptions do ponto anterior. O primeiro ponto fica sem variação.

Exemplo mensal: julho com 80 ativas e agosto com 87 ativas, das quais 12 novas. Em agosto, a base é 75 e a variação é +7.

Cada ponto é um retrato do estoque: não some os pontos do intervalo. Na visão diária, também não some newSubscriptions entre dias, porque o valor já vem acumulado no mês. Só entram assinaturas ACTIVE, a mesma base do MRR. Assinaturas em teste grátis, em atraso, inadimplentes ou pendentes ficam de fora. A contagem é de assinaturas, não de clientes. Os dois campos podem vir null em períodos sem contagem. Nesse caso, trate como dado ausente, não como zero.

Case de uso:

Como integrador, quero o gráfico de MRR mês a mês sem recalcular a partir das cobranças.

Séries temporais

Simulação de MRR

Abaixo você pode simular o consumo da série temporal descrita acima. Além disso, você pode simular as séries temporais descritas nas próximas seções.

MRR

Receita recorrente diária - Últimas 4 semanas

Carregando série demo…

Bônus: MRR novo x recorrente

Gráfico empilhado do estoque de MRR: o que já existia na base e o que nasceu no mês. Os dois valores saem deste mesmo GET /v1/analytics/mrr.

Como construir

O gráfico mensal não usa o filtro Semanal, Mensal ou Anual da série acima: ele pede granularity=month sem startMonth e sem endMonth. A API preenche os últimos 12 meses.

CampoNo gráfico
recurringMrrBase da barra. Assinaturas criadas antes daquele mês.
newMrrTopo da barra. Assinaturas criadas naquele mês.
mrrAltura da barra. Identidade: mrr = recurringMrr + newMrr.

Converta as strings decimais para número. Não recalcule a partição: desenhe os dois campos. O eixo Y começa em zero. No painel autenticado, a mesma URL leva Authorization: Bearer com escopo subscriptions/read.

Gráfico mensal

GET /v1/analytics/mrr?granularity=month
  • •Cada item de items[] é um mês. O rótulo do eixo X sai de period (YYYY-MM).
  • •Empilhe recurringMrr embaixo e newMrr em cima, no mesmo mês.
  • •O tooltip mostra os dois valores e a soma, que é o MRR do mês.

Diário do mês

O clique no mês pede o mesmo path com granularity=day, do dia 1 até o último dia do mês. No mês corrente, endDate é hoje.

GET /v1/analytics/mrr?granularity=day&startDate=2026-10-01&endDate=2026-10-11

Nessa granularidade, na rota autenticada, newMrr não é o valor nascido naquele dia. É o acumulado do mês até o dia (MTD). A barra do dia é a diferença para o ponto anterior, nunca negativa. A linha é o newMrr devolvido. Na fixture de GET /v1/analytics/demo/mrr, o campo diário é o valor do ponto, não o MTD; a simulação aplica a mesma conta do painel.

nascidoNoDia = max(0, newMrr[d] - newMrr[d - 1])

Métricas

Simulação MRR recorrente x MRR novo

O gráfico mensal chama a rota pública sem token. A soma da barra é o MRR do mês. Clique em um mês para buscar o diário de MRR novo.

MRR recorrente x MRR novo

MRR recorrente (criadas antes) + MRR novo (criadas no mês) = MRR do período.

Carregando série demo…

Clique no mês para ver o diário

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

subscriptions/read

Query Parameters

granularityopcional
month (default) ou day
month
startMonthopcional
Início mensal YYYY-MM (com granularity=month)
2026-02
endMonthopcional
Fim mensal YYYY-MM (com granularity=month)
2026-08
startDateopcional
Início diário YYYY-MM-DD (com granularity=day)
endDateopcional
Fim diário YYYY-MM-DD (com granularity=day)
const url = 'https://api.validapay.com.br/v1/analytics/mrr?granularity=month&startMonth=2026-02&endMonth=2026-08';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200Mensal▾
JSON
{
  "accountId": "12345",
  "items": [
    {
      "period": "2026-08", 
      "mrr": "12345.67", 
      "newMrr": "2800.00", 
      "recurringMrr": "9545.67", 
      "activeSubscriptions": 87, 
      "newSubscriptions": 12, 
      "currency": "BRL"
    }
  ]
}

Campos da resposta

accountIdstring
itemsarray[1]
200Diário▾
JSON
{
  "accountId": "12345",
  "items": [
    {
      "period": "2026-08-11", 
      "mrr": "12345.67",
      "newMrr": "2100.00", 
      "recurringMrr": "10245.67",
      "activeSubscriptions": 85, 
      "newSubscriptions": 9, 
      "currency": "BRL"
    }
  ]
}

Campos da resposta

accountIdstring
itemsarray[1]
400Intervalo de datas inválido▾
JSON
{
  "error": {
    "message": "startDate e endDate devem ser informados juntos",
    "code": "INVALID_DATE_RANGE",
    "details": null,
    "timestamp": "2026-10-10T18:00:00.000Z"
  }
}

← Anterior

Cobranças

Próximo →

MRRM