Endpoint responsável por consultar cobranças cadastradas na conta de forma paginada, com suporte a filtros por cliente, forma de pagamento, status, datas e vínculos operacionais.

Diferente da recuperação de uma cobrança específica, essa chamada retorna uma lista de registros compatíveis com os parâmetros informados na consulta.

Funcionamento da listagem

A resposta desse endpoint é paginada.

Isso significa que as cobranças são retornadas em blocos, respeitando os parâmetros de navegação enviados na requisição. Esse comportamento é importante para integrações que trabalham com grande volume de dados, rotinas de conciliação ou interfaces administrativas.

Parâmetros principais da requisição

Alguns filtros são mais comuns em fluxos de integração:

• customer — Filtra cobranças de um cliente específico
• customerGroupName — Filtra cobranças pelo nome do grupo do cliente
• billingType — Filtra pela forma de pagamento
• status — Filtra pelo status atual da cobrança
• subscription — Filtra cobranças vinculadas a uma assinatura
• installment — Filtra cobranças vinculadas a um parcelamento
• externalReference — Filtra pelo identificador utilizado no sistema de origem
• invoiceStatus — Filtra cobranças de acordo com o status da nota fiscal vinculada
• anticipated — Filtra registros que já foram antecipados
• anticipable — Filtra registros elegíveis para antecipação
• dateCreated[ge] e dateCreated[le] — Filtram por intervalo de data de criação
• dueDate[ge] e dueDate[le] — Filtram por intervalo de vencimento
• paymentDate[ge] e paymentDate[le] — Filtram por intervalo de recebimento
• estimatedCreditDate[ge] e estimatedCreditDate[le] — Filtram por intervalo de data estimada de crédito
• user — Filtra pelo e-mail do usuário que criou a cobrança
• checkoutSession — Filtra pelo identificador da sessão de checkout

Casos de uso mais comuns

Esse endpoint costuma ser utilizado para:

• localizar cobranças de um cliente
• consultar cobranças por status
• listar cobranças por forma de pagamento
• apoiar rotinas de conciliação
• consultar cobranças de assinaturas ou parcelamentos
• alimentar telas administrativas com filtros operacionais

🚧

Atenção

Este endpoint não deve ser utilizado para polling contínuo de status.

Polling é a prática de fazer chamadas GET sucessivas para verificar mudanças de estado da cobrança. Além de ser uma má prática de integração, esse comportamento aumenta consumo de recursos e pode levar ao bloqueio da chave de API por abuso.

Para acompanhar mudanças de status, o recomendado é utilizar Webhooks.