# MRR

**Área:** Séries temporais

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.

## Simulação de MRR

A página HTML traz o gráfico interativo com as séries MRR, Churn, MRRM, Inadimplência e Assinantes e os filtros Semanal, Mensal, Semestral, Anual e Personalizado.
Os dados vêm das rotas públicas `GET /v1/analytics/demo/...` em `https://api.validapay.com.br`, sem token.
Assinantes usa `activeSubscriptions` de `GET /v1/analytics/demo/mrr`.

## Bônus: MRR novo x recorrente

Gráfico empilhado do estoque de MRR nesta mesma rota: o que já existia na base e o que nasceu no mês.

O gráfico mensal pede `granularity=month` sem `startMonth` e sem `endMonth`. A API preenche os últimos 12 meses.

| Campo | No gráfico |
|---|---|
| `recurringMrr` | Base da barra. Assinaturas criadas antes daquele mês. |
| `newMrr` | Topo da barra. Assinaturas criadas naquele mês. |
| `mrr` | Altura 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.

```http
GET /v1/analytics/mrr?granularity=month
```

O clique no mês pede `granularity=day`, do dia 1 até o último dia do mês. No mês corrente, `endDate` é hoje. Nessa granularidade, `newMrr` autenticado é o acumulado do mês até o dia (MTD). A barra do dia é `max(0, newMrr[d] - newMrr[d - 1])` e a linha é o `newMrr` devolvido.

A página HTML simula as duas consultas em `GET /v1/analytics/demo/mrr`, sem token.

**Scopes necessários:** `subscriptions/read`

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._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `granularity` | não | month (default) ou day |
| `startMonth` | não | Início mensal YYYY-MM (com granularity=month) |
| `endMonth` | não | Fim mensal YYYY-MM (com granularity=month) |
| `startDate` | não | Início diário YYYY-MM-DD (com granularity=day) |
| `endDate` | não | Fim diário YYYY-MM-DD (com granularity=day) |

### Resposta 200: 200 Mensal

```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

| Campo | Descrição |
|---|---|
| `items.period` | YYYY-MM |
| `items.mrr` | Estoque ACTIVE no período |
| `items.newMrr` | Assinaturas criadas no mês |
| `items.recurringMrr` | Criadas antes do mês |
| `items.activeSubscriptions` | Assinaturas ativas no ponto (estoque) |
| `items.newSubscriptions` | Novas entre as ativas, criadas no mês |

### Resposta 200: 200 Diá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

| Campo | Descrição |
|---|---|
| `items.period` | YYYY-MM-DD |
| `items.newMrr` | Acumulado MTD (dia 1 até o period) |
| `items.activeSubscriptions` | Assinaturas ativas no ponto (estoque) |
| `items.newSubscriptions` | Novas entre as ativas, acumulado do dia 1 até o period |

### Resposta 400: 400 Intervalo 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"
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/get-mrr  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json