Resumos

Cobranças

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.

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.

Resumos

Simulação de cards de cobranças

A rota descrita nesta seção permite montar cards de resumos no seu painel, conforme a simulação abaixo.

Carregando resumo demo…

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

charges/readpix.cob/read

Query Parameters

dateBasisopcional

created (default) | paid | created_and_paid

created

startDateopcional

Início YYYY-MM-DD (envie com endDate)

2026-10-01

endDateopcional

Fim YYYY-MM-DD (envie com startDate)

2026-10-10

saleTypeopcional

RECURRING | ONE_TIME; omitido inclui ambos

productIdopcional

Filtro por produto

priceIdopcional

Filtro por plano

paymentTypeopcional

Afeta cards escalares e timeToPay

statusopcional

Afeta cards escalares

← Anterior

Assinaturas

MRR

const url = 'https://api.validapay.com.br/v1/analytics/charges/summary?dateBasis=created&startDate=2026-10-01&endDate=2026-10-10';

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

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

accountIdstring

startDatestring

endDatestring

dateBasisstring

Eixo resolvido

saleTypeobject

null = RECURRING + ONE_TIME

totalChargesnumber

netAmountstring

paidNetAmountstring

paidCountnumber

averageTicketstring

conversionRatestring

timeToPayobject

statusBreakdownobject

paymentMethodBreakdownobject

paymentMethodConversionBreakdownobject

chargeTypeBreakdownobject

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

400dateBasis 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"
  }
}

403Conta 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"
  }
}

← Anterior

Assinaturas

MRR