Métricas de faturas

Retorna métricas agregadas das Invoices da sua conta no período: contagens por status, totais em centavos, taxa de pagamento, série temporal diária (paid + created por dia), próximas 10 a vencer e 10 vencidas atuais. Útil pra dashboards e relatórios financeiros.

GET/v2/invoices/metrics

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

period'7d' | '30d' | '90d' | 'mtd' (query)opcional

Período da janela de análise. `7d` = últimos 7 dias, `30d` (default) = últimos 30 dias, `90d` = últimos 90 dias, `mtd` = mês até hoje.

Exemplo: 30d

Respostas

200

Métricas agregadas. Todos os valores monetários em centavos.

Campos do response:

period.days/from/to — janela analisada.
counts — quantidades por status no período.
amounts.paidTotal — soma de amountPaid em PAID.
amounts.pendingTotal — soma de amount em PENDING.
amounts.overdueTotal — soma de amount em OVERDUE + PENDING vencidas.
amounts.refundedTotal — soma de refundedAmount em REFUNDED.
rates.paymentRate / defaultRate — em % (paid / (paid + overdue) × 100).
daily[] — série diária preenchida (dias sem dados vêm com 0).
upcoming[] — próximas 10 PENDING a vencer (próximos 7 dias).
overdue[] — 10 invoices vencidas atualmente.

JSON

{
  "period": {
    "days": 30,
    "from": "2026-08-15T00:00:00.000Z",
    "to": "2026-09-14T00:00:00.000Z"
  },
  "counts": {
    "paid": 47,
    "pending": 12,
    "overdue": 3,
    "canceled": 2,
    "refunded": 1,
    "total": 65
  },
  "amounts": {
    "paidTotal": 230300,
    "pendingTotal": 58800,
    "overdueTotal": 14700,
    "refundedTotal": 3000
  },
  "rates": {
    "paymentRate": 94.0,
    "defaultRate": 6.0
  },
  "daily": [
    { "date": "2026-08-15", "paid": 2, "paidAmount": 9800, "created": 3 },
    { "date": "2026-08-16", "paid": 1, "paidAmount": 4900, "created": 2 }
  ],
  "upcoming": [
    {
      "id": "inv_222bbb",
      "description": "Mensalidade Outubro",
      "amount": 4900,
      "dueDate": "2026-09-20T00:00:00.000Z",
      "customerName": "Maria Souza",
      "daysUntilDue": 6
    }
  ],
  "overdue": [
    {
      "id": "inv_333ccc",
      "description": "Mensalidade Agosto",
      "amount": 4900,
      "dueDate": "2026-08-20T00:00:00.000Z",
      "customerName": "Pedro Costa",
      "daysOverdue": 25
    }
  ]
}

Exemplos

cURL

# Últimos 30 dias (default)
curl -X GET "https://api.pagnovo.com/v2/invoices/metrics" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

# Mês até hoje
curl -X GET "https://api.pagnovo.com/v2/invoices/metrics?period=mtd" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch("https://api.pagnovo.com/v2/invoices/metrics?period=30d", {
  headers: { Authorization: `Basic ${token}` },
});

const m = await res.json();
console.log(`Taxa de pagamento: ${m.rates.paymentRate}%`);
console.log(`Faturado: R$ ${(m.amounts.paidTotal / 100).toFixed(2)}`);
console.log(`Em aberto: R$ ${(m.amounts.pendingTotal / 100).toFixed(2)}`);
console.log(`Vencidas: ${m.counts.overdue} (R$ ${(m.amounts.overdueTotal / 100).toFixed(2)})`);