Visão Geral Retorna uma lista paginada de todos os pagamentos de boletos realizados pela conta, com suporte a filtros avançados por status, data inicial e data final.
Parâmetros de Query Número da página a ser retornada Valor mínimo: 1
Quantidade de itens por página Valor mínimo: 1
Valor máximo: 100
Filtrar por status do pagamento Valores aceitos:
PENDING: Pagamentos em processamentoPAID: Pagamentos confirmadosCANCELED: Pagamentos canceladosREFUND_OCCURRENCE: Pagamentos com ocorrência de estorno Data inicial para filtro (formato: YYYY-MM-DD) Retorna pagamentos criados a partir desta data (inclusive) Exemplo: 2024-01-01
Data final para filtro (formato: YYYY-MM-DD) Retorna pagamentos criados até esta data (inclusive) Exemplo: 2024-01-31
Resposta de Sucesso Lista de pagamentos ID único do pagamento (UUID)
Identificador externo (se fornecido na criação)
Status atual: PENDING, PAID, CANCELED, REFUND_OCCURRENCE
Valor do pagamento em reais
Data de vencimento do boleto (formato ISO 8601)
Data/hora de criação do pagamento (formato ISO 8601)
Data/hora da última atualização (formato ISO 8601)
Metadados da paginação Total de itens encontrados
Total de páginas disponíveis
Indica se existe próxima página
Indica se existe página anterior
Exemplos de Requisição Listar últimos 20 pagamentos curl -X GET "https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws?page=1&limit=20" \ -H "x-api-key: YOUR_API_KEY" Filtrar por status PAID curl -X GET "https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws?status=PAID" \ -H "x-api-key: YOUR_API_KEY" Filtrar por período curl -X GET "https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws?startDate=2024-01-01&endDate=2024-01-31" \ -H "x-api-key: YOUR_API_KEY" Filtros combinados curl -X GET "https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws?page=1&limit=10&status=PAID&startDate=2024-01-01" \ -H "x-api-key: YOUR_API_KEY" const params = new URLSearchParams ({ page: '1' , limit: '10' , status: 'PAID' , startDate: '2024-01-01' }); const response = await fetch ( `https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws? ${ params } ` , { headers: { 'x-api-key' : 'YOUR_API_KEY' } }); const data = await response . json (); import requests params = { 'page' : 1 , 'limit' : 10 , 'status' : 'PAID' , 'startDate' : '2024-01-01' } response = requests.get( 'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraws' , params = params, headers = { 'x-api-key' : 'YOUR_API_KEY' } ) data = response.json() Exemplo de Resposta { "data" : [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "externalId" : "PAY-2024-001" , "status" : "PAID" , "amount" : 152.50 , "dueDate" : "2024-01-15T03:00:00.000Z" , "createdAt" : "2024-01-10T14:00:00.000Z" , "updatedAt" : "2024-01-10T14:30:00.000Z" }, { "id" : "660e8400-e29b-41d4-a716-446655440001" , "externalId" : "PAY-2024-002" , "status" : "PAID" , "amount" : 89.99 , "dueDate" : "2024-01-20T03:00:00.000Z" , "createdAt" : "2024-01-12T10:15:00.000Z" , "updatedAt" : "2024-01-12T10:45:00.000Z" } ], "meta" : { "page" : 1 , "limit" : 20 , "total" : 45 , "totalPages" : 3 , "hasNextPage" : true , "hasPreviousPage" : false } } Códigos de Resposta Listagem retornada com sucesso
Parâmetros inválidos Possíveis causas:
Data em formato inválido
Status inválido
Limit maior que 100
API key inválida ou ausente
Ordenação Os pagamentos são retornados ordenados por data de criação decrescente (mais recentes primeiro).
Otimização : O filtro por status é aplicado após a consulta no banco de dados (post-filtering). Para grandes volumes, considere usar apenas filtros de data para melhor performance.
Casos de Uso Dashboard de pagamentos // Buscar últimos 10 pagamentos const recent = await listWithdraws ({ page: 1 , limit: 10 }); // Buscar pagamentos pendentes const pending = await listWithdraws ({ status: 'PENDING' }); // Buscar pagamentos do mês const thisMonth = await listWithdraws ({ startDate: '2024-01-01' , endDate: '2024-01-31' }); Paginação async function getAllPayments () { const allPayments = []; let page = 1 ; let hasMore = true ; while ( hasMore ) { const response = await listWithdraws ({ page , limit: 100 }); allPayments . push ( ... response . data ); hasMore = response . meta . hasNextPage ; page ++ ; } return allPayments ; } Relatório financeiro async function getMonthlyReport ( year , month ) { const startDate = ` ${ year } - ${ month . toString (). padStart ( 2 , '0' ) } -01` ; const endDate = new Date ( year , month , 0 ). toISOString (). split ( 'T' )[ 0 ]; const response = await listWithdraws ({ startDate , endDate , status: 'PAID' , limit: 100 }); const total = response . data . reduce (( sum , payment ) => sum + payment . amount , 0 ); return { total , count: response . meta . total , payments: response . data }; } Filtros Disponíveis Filtro Tipo Descrição pageinteger Página atual (padrão: 1) limitinteger Itens por página (padrão: 20, máx: 100) statusstring Status do pagamento startDatestring Data inicial (YYYY-MM-DD) endDatestring Data final (YYYY-MM-DD)
Próximos Passos Dica : Combine filtros de data e status para criar relatórios personalizados. Por exemplo, listar todos os pagamentos pagos em um determinado período.
