> ## 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. # Transações por Chave PIX > Consulte e filtre transações associadas a uma chave PIX específica com paginação ## Visão Geral Os endpoints de transações por chave PIX permitem consultar o histórico de transações associadas a uma chave PIX específica (CPF, CNPJ, telefone, e-mail ou chave aleatória EVP). São ideais para cenários como: * **Reconciliação por chave**: verificar todos os recebimentos de um CNPJ ou CPF específico * **Auditoria**: auditar movimentações de uma chave PIX em um período * **Monitoramento de recebimentos**: acompanhar pagamentos recebidos via uma chave específica Comparado ao endpoint geral `/api/transactions`, a diferença principal é o filtro obrigatório por chave PIX e o `size` máximo maior: até **1000 registros por página** (vs. 100 no endpoint geral). A consulta retorna no máximo 1000 resultados no total — se a chave tiver mais transações no período, use filtros de `type`, `status` ou períodos menores para refinar. ## 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). ## Tipos de Chave PIX Suportados | Tipo | Formato | Exemplo | | --------------------- | ----------------------------------------- | -------------------------------------- | | CPF | Apenas números (11 dígitos) | `12345678900` | | CNPJ | Apenas números (14 dígitos) | `12345678000190` | | Telefone | Formato E.164 com `+` encodado como `%2B` | `%2B5511999999999` | | E-mail | Endereço de e-mail válido | `joao@example.com` | | Chave aleatória (EVP) | UUID v4 | `550e8400-e29b-41d4-a716-446655440000` | Ao usar chaves com caracteres especiais na URL (como `+` no telefone), sempre aplique URL encoding. Nos exemplos de código, `encodeURIComponent` (JavaScript) e `quote(..., safe="")` (Python) fazem isso automaticamente. *** ## Endpoint 1: Listar Transações por Chave PIX ``` GET /api/pix/transactions/pix-key/{pixKey} ``` ### Parâmetros | Parâmetro | Tipo | Obrigatório | Padrão | Descrição | | ----------- | ------- | ----------- | ------------------- | -------------------------------------------------- | | `pixKey` | string | ✓ (path) | — | Chave PIX (URL-encoded) | | `page` | integer | — | `1` | Número da página | | `size` | integer | — | `20` | Registros por página (máx. **1000**) | | `status` | string | — | — | `PENDING`, `CONFIRMED` ou `ERROR` | | `type` | string | — | — | `PAYMENT`, `WITHDRAW`, `REFUND_IN` ou `REFUND_OUT` | | `startDate` | date | — | Últimos **30 dias** | Data inicial (ISO 8601) | | `endDate` | date | — | Hoje | Data final (ISO 8601) | O intervalo entre `startDate` e `endDate` não pode exceder **31 dias**. A consulta retorna no máximo **1000 resultados** — se houver mais transações no período, use filtros adicionais (`type`, `status`, ou períodos menores) para refinar. ### Chave sem resultados Se a `pixKey` informada não tiver transações no período consultado, a API retorna HTTP 200 com `data` vazio: ```json theme={null} { "data": [], "metadata": { "page": 1, "size": 20, "total": 0, "totalPages": 0, "hasNext": false, "hasPrevious": false } } ``` ### Exemplos ```bash cURL theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/joao%40example.com?status=CONFIRMED&page=1&size=50" \ -H "Authorization: Bearer seu_token_aqui" ``` ```javascript Node.js theme={null} const pixKey = 'joao@example.com'; const params = new URLSearchParams({ status: 'CONFIRMED', page: '1', size: '50' }); const response = await fetch( `https://api.public.firebanking.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`, { headers: { 'Authorization': 'Bearer seu_token_aqui' } } ); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests from urllib.parse import quote pix_key = 'joao@example.com' response = requests.get( f'https://api.public.firebanking.com.br/api/pix/transactions/pix-key/{quote(pix_key, safe="")}', params={ 'status': 'CONFIRMED', 'page': 1, 'size': 50 }, headers={ 'Authorization': 'Bearer seu_token_aqui' } ) data = response.json() print(data) ``` ### 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": "E00416968202501151030VX5Sx8fIpkY", "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": 50, "total": 320, "totalPages": 7, "hasNext": true, "hasPrevious": false } } ``` ### Paginação | Campo | Descrição | | ------------- | ------------------------------------------ | | `page` | Página atual | | `size` | Quantidade de registros por página | | `total` | Total de registros encontrados (máx. 1000) | | `totalPages` | Total de páginas disponíveis | | `hasNext` | Indica se existe próxima página | | `hasPrevious` | Indica se existe página anterior | Para obter todos os resultados de uma vez, use `size=1000`. Para processar em lotes, navegue pelas páginas enquanto `hasNext` for `true`: ```javascript theme={null} async function getAllTransactions(pixKey, filters = {}) { const results = []; let page = 1; do { const params = new URLSearchParams({ ...filters, page, size: 100 }); const response = await fetch( `https://api.public.firebanking.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`, { headers: { 'Authorization': 'Bearer seu_token_aqui' } } ); const { data, metadata } = await response.json(); results.push(...data); if (!metadata.hasNext) break; page++; } while (true); return results; } ``` *** ## Endpoint 2: Consultar Transação por Chave PIX e Identificador ``` GET /api/pix/transactions/pix-key/{pixKey}/{identifier} ``` ### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | ---------------------------------------- | | `pixKey` | string | ✓ | Chave PIX (URL-encoded) | | `identifier` | string | ✓ | Identificador da transação (URL-encoded) | O `identifier` é comparado simultaneamente contra três campos da transação: * **`endToEndId`** — End-to-End ID do PIX (ex: `E00416968202501151030VX5Sx8fIpkY`) * **`externalId`** — Identificador externo fornecido na criação da transação * **`id` numérico** — ID interno da transação na Fire Banking (apenas se o valor for puramente numérico) Na prática não há ambiguidade: o formato de cada tipo de identificador é único (e2eId começa com `E` seguido de 32 caracteres alfanuméricos; id é puramente numérico; externalId é qualquer string). ### Exemplos ```bash cURL (endToEndId) theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \ -H "Authorization: Bearer seu_token_aqui" ``` ```bash cURL (externalId) theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/joao%40example.com/order-abc123" \ -H "Authorization: Bearer seu_token_aqui" ``` ```javascript Node.js theme={null} const pixKey = 'joao@example.com'; const identifier = 'E00416968202501151030VX5Sx8fIpkY'; const response = await fetch( `https://api.public.firebanking.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}/${encodeURIComponent(identifier)}`, { headers: { 'Authorization': 'Bearer seu_token_aqui' } } ); if (response.status === 404) { console.log('Transação não encontrada'); } else { const transaction = await response.json(); console.log(transaction); } ``` ```python Python theme={null} import requests from urllib.parse import quote pix_key = 'joao@example.com' identifier = 'E00416968202501151030VX5Sx8fIpkY' response = requests.get( f'https://api.public.firebanking.com.br/api/pix/transactions/pix-key/{quote(pix_key, safe="")}/{quote(identifier, safe="")}', headers={ 'Authorization': 'Bearer seu_token_aqui' } ) if response.status_code == 404: print('Transação não encontrada') else: transaction = response.json() print(transaction) ``` ### Resposta 200 — Transação Encontrada ```json theme={null} { "transactionId": "12345", "externalId": "order-abc123", "status": "Confirmado", "operationType": "Pix in", "movementType": "CREDIT", "originalAmount": 100.00, "feeAmount": 1.00, "finalAmount": 99.00, "endToEndId": "E00416968202501151030VX5Sx8fIpkY", "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" } } } ``` ### Resposta 404 — Não Encontrada Retornado quando nenhuma transação corresponde ao `identifier` informado para a `pixKey` especificada. ```json theme={null} { "statusCode": 404, "message": "Transação não encontrada" } ``` *** ## Mapeamento de Campos ### Status | Valor Interno | Valor Retornado | | ------------- | --------------- | | `PENDING` | `Pendente` | | `CONFIRMED` | `Confirmado` | | `ERROR` | `Error` | ### Tipo de Operação | 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 | Tipo de Operação | Movimento | | ---------------- | --------- | | `Pix in` | `CREDIT` | | `Pix out` | `DEBIT` | | `Refund in` | `DEBIT` | | `Refund out` | `CREDIT` | *** ## Diferenças em Relação a `/api/transactions` | Aspecto | `/api/transactions` | `/api/pix/transactions/pix-key/{pixKey}` | | ---------------------------------- | -------------------------- | ---------------------------------------- | | Filtro principal | Toda a conta | Por chave PIX específica | | Máx. `size` por página | 100 | **1000** | | Máx. resultados totais | Sem limite | **1000** | | Default `startDate` | Últimos 31 dias | Últimos **30 dias** | | Chave inexistente / sem resultados | 200 com lista vazia | 200 com lista vazia | | Busca por `externalId` | Query param `?externalId=` | Path param `/{identifier}` | | Busca por `endToEndId` | Query param `?endToEndId=` | Path param `/{identifier}` | *** ## Casos de Uso Verificar todos os recebimentos confirmados de um CNPJ em um período: ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/12345678000190?type=PAYMENT&status=CONFIRMED&startDate=2025-01-01&endDate=2025-01-31&size=1000" \ -H "Authorization: Bearer seu_token" ``` Confirmar se um pagamento PIX específico foi recebido pela chave: ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \ -H "Authorization: Bearer seu_token" ``` Buscar todas as movimentações de um CNPJ nos últimos 30 dias (padrão): ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/12345678000190?size=1000" \ -H "Authorization: Bearer seu_token" ``` Monitorar recebimentos de uma chave de telefone em uma semana específica: ```bash theme={null} curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/%2B5511999999999?type=PAYMENT&startDate=2025-01-13&endDate=2025-01-19" \ -H "Authorization: Bearer seu_token" ``` *** ## Códigos de Erro | Código | Descrição | | ------ | ---------------------------------------------------------------------- | | `400` | Parâmetros inválidos, datas invertidas, ou intervalo excede 31 dias | | `401` | Token não fornecido ou inválido | | `404` | Transação não encontrada (apenas no endpoint `/{pixKey}/{identifier}`) | *** ## Próximos Passos Consulte transações gerais da conta com filtros avançados Verifique o status detalhado de uma transação específica Receba notificações automáticas quando transações chegarem