> ## Documentation Index > Fetch the complete documentation index at: https://docs.firebanking.dev/llms.txt > Use this file to discover all available pages before exploring further. # Buscar Transações > Consulte e filtre transações PIX da sua conta com paginação ## Visão Geral O endpoint de busca de transações permite consultar o histórico de transações PIX da sua conta com diversos filtros e paginação. Os dados são retornados em um formato amigável, com status e tipos traduzidos para português e valores em reais. ## Autenticação Este endpoint requer um token Bearer válido no header `Authorization`: ```bash theme={null} Authorization: Bearer ``` O token deve ser obtido através do endpoint [Gerar Token](/api-reference/endpoints/generate-token). ## Parâmetros de Consulta | Parâmetro | Tipo | Descrição | | ------------ | ------- | ----------------------------------------------------------------- | | `page` | integer | Número da página (padrão: 1) | | `size` | integer | Registros por página (padrão: 20, máximo: 100) | | `status` | string | Filtro por status: `PENDING`, `CONFIRMED`, `ERROR` | | `type` | string | Filtro por tipo: `PAYMENT`, `WITHDRAW`, `REFUND_IN`, `REFUND_OUT` | | `startDate` | date | Data inicial (ISO 8601). Padrão: últimos 31 dias | | `endDate` | date | Data final (ISO 8601). Padrão: hoje | | `externalId` | string | Filtro por seu identificador externo | | `endToEndId` | string | Filtro por End-to-End ID do PIX | O intervalo entre `startDate` e `endDate` não pode exceder **31 dias**. ## Mapeamento de Campos ### Status Os status internos são traduzidos para o formato público: | Valor Interno | Valor Retornado | | ------------- | --------------- | | `PENDING` | `Pendente` | | `CONFIRMED` | `Confirmado` | | `ERROR` | `Error` | ### Tipo de Operação Os tipos de transação são traduzidos para português: | Valor Interno | Valor Retornado | Descrição | | ------------- | --------------- | ---------------------------- | | `PAYMENT` | `Pix in` | Recebimento via PIX | | `WITHDRAW` | `Pix out` | Pagamento via PIX | | `REFUND_IN` | `Refund in` | Estorno solicitado (débito) | | `REFUND_OUT` | `Refund out` | Devolução recebida (crédito) | ### Tipo de Movimento Indica se a transação é entrada ou saída na conta: | Tipo de Operação | Movimento | | ---------------- | --------- | | `Pix in` | `CREDIT` | | `Pix out` | `DEBIT` | | `Refund in` | `DEBIT` | | `Refund out` | `CREDIT` | ### Valores Todos os valores monetários são retornados em **reais** com 2 casas decimais: * `originalAmount`: Valor original da transação * `feeAmount`: Taxa aplicada * `finalAmount`: Valor final (original ± taxa) ### Mascaramento de Documento Por segurança, documentos de contrapartes são mascarados: * **CPF**: `123.456.789-00` → `***.456.789-**` * **CNPJ**: `12.345.678/0001-90` → `**.345.678/****-**` ## Exemplo de Uso ### Buscar todas as transações confirmadas ```bash cURL theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?status=CONFIRMED&page=1&size=10" \ -H "Authorization: Bearer seu_token_aqui" ``` ```javascript Node.js theme={null} const response = await fetch( 'https://api.public.firebanking.com.br/api/transactions?status=CONFIRMED&page=1&size=10', { headers: { 'Authorization': 'Bearer seu_token_aqui' } } ); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.public.firebanking.com.br/api/transactions', params={ 'status': 'CONFIRMED', 'page': 1, 'size': 10 }, headers={ 'Authorization': 'Bearer seu_token_aqui' } ) data = response.json() print(data) ``` ### Buscar transações por período ```bash cURL theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?startDate=2025-01-01&endDate=2025-01-15&type=PAYMENT" \ -H "Authorization: Bearer seu_token_aqui" ``` ```javascript Node.js theme={null} const params = new URLSearchParams({ startDate: '2025-01-01', endDate: '2025-01-15', type: 'PAYMENT' }); const response = await fetch( `https://api.public.firebanking.com.br/api/transactions?${params}`, { headers: { 'Authorization': 'Bearer seu_token_aqui' } } ); ``` ### Buscar por identificador específico ```bash theme={null} # Por externalId (seu identificador) curl -X GET "https://api.public.firebanking.com.br/api/transactions?externalId=order-12345" \ -H "Authorization: Bearer seu_token_aqui" # Por endToEndId (ID do PIX) curl -X GET "https://api.public.firebanking.com.br/api/transactions?endToEndId=E12345678901234567890123456789012" \ -H "Authorization: Bearer seu_token_aqui" ``` ## Exemplo de Resposta ```json theme={null} { "data": [ { "transactionId": "12345", "externalId": "order-abc123", "status": "Confirmado", "operationType": "Pix in", "movementType": "CREDIT", "originalAmount": 100.00, "feeAmount": 1.00, "finalAmount": 99.00, "endToEndId": "E12345678901234567890123456789012", "createdAt": "2025-01-15T10:30:00.000Z", "processedAt": "2025-01-15T10:30:05.000Z", "counterpart": { "name": "João Silva", "document": "***.456.789-**", "bank": { "bankISPB": "00000000", "bankName": "Banco do Brasil", "bankCode": "001", "accountBranch": "0001", "accountNumber": "123456-7" } } } ], "metadata": { "page": 1, "size": 20, "total": 150, "totalPages": 8, "hasNext": true, "hasPrevious": false } } ``` ## Paginação A resposta inclui metadados de paginação para facilitar a navegação: | Campo | Descrição | | ------------- | ---------------------------------- | | `page` | Página atual | | `size` | Quantidade de registros por página | | `total` | Total de registros encontrados | | `totalPages` | Total de páginas disponíveis | | `hasNext` | Indica se existe próxima página | | `hasPrevious` | Indica se existe página anterior | ### Navegação entre páginas ```javascript theme={null} // Primeira página const page1 = await fetchTransactions({ page: 1, size: 20 }); if (page1.metadata.hasNext) { // Próxima página const page2 = await fetchTransactions({ page: 2, size: 20 }); } ``` ## Casos de Uso Comuns ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?type=PAYMENT&status=CONFIRMED&startDate=2025-01-15&endDate=2025-01-15" \ -H "Authorization: Bearer seu_token" ``` ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?status=PENDING" \ -H "Authorization: Bearer seu_token" ``` ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?type=REFUND_IN" \ -H "Authorization: Bearer seu_token" ``` ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/transactions?externalId=MEU-PEDIDO-123" \ -H "Authorization: Bearer seu_token" ``` ## Códigos de Erro | Código | Descrição | | ------ | --------------------------------------------------------- | | `400` | Parâmetros inválidos ou intervalo de datas excede 31 dias | | `401` | Token não fornecido ou inválido | ## Próximos Passos Consulte o status detalhado de uma transação específica Reenvie notificações de transações para seu sistema Filtre transações por chave PIX específica com paginação