Buscar Transações - Avista API Docs

Visão Geral
Autenticação
Parâmetros de Consulta
Mapeamento de Campos
Status
Tipo de Operação
Tipo de Movimento
Valores
Mascaramento de Documento
Exemplo de Uso
Buscar todas as transações confirmadas
Buscar transações por período
Buscar por identificador específico
Exemplo de Resposta
Paginação
Navegação entre páginas
Casos de Uso Comuns
Códigos de Erro
Próximos Passos

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:

Authorization: Bearer <seu_token>

O token deve ser obtido através do endpoint Gerar 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

curl -X GET "https://api.avista.global/api/transactions?status=CONFIRMED&page=1&size=10" \
  -H "Authorization: Bearer seu_token_aqui"

Buscar transações por período

curl -X GET "https://api.avista.global/api/transactions?startDate=2025-01-01&endDate=2025-01-15&type=PAYMENT" \
  -H "Authorization: Bearer seu_token_aqui"

Buscar por identificador específico

# Por externalId (seu identificador)
curl -X GET "https://api.avista.global/api/transactions?externalId=order-12345" \
  -H "Authorization: Bearer seu_token_aqui"

# Por endToEndId (ID do PIX)
curl -X GET "https://api.avista.global/api/transactions?endToEndId=E12345678901234567890123456789012" \
  -H "Authorization: Bearer seu_token_aqui"

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

// 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

Relatório diário de recebimentos

curl -X GET "https://api.avista.global/api/transactions?type=PAYMENT&status=CONFIRMED&startDate=2025-01-15&endDate=2025-01-15" \
  -H "Authorization: Bearer seu_token"

Verificar transações pendentes

curl -X GET "https://api.avista.global/api/transactions?status=PENDING" \
  -H "Authorization: Bearer seu_token"

Histórico de estornos

curl -X GET "https://api.avista.global/api/transactions?type=REFUND_IN" \
  -H "Authorization: Bearer seu_token"

Buscar transação específica por referência

curl -X GET "https://api.avista.global/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

Consultar Status

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

Reenviar Webhook

Reenvie notificações de transações para seu sistema

PIX Refund-In (Estorno)Visão Geral

⌘I