# Cobranças

**Área:** Resumos

Consulte o resumo da sua carteira de cobranças: totais, distribuição por status, método, conversão por método, tipo operacional e tempo até pagamento.

`GET /v1/analytics/charges/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 cobranças

A página HTML mostra os quatro cards do resumo acima da tabela de cobranças: total, volume, faturamento pago e ticket médio. Ver mais métricas abre Total de cobranças por status, Total de cobranças por método de pagamento, Taxa de conversão por método, Distribuição por tipo de cobrança e Tempo até o pagamento.

A taxa de conversão só aparece com `dateBasis=created`. Com `paid` ou `created_and_paid` ela sai, porque as tentativas não pagas deixam o denominador.

O eixo `dateBasis` (`created`, `paid` ou `created_and_paid`) muda o título e o recorte. O período segue Semanal, Mensal, Semestral, Anual e Personalizado.

Os dados vêm de `GET /v1/analytics/demo/charges/summary`, sem token.

**Scopes necessários:** `charges/read` `pix.cob/read`

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

**Eixo de data (`dateBasis`)**

- Se `dateBasis` for omitido ou igual a `created`, serão retornadas as cobranças **criadas** no período
- Se `dateBasis` for igual a `paid`, serão retornadas as cobranças **pagas** no período
- Se `dateBasis` for igual a `created_and_paid`, serão retornadas as cobranças **criadas** e **pagas** no mesmo período
- Os parâmetros de início e fim (campos `startDate` e `endDate`) devem vir juntos. Se apenas um for enviado, será retornado um erro 400.
- `paidNetAmount` / `paidCount` exigem `status = PAID`. Com `dateBasis=paid` ou `created_and_paid`, tentativas não pagas ficam fora do denominador de conversão.

Case de uso:

_Como integrador, quero o resumo da minha carteira de cobranças por data, sem listar todas as cobranças._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `dateBasis` | não | created (default) \| paid \| created_and_paid |
| `startDate` | não | Início YYYY-MM-DD (envie com endDate) |
| `endDate` | não | Fim YYYY-MM-DD (envie com startDate) |
| `saleType` | não | RECURRING \| ONE_TIME; omitido inclui ambos |
| `productId` | não | Filtro por produto |
| `priceId` | não | Filtro por plano |
| `paymentType` | não | Afeta cards escalares e timeToPay |
| `status` | não | Afeta cards escalares |

### Resposta 200: 200

```json
{
  "accountId": "460851686",
  "startDate": "2026-10-01",
  "endDate": "2026-10-10",
  "dateBasis": "created", 
  "saleType": null, 
  "totalCharges": 120,
  "netAmount": "3379.83",
  "paidNetAmount": "520.00",
  "paidCount": 12,
  "averageTicket": "43.33",
  "conversionRate": "0.10",
  "timeToPay": {
    "paidCount": 7,
    "avgSeconds": 157885,
    "avgHours": "43.86",
    "medianSeconds": 40,
    "medianHours": "0.01",
    "p90Seconds": 1067008,
    "p90Hours": "296.39"
  },
  "statusBreakdown": {
    "items": [
      { "status": "PENDING", "chargeCount": 105, "netAmount": "2859.83", "percentage": "87.50" },
      { "status": "PAID", "chargeCount": 12, "netAmount": "520.00", "percentage": "10.00" },
      { "status": "CANCELED", "chargeCount": 3, "netAmount": "0.00", "percentage": "2.50" }
    ]
  },
  "paymentMethodBreakdown": {
    "items": [
      { "paymentType": "PIX", "chargeCount": 90, "netAmount": "800.00" },
      { "paymentType": "BOLETO", "chargeCount": 20, "netAmount": "2100.00" },
      { "paymentType": "CREDIT_CARD", "chargeCount": 10, "netAmount": "479.83" }
    ]
  },
  "paymentMethodConversionBreakdown": {
    "items": [
      { "paymentType": "PIX", "attemptCount": 90, "paidCount": 9, "conversionRate": "0.1000", "deduplicationApplied": false },
      { "paymentType": "BOLETO", "attemptCount": 20, "paidCount": 2, "conversionRate": "0.1000", "deduplicationApplied": false },
      { "paymentType": "CREDIT_CARD", "attemptCount": 8, "paidCount": 1, "conversionRate": "0.1250", "deduplicationApplied": true }
    ]
  },
  "chargeTypeBreakdown": {
    "items": [
      { "chargeType": "RECURRING", "chargeCount": 85, "netAmount": "2500.00", "percentage": "70.83" },
      { "chargeType": "MERGED_CYCLE", "chargeCount": 12, "netAmount": "420.00", "percentage": "10.00" },
      { "chargeType": "ONE_TIME_ITEM", "chargeCount": 23, "netAmount": "459.83", "percentage": "19.17" }
    ]
  }
}
```

#### Campos da resposta

| Campo | Descrição |
|---|---|
| `dateBasis` | Eixo resolvido |
| `saleType` | null = RECURRING + ONE_TIME |

### 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 400: 400 dateBasis inválido

```json
{
  "error": {
    "message": "dateBasis deve ser created, paid ou created_and_paid",
    "code": "INVALID_DATE_BASIS",
    "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-cobrancas  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json