Faturas e segunda via — API WebSystem Provider

Listar faturas

GET/faturasfinanceiro:leitura

Lista faturas, da mais recente para a mais antiga. As faturas em aberto já vêm com a segunda via.

Parâmetros (query)

Nome	Descrição
`cliente_id`	Faturas de um cliente.
`contrato_id`	Faturas de um contrato.
`situacao`	`aberta` (pendente + vencida), `pendente`, `vencida`, `paga`, `cancelada`, `estornada` ou `todas` (padrão).
`vencimento_de`, `vencimento_ate`	Período de vencimento, no formato `AAAA-MM-DD`.
`pagina`, `por_pagina`	Paginação.

curl "$API/faturas?cliente_id=5&situacao=aberta" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": [
    {
      "id": 77,
      "cliente_id": 5,
      "contrato_id": 10,
      "descricao": "Mensalidade 300 Mega",
      "situacao": "vencida",
      "tipo": "boleto",
      "valor": 99.9,
      "valor_atualizado": null,
      "valor_pago": 0,
      "vencimento": "2026-10-10",
      "emitida_em": "2026-09-25T10:00:00.000Z",
      "pago_em": null,
      "segunda_via": {
        "link_pagamento": "https://banco.exemplo/boleto/77",
        "pdf": "https://banco.exemplo/boleto/77.pdf",
        "pagina_pix": "https://painel.seuprovedor.com.br/api/billings/77/pix",
        "pix_copia_cola": "00020126580014br.gov.bcb.pix...",
        "linha_digitavel": "23793.38128 60000.000003 00000.000000 1 00000000000000",
        "codigo_barras": "23791000000000000003381286000000000000000000"
      }
    }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "total_paginas": 1 }
}

Consultar uma fatura

GET/faturas/{id}financeiro:leitura

Mesmo formato de um item de /faturas, com a segunda via quando em aberto.

curl "$API/faturas/77" -H "Authorization: Bearer $CHAVE"

A segunda via

segunda_via só vem preenchida em fatura pendente ou vencida; nas demais é null.
Cada campo pode ser null, conforme o banco e o tipo de cobrança. Fatura só PIX não tem linha digitável.
pagina_pix é a página de pagamento PIX do provedor. O QR é gerado de novo a cada abertura, então o link não expira: prefira enviá-lo ao assinante.
valor_atualizado aparece quando o PIX foi recalculado com multa e juros: é o valor a pagar hoje.
tipo: boleto, pix, carne ou carteira (cobrança paga direto ao provedor).
situacao: pendente, vencida, paga, cancelada, estornada ou processando.

Para saber na hora que uma fatura foi paga, não fique consultando: assine o evento fatura.paga nos webhooks.

Baixa de pagamento

A baixa (registrar um pagamento recebido) ainda é feita no sistema do provedor, onde ela cancela a cobrança no banco, lança no caixa e libera o contrato. Os pagamentos feitos por boleto e PIX dos bancos integrados já entram sozinhos.