Fire Bankingdocs
Guias de Integração

Transações por Chave PIX

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:

Authorization: Bearer <seu_token>

O token deve ser obtido através do endpoint Gerar Token.

Tipos de Chave PIX Suportados

TipoFormatoExemplo
CPFApenas números (11 dígitos)12345678900
CNPJApenas números (14 dígitos)12345678000190
TelefoneFormato E.164 com + encodado como %2B%2B5511999999999
E-mailEndereço de e-mail válidojoao@example.com
Chave aleatória (EVP)UUID v4550e8400-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âmetroTipoObrigatórioPadrãoDescrição
pixKeystring✓ (path)—Chave PIX (URL-encoded)
pageinteger—1Número da página
sizeinteger—20Registros por página (máx. 1000)
statusstring——PENDING, CONFIRMED ou ERROR
typestring——PAYMENT, WITHDRAW, REFUND_IN ou REFUND_OUT
startDatedate—Últimos 30 diasData inicial (ISO 8601)
endDatedate—HojeData 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:

{
  "data": [],
  "metadata": { "page": 1, "size": 20, "total": 0, "totalPages": 0, "hasNext": false, "hasPrevious": false }
}

Exemplos

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"
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);
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

{
  "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

CampoDescrição
pagePágina atual
sizeQuantidade de registros por página
totalTotal de registros encontrados (máx. 1000)
totalPagesTotal de páginas disponíveis
hasNextIndica se existe próxima página
hasPreviousIndica 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:

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âmetroTipoObrigatórioDescrição
pixKeystring✓Chave PIX (URL-encoded)
identifierstring✓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 Avista (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

curl -X GET "https://api.public.firebanking.com.br/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \
  -H "Authorization: Bearer seu_token_aqui"
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"
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);
}
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

{
  "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.

{
  "statusCode": 404,
  "message": "Transação não encontrada"
}

Mapeamento de Campos

Status

Valor InternoValor Retornado
PENDINGPendente
CONFIRMEDConfirmado
ERRORError

Tipo de Operação

Valor InternoValor RetornadoDescrição
PAYMENTPix inRecebimento via PIX
WITHDRAWPix outPagamento via PIX
REFUND_INRefund inEstorno solicitado (débito)
REFUND_OUTRefund outDevolução recebida (crédito)

Tipo de Movimento

Tipo de OperaçãoMovimento
Pix inCREDIT
Pix outDEBIT
Refund inDEBIT
Refund outCREDIT

Diferenças em Relação a /api/transactions

Aspecto/api/transactions/api/pix/transactions/pix-key/\{pixKey\}
Filtro principalToda a contaPor chave PIX específica
Máx. size por página1001000
Máx. resultados totaisSem limite1000
Default startDateÚltimos 31 diasÚltimos 30 dias
Chave inexistente / sem resultados200 com lista vazia200 com lista vazia
Busca por externalIdQuery param ?externalId=Path param /\{identifier\}
Busca por endToEndIdQuery param ?endToEndId=Path param /\{identifier\}

Casos de Uso

Códigos de Erro

CódigoDescrição
400Parâmetros inválidos, datas invertidas, ou intervalo excede 31 dias
401Token não fornecido ou inválido
404Transação não encontrada (apenas no endpoint /\{pixKey\}/\{identifier\})

Próximos Passos

Buscar Transações

Consulte transações gerais da conta com filtros avançados

Consultar Status

Verifique o status detalhado de uma transação específica

Configurar Webhooks

Receba notificações automáticas quando transações chegarem

Buscar Transações

Consulte e filtre transações PIX da sua conta com paginação

Teste em Sandbox

Simule cenários de erro e delay para testar sua integração

Nesta página

Visão GeralAutenticaçãoTipos de Chave PIX SuportadosEndpoint 1: Listar Transações por Chave PIXParâmetrosChave sem resultadosExemplosExemplo de RespostaPaginaçãoEndpoint 2: Consultar Transação por Chave PIX e IdentificadorParâmetrosExemplosResposta 200 — Transação EncontradaResposta 404 — Não EncontradaMapeamento de CamposStatusTipo de OperaçãoTipo de MovimentoDiferenças em Relação a /api/transactionsCasos de UsoCódigos de ErroPróximos Passos