# Assinaturas

**Área:** Resumos

Consulte o resumo da sua carteira de assinaturas e acompanhe assinaturas ativas, novas assinaturas, inadimplência, churn, recebidos, etc. Todas as métricas do resumo respondem ao filtro de data.

`GET /v1/analytics/subscriptions/summary`

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

## Cards de assinaturas

A página HTML mostra os cards do painel de assinaturas: MRR, ARR, assinaturas ativas e novas assinaturas. Ver mais métricas abre MRR inadimplente, taxa de arrecadação, emitidos, recebidos, churn e os gráficos Status de ciclos, Cobranças emitidas por método e Cobranças emitidas por plano.

Status de ciclos usa `statusBreakdown`. Cobranças emitidas por método usa `paymentMethodBreakdown`. Cobranças emitidas por plano usa `planBreakdown`. A barra de status segue `percentage`; as outras duas seguem `netAmount` sobre o total do gráfico.

Os filtros são Semanal, Mensal, Semestral, Anual e Personalizado, os mesmos do resumo do painel. Os dados vêm de `GET /v1/analytics/demo/subscriptions/summary`, sem token.

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

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

**O que vem**

- Os parâmetros de início e fim (campos `startDate` e `endDate`) indicam o período da consulta. Sem as duas datas, será considerado o mês atual.
- O período anterior e o respectivo crescimento relativo (campos `previousPeriod` e `growth`) apenas são retornados quando as datas de início e fim são enviadas; caso contrário, são `null`.
- O campo `growth.*` = `(atual − anterior) / anterior`, com 4 casas, indica o crescimento em relação ao mesmo período anterior, ou `null` se o anterior for zero.

**Para que serve**

- Resumo de assinaturas e KPIs de carteira
- Comparar o período atual com o mês anterior via `growth`

Case de uso:

_Como integrador, quero exibir o resumo da minha carteira de assinaturas sem montar agregações a partir dos ciclos e cobranças._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `startDate` | não | Início do período (YYYY-MM-DD). Envie junto com endDate |
| `endDate` | não | Fim do período (YYYY-MM-DD). Envie junto com startDate |
| `productId` | não | Filtra cards de período/ciclos pelo produto |
| `priceId` | não | Filtra cards de período/ciclos pelo plano |
| `paymentType` | não | PIX \| BOLETO \| CREDIT_CARD \| PIX_AUTOMATICO |

### Resposta 200: 200

```json
{
  "accountId": "474267606", 
  "startDate": "2026-09-01", 
  "endDate": "2026-09-30", 
  "asOfDate": "2026-09-30", 
  "totalPeriod": {
    "cycleCount": 85, 
    "netAmount": "42000.00" 
  },
  "received": {
    "cycleCount": 62,
    "netAmount": "38500.00"
  },
  "overdue": {
    "cycleCount": 12,
    "netAmount": "4800.00"
  },
  "dueToday": {
    "cycleCount": 5,
    "netAmount": "2100.00"
  },
  "upcoming": {
    "cycleCount": 38,
    "netAmount": "45200.00"
  },
  "activeSubscriptions": 156, 
  "mrr": "12345.67", 
  "arr": "148148.04", 
  "mrrAsOf": "2026-09-30", 
  "delinquentMrr": "2100.00", 
  "delinquentSubscriptions": 9,
  "newSubscriptions": 8,
  "canceledSubscriptions": 3,
  "churn": {
    "subscriptionCount": 1,
    "mrr": "149.79"
  },
  "previousPeriod": {
    "startDate": "2026-08-01",
    "endDate": "2026-08-30",
    "mrrAsOf": "2026-08-30",
    "mrr": "10000.00",
    "arr": "120000.00",
    "activeSubscriptions": 150,
    "newSubscriptions": 10,
    "churn": { "subscriptionCount": 2, "mrr": "100.00" },
    "delinquentMrr": "2000.00",
    "delinquentSubscriptions": 10
  },
  "growth": {
    "mrr": 0.2346,
    "activeSubscriptions": 0.04,
    "newSubscriptions": -0.2,
    "churn": { "subscriptionCount": -0.5, "mrr": 0.4979 },
    "delinquentMrr": 0.05,
    "delinquentSubscriptions": -0.1
  },
  "collectionRate": "0.72",
  "overdueAmount": "4800.00",
  "statusBreakdown": {
    "items": [
      {
        "status": "PAID",
        "cycleCount": 62,
        "netAmount": "38500.00",
        "percentage": "72.94"
      },
      {
        "status": "AWAITING_PAYMENT",
        "cycleCount": 23,
        "netAmount": "3500.00",
        "percentage": "27.06"
      }
    ]
  },
  "paymentMethodBreakdown": {
    "items": [
      { "paymentType": "PIX", "cycleCount": 52, "netAmount": "28000.00" },
      { "paymentType": "CREDIT_CARD", "cycleCount": 28, "netAmount": "11000.00" },
      { "paymentType": "BOLETO", "cycleCount": 5, "netAmount": "3000.00" }
    ]
  },
  "planBreakdown": {
    "items": [
      { "priceId": "price_pro", "planTitle": "Plano Pro", "cycleCount": 60, "netAmount": "32000.00" },
      { "priceId": "price_basic", "planTitle": "Plano Básico", "cycleCount": 25, "netAmount": "10000.00" }
    ]
  }
}
```

#### Campos da resposta

| Campo | Descrição |
|---|---|
| `accountId` | Conta resolvida pelo token |
| `startDate` | Início do período pedido |
| `endDate` | Fim do período pedido |
| `asOfDate` | Referência dos snapshots de recebíveis |
| `totalPeriod.cycleCount` | Ciclos PAID + AWAITING_PAYMENT no período |
| `totalPeriod.netAmount` | Soma líquida desses ciclos |
| `activeSubscriptions` | Estoque ACTIVE em mrrAsOf |
| `mrr` | MRR ACTIVE em mrrAsOf |
| `arr` | mrr * 12 |
| `mrrAsOf` | LEAST(endDate, hoje BRT) |
| `delinquentMrr` | Estoque overdue inteiro em mrrAsOf |

### 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"
  }
}
```


### Resposta 403: 403 Conta diferente do token

```json
{
  "error": {
    "message": "accountId diferente da conta do token",
    "code": "ACCOUNT_OVERRIDE_FORBIDDEN",
    "details": null,
    "timestamp": "2026-10-10T18:00:00.000Z"
  }
}
```


---

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