Listar Transferências PIX

Esta seção explica como listar todas as transferências PIX de uma conta específica.

Visão Geral

O endpoint de listagem retorna todas as transferências PIX (créditos e débitos) de uma conta, permitindo que você:

• Visualize o histórico completo de transferências
• Monitore o status de múltiplas transações
• Acompanhe valores enviados e recebidos
• Identifique transações de crédito e débito

Endpoint

GET /account/{account_id}/transfer/pix/list

Retorna a lista de todas as transferências PIX de uma conta.

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/transfer/pix/list

Headers:

Authorization: Bearer {token}

Parâmetros da URL:

• account_id (obrigatório): ID da conta

Exemplo de Requisição:

curl -X GET \
  'https://app.finexis.com.br/api/v1/gateway/account/5/transfer/pix/list' \
  -H 'Authorization: Bearer {seu_token}'

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Account transactions retrieved successfully",
  "data": [
    {
      "id": 1,
      "account_id": 5,
      "provider_id": 2,
      "amount": "0.100000000000000000",
      "currency": "BRL",
      "type": "credit",
      "status": "paid",
      "description": null,
      "external_id": null,
      "reference": "4a31c00169c84021ae61d9b71c",
      "metadata": [],
      "created_at": "2025-11-18 02:03:02",
      "updated_at": "2025-11-18 02:03:02"
    }
  ]
}

Estrutura da Resposta

A resposta é um array de objetos, onde cada objeto representa uma transferência com os seguintes campos:

Campo	Tipo	Descrição
id	integer	ID único da transação
account_id	integer	ID da conta
provider_id	integer	ID do provedor PIX
amount	string	Valor da transferência (alta precisão)
currency	string	Moeda (geralmente "BRL")
type	string	Tipo de transação (credit ou debit)
status	string	Status da transação
description	string/null	Descrição da transferência
external_id	string/null	ID externo da transação
reference	string	Referência única para consultas
metadata	array/object	Metadados da transação
created_at	string	Data de criação
updated_at	string	Data da última atualização

Tipos de Transação

Tipo	Descrição	Impacto no Saldo
credit	Transação de crédito (recebimento)	Aumenta o saldo
debit	Transação de débito (envio/saque)	Diminui o saldo

Status Possíveis

Status	Descrição
pending	Transação pendente
paid	Transação paga/concluída
failed	Transação falhou
cancelled	Transação cancelada

Casos de Uso

Este endpoint é útil para:

• Extrato: Gerar extratos bancários
• Dashboard: Exibir histórico de transações em uma interface
• Relatórios: Criar relatórios financeiros
• Auditoria: Rastrear todas as movimentações da conta
• Reconciliação: Comparar transações com registros internos

Filtrando e Processando

Exemplo de filtros em JavaScript:

// Filtrar apenas transações de crédito (recebimentos)
const credits = transactions.filter(t => t.type === 'credit');

// Filtrar apenas transações de débito (envios)
const debits = transactions.filter(t => t.type === 'debit');

// Filtrar transações concluídas
const completed = transactions.filter(t => t.status === 'paid');

// Filtrar transações pendentes
const pending = transactions.filter(t => t.status === 'pending');

// Calcular total de créditos
const totalCredits = credits
  .filter(t => t.status === 'paid')
  .reduce((sum, t) => sum + parseFloat(t.amount), 0);

// Calcular total de débitos
const totalDebits = debits
  .filter(t => t.status === 'paid')
  .reduce((sum, t) => sum + parseFloat(t.amount), 0);

// Ordenar por data (mais recentes primeiro)
const sorted = transactions.sort((a, b) => 
  new Date(b.created_at) - new Date(a.created_at)
);

Agrupando por Tipo

Você pode agrupar as transações para facilitar a visualização:

const grouped = transactions.reduce((acc, transaction) => {
  const type = transaction.type;
  if (!acc[type]) {
    acc[type] = [];
  }
  acc[type].push(transaction);
  return acc;
}, {});

// Resultado:
// {
//   credit: [...],
//   debit: [...]
// }

Próximos Passos

• Consultar Status de uma transferência específica
• Criar Nova Transferência
• Ver Cobranças PIX