Avistadocs
Guías de Integración

Transacciones por Clave PIX

Descripción General

Los endpoints de transacciones por clave PIX le permiten consultar el historial de transacciones asociadas a una clave PIX específica (CPF, CNPJ, teléfono, email o clave aleatoria EVP). Son ideales para escenarios como:

  • Conciliación por clave: verificar todos los recibos de un CNPJ o CPF específico
  • Auditoría: auditar movimientos de una clave PIX dentro de un período
  • Monitoreo de recibos: rastrear pagos recibidos a través de una clave específica

En comparación con el endpoint general /api/transactions, la diferencia principal es el filtro obligatorio por clave PIX y el size máximo mayor: hasta 1000 registros por página (vs. 100 en el endpoint general). La consulta retorna como máximo 1000 resultados en total -- si la clave tiene más transacciones en el período, use filtros de type, status o períodos más cortos para acotar.

Autenticación

Este endpoint requiere un Bearer token válido en el encabezado Authorization:

Authorization: Bearer <your_token>

El token debe obtenerse a través del endpoint Generar Token.

Tipos de Clave PIX Soportados

TipoFormatoEjemplo
CPFSolo números (11 dígitos)12345678900
CNPJSolo números (14 dígitos)12345678000190
TeléfonoFormato E.164 con + codificado como %2B%2B5511999999999
EmailDirección de email válidajoao@example.com
Clave aleatoria (EVP)UUID v4550e8400-e29b-41d4-a716-446655440000

Cuando use claves con caracteres especiales en la URL (como + en números de teléfono), siempre aplique codificación URL. En los ejemplos de código, encodeURIComponent (JavaScript) y quote(..., safe="") (Python) manejan esto automáticamente.

Endpoint 1: Listar Transacciones por Clave PIX

GET /api/pix/transactions/pix-key/{pixKey}

Parámetros

ParámetroTipoRequeridoPredeterminadoDescripción
pixKeystringSí (path)--Clave PIX (codificada en URL)
pageinteger--1Número de página
sizeinteger--20Registros por página (máx. 1000)
statusstring----PENDING, CONFIRMED o ERROR
typestring----PAYMENT, WITHDRAW, REFUND_IN o REFUND_OUT
startDatedate--Últimos 30 díasFecha de inicio (ISO 8601)
endDatedate--HoyFecha de fin (ISO 8601)

El intervalo entre startDate y endDate no puede exceder 31 días. La consulta retorna como máximo 1000 resultados -- si hay más transacciones en el período, use filtros adicionales (type, status o períodos más cortos) para acotar.

Clave Sin Resultados

Si la pixKey proporcionada no tiene transacciones en el período consultado, la API retorna HTTP 200 con data vacío:

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

Ejemplos

curl -X GET "https://api.avista.global/api/pix/transactions/pix-key/joao%40example.com?status=CONFIRMED&page=1&size=50" \
  -H "Authorization: Bearer your_token_here"
const pixKey = 'joao@example.com';
const params = new URLSearchParams({
  status: 'CONFIRMED',
  page: '1',
  size: '50'
});

const response = await fetch(
  `https://api.avista.global/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
  {
    headers: {
      'Authorization': 'Bearer your_token_here'
    }
  }
);

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.avista.global/api/pix/transactions/pix-key/{quote(pix_key, safe="")}',
    params={
        'status': 'CONFIRMED',
        'page': 1,
        'size': 50
    },
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

data = response.json()
print(data)

Ejemplo de Respuesta

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

Paginación

CampoDescripción
pagePágina actual
sizeNúmero de registros por página
totalTotal de registros encontrados (máx. 1000)
totalPagesTotal de páginas disponibles
hasNextIndica si hay una página siguiente
hasPreviousIndica si hay una página anterior

Para obtener todos los resultados de una vez, use size=1000. Para procesar en lotes, navegue por las páginas mientras hasNext sea 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.avista.global/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
      { headers: { 'Authorization': 'Bearer your_token_here' } }
    );
    const { data, metadata } = await response.json();
    results.push(...data);
    if (!metadata.hasNext) break;
    page++;
  } while (true);

  return results;
}

Endpoint 2: Consultar Transacción por Clave PIX e Identificador

GET /api/pix/transactions/pix-key/{pixKey}/{identifier}

Parámetros

ParámetroTipoRequeridoDescripción
pixKeystringSíClave PIX (codificada en URL)
identifierstringSíIdentificador de la transacción (codificado en URL)

El identifier se compara simultáneamente contra tres campos de la transacción:

  • endToEndId -- ID End-to-End del PIX (ej.: E00416968202501151030VX5Sx8fIpkY)
  • externalId -- Identificador externo proporcionado al crear la transacción
  • id (numérico) -- ID interno de la transacción en Avista (solo si el valor es puramente numérico)

En la práctica no hay ambigüedad: cada tipo de identificador tiene un formato único (e2eId comienza con E seguido de 32 caracteres alfanuméricos; id es puramente numérico; externalId es cualquier cadena).

Ejemplos

curl -X GET "https://api.avista.global/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \
  -H "Authorization: Bearer your_token_here"
curl -X GET "https://api.avista.global/api/pix/transactions/pix-key/joao%40example.com/order-abc123" \
  -H "Authorization: Bearer your_token_here"
const pixKey = 'joao@example.com';
const identifier = 'E00416968202501151030VX5Sx8fIpkY';

const response = await fetch(
  `https://api.avista.global/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}/${encodeURIComponent(identifier)}`,
  {
    headers: {
      'Authorization': 'Bearer your_token_here'
    }
  }
);

if (response.status === 404) {
  console.log('Transaction not found');
} 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.avista.global/api/pix/transactions/pix-key/{quote(pix_key, safe="")}/{quote(identifier, safe="")}',
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

if response.status_code == 404:
    print('Transaction not found')
else:
    transaction = response.json()
    print(transaction)

Respuesta 200 -- Transacción 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"
    }
  }
}

Respuesta 404 -- No Encontrado

Se retorna cuando ninguna transacción coincide con el identifier proporcionado para la pixKey especificada.

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

Mapeo de Campos

Estado

Valor InternoValor Retornado
PENDINGPendente
CONFIRMEDConfirmado
ERRORError

Tipo de Operación

Valor InternoValor RetornadoDescripción
PAYMENTPix inRecepción PIX
WITHDRAWPix outPago PIX
REFUND_INRefund inDevolución solicitada (débito)
REFUND_OUTRefund outReversión recibida (crédito)

Tipo de Movimiento

Tipo de OperaciónMovimiento
Pix inCREDIT
Pix outDEBIT
Refund inDEBIT
Refund outCREDIT

Diferencias con /api/transactions

Aspecto/api/transactions/api/pix/transactions/pix-key/\{pixKey\}
Filtro principalToda la cuentaPor clave PIX específica
Máx. size por página1001000
Máx. resultados totalesSin límite1000
startDate predeterminadoÚltimos 31 díasÚltimos 30 días
Clave inexistente / sin resultados200 con lista vacía200 con lista vacía
Búsqueda por externalIdQuery param ?externalId=Path param /\{identifier\}
Búsqueda por endToEndIdQuery param ?endToEndId=Path param /\{identifier\}

Casos de Uso

Códigos de Error

CódigoDescripción
400Parámetros inválidos, fechas invertidas o intervalo excede 31 días
401Token no proporcionado o inválido
404Transacción no encontrada (solo en el endpoint /\{pixKey\}/\{identifier\})

Próximos Pasos

Buscar Transacciones

Consulte transacciones generales de la cuenta con filtros avanzados

Verificar Estado

Verifique el estado detallado de una transacción específica

Configurar Webhooks

Reciba notificaciones automáticas cuando lleguen transacciones

Buscar Transacciones

Consulte y filtre las transacciones PIX de su cuenta con paginación

Pruebas en Sandbox

Simule escenarios de error y retraso para probar su integración

En esta página

Descripción GeneralAutenticaciónTipos de Clave PIX SoportadosEndpoint 1: Listar Transacciones por Clave PIXParámetrosClave Sin ResultadosEjemplosEjemplo de RespuestaPaginaciónEndpoint 2: Consultar Transacción por Clave PIX e IdentificadorParámetrosEjemplosRespuesta 200 -- Transacción EncontradaRespuesta 404 -- No EncontradoMapeo de CamposEstadoTipo de OperaciónTipo de MovimientoDiferencias con /api/transactionsCasos de UsoCódigos de ErrorPróximos Pasos