Listar lotes de pagamento

Este endpoint retorna os lotes de pagamento de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação.

Boleto bancário

É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.

Fatura de recolhimento

Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/batches

MÉTODO

GET

Request Path Params

Campo	Tipo	Descrição	Caracteres
account_key *	uuid4	Chave única de identificação da conta.	36

Request Query String Params

Campo	Tipo	Descrição
request_control_key	uuid4	Chave única de identificação da requisição do cliente (lote).
batch_payment_key	uuid4	Chave única de identificação do pagamento em lote.
payment_type	enum	Tipo do pagamento do lote.
batch_payment_status	enum	Status do lote.
date_from	string	Data inicial. Formato "YYYY-MM-DD".
date_to	string	Data final. Formato "YYYY-MM-DD".
page	string	Número da página requisitada. 1 por padrão.
page_size	string	Tamanho da página requisitada na consulta. 30 por padrão e valor máximo.

Enumeradores payment_type

Enumerador	Tipo	Descrição
bank_slip	string	Boleto bancário
collection_slip	string	Fatura de recolhimento

Enumeradores batch_payment_status

Enumerador	Descrição
pending	Pendente de processamento
pending_2fa_approval	Pendente de aprovação 2FA
rejected	Rejeitado
approved	Aprovado
processed	Processado

Response

Success Response

STATUS

200

Response Body: Listagem de lotes de pagamento

{
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  },
  "data": [
    {
      "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "batch_status": "processed",
      "payment_type": "bank_slip",
      "total_paid": 10,
      "total_pending": 0,
      "total_error": 0,
      "total_amount": 1357.3
    }
  ]
}

Response Body Params

Campo	Tipo	Descrição
pagination *	object	Informações de paginação da consulta.
data *	array	Lista de lotes encontrados.

Cada elemento de data contém:

Campo	Tipo	Descrição
batch_payment_key *	uuid4	Chave única de identificação do pagamento em lote.
request_control_key *	uuid4	Chave única de identificação da requisição do cliente (lote).
batch_status *	enum	Status atual do lote.
payment_type *	enum	Tipo do pagamento do lote.
total_paid *	int	Quantidade de itens do lote pagos com sucesso.
total_pending *	int	Quantidade de itens ainda pendentes no lote.
total_error *	int	Quantidade de itens com erro no lote.
total_amount *	number	Valor total do lote.

Objeto pagination

Campo	Tipo	Descrição
current_page *	int	Página atual retornada.
rows_per_page *	int	Quantidade de registros por página.

Enumeradores payment_type

Enumerador	Descrição
bank_slip	Boleto bancário
collection_slip	Fatura de recolhimento

Enumeradores batch_payment_status

Enumerador	Descrição
pending	Pendente de processamento
pending_2fa_approval	Pendente de aprovação 2FA
rejected	Rejeitado
approved	Aprovado
processed	Processado

Error Response

STATUS

4XX

Response Body

{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}

Código HTTP	Código QI	Título	Descrição (eng)	Descrição (pt-br)
400	BIP000026	Bad Request	Invalid payment date format. The correct format is YYYY-MM-DD.	Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD.
400	BIP000027	Bad Request	Invalid integer value for page or size query string parameters.	Valor inválido para parâmetros de página ou tamanho de página.
400	BIP000047	Bad Request	Invalid payment type.	Tipo de pagamento inválido.