Registro de cambios

Cambios relevantes de la API pública de INFI.

2026-06-04 — Registro de destinatario tercero vía API

Nuevo endpoint POST /v1/recipients para enviar destinatarios terceros (CPF/CNPJ distinto del titular) directamente por la API — antes, el registro solo se hacía por soporte.

• El registro crea al destinatario como pending_review: no aprueba y no libera retiros. La aprobación (KYC/AML) sigue haciéndola INFI. Solo tras activarse, el destinatario aparece en GET /v1/recipients y puede usarse en POST /v1/withdraw vía recipientId.
• Idempotente por documento: reenviar el mismo CPF/CNPJ devuelve el mismo recipientId (sin duplicar); un destinatario ya aprobado no se rebaja.
• Name-match: la clave cpf/cnpj debe coincidir con el document. Límite por defecto de 10 destinatarios (activos + en análisis) por cuenta — ajustable por cuenta vía soporte.

Ver Registrar destinatario.

2026-06-02 — Reintento automático de webhook

Las entregas de webhook que fallan por error transiente (timeout, error de red, HTTP 5xx, 429, 408) ahora se reentregan automáticamente con backoff: 1min → 5min → 30min → 2h → 6h (hasta 6 intentos, ~9h). Antes había un único intento automático — la recuperación dependía de polling o reenvío manual.

• 4xx no se reintenta (400/401/403/422…): significa que el endpoint rechazó el evento; martillar no ayudaría. Corrige la causa y usa el reenvío manual.
• eventId se preserva entre intentos — deduplicar por X-Infi-Event-Id es obligatorio. El timestamp y la X-Infi-Signature se regeneran en cada intento; el eventId no.
• Con esto, se recomienda un flujo event-driven: reacciona al webhook + mantén tu saldo desde netCents + concilia ligero, sin polling agresivo de GET /v1/balance.

Cambio de comportamiento, no de contrato: ningún campo nuevo, ninguna acción necesaria para quien ya deduplica por eventId. Ver Reintento e idempotencia.

2026-05-27 — Normalización automática de document.type y pixKeyType + errores más informativos

Cambio aditivo: las solicitudes que ya envían valores correctos siguen funcionando sin ajustes. Lo que cambia es cómo manejamos variaciones y cómo reportamos errores.

Normalización automática (ley de Postel) en campos enum:

• customer.document.type en POST /v1/pix: acepta "CNPJ", "Cpf", " cnpj " etc. — las variaciones de case y whitespace se normalizan internamente a minúsculas. Antes, cualquier no-minúscula se convertía silenciosamente en "cpf" en la sanitización, haciendo que el proveedor rechazara números con tamaño incompatible y generando un 502 Erro ao comunicar com gateway confuso.
• pixKeyType en POST /v1/withdraw: misma normalización — "CPF", "Email", " evp " aceptados.

Validación de tamaño del documento: customer.document.number debe tener 11 dígitos cuando type=cpf o 14 dígitos cuando type=cnpj (tras quitar puntuación). Antes, números con tamaño incompatible eran aceptados por INFI y rechazados por el PSP.

Errores más informativos — todos los mensajes de 400 por validación de payload incluyen ahora el valor recibido (truncado) y lo esperado:

// Antes
{ "error": "Erro ao comunicar com gateway. Tente novamente." }
// status: 502
 
// Ahora
{ "error": "customer.document.type deve ser 'cpf' ou 'cnpj'. Recebido: 'CNPJ '." }
// status: 400

Recomendación: enviar valores en minúsculas sin whitespace es el estándar limpio, pero la API ya no lo exige.

Ver Crear cobro, Iniciar retiro y Errores.

2026-05-09 — Retiro a terceros pre-aprobados vía API

POST /v1/withdraw ganó soporte al campo opcional recipientId para retirar a destinatarios terceros (CPF/CNPJ que no es el titular de la cuenta).

• Sin recipientId (por defecto): comportamiento anterior — solo CPF/CNPJ del titular registrado, otros tipos rechazados.
• Con recipientId: libera los 5 tipos de clave PIX (cpf, cnpj, email, phone, evp) para un destinatario pre-aprobado por el equipo INFI (compliance/AML).

La aprobación del recipientId es manual — contacta a soporte con el nombre legal y CPF/CNPJ del destinatario. No hay endpoint de auto-registro.

Nuevo endpoint GET /v1/recipients devuelve la lista de destinatarios activos pre-aprobados para tu cuenta con los respectivos recipientId — úsalos en POST /v1/withdraw. Ver Listar destinatarios.

Defensas actuales inalteradas: API key, IP allowlist, rate limit, anti-burst, caps diario/mensual, validación de saldo, idempotencia vía externalRef. Cada retiro a tercero dispara alerta interna en INFI (auditoría continua).

Ver Iniciar retiro para schema completo, restricciones por tipo de clave y ejemplos.

2026-05-09 — Datos del PIX en webhooks y consulta REST

Nuevos campos opcionales entregados cuando la transacción fue efectivamente liquidada en la red SPI. Cambio aditivo — los clientes que no los usan los ignoran, sin adaptación.

• Webhooks transaction.paid, transaction.refunded, transaction.partially_refunded ahora traen:

  • endToEndId — E2E ID estándar BACEN del PIX (formato E<ISPB><YYYYMMDDhhmm><id>).
  • payer — quién pagó: { name, document, documentType, bankAccount: { ispb, branch, account } }.

• Webhooks transfer.paid, transfer.refunded, transfer.partially_refunded ahora traen:

  • endToEndId — E2E ID del PIX OUT.
  • beneficiary — quién recibió el retiro: misma estructura de payer.
  • refundEndToEndId — solo en devoluciones (transfer.refunded / transfer.partially_refunded): E2E ID del PIX de devolución, distinto del PIX OUT original.

• REST GET /v1/transactions/:id y GET /v1/transactions devuelven los mismos campos cuando aplica. El polling pasa a ser fallback equivalente al webhook.

Eventos sin liquidación (transaction.failed, cancelled, expired, transfer.created, processing, pending_approval, approved, rejected, failed, cancelled) no traen esos campos — se omiten del JSON, no vienen como null.

Nota LGPD: payer.* y beneficiary.* contienen datos personales (nombre, CPF/CNPJ, cuenta bancaria). Tú eres el controlador del tratamiento posterior. Ver Eventos.

2026-05-08 — Multi-webhook + historial de entregas

• Múltiples URLs de webhook por cuenta (hasta 6). Cada URL filtra eventos por nombre canónico o por categoría semántica (cashin, cashout, refund, dispute, chargeback). Ver Configurando webhook.
• Catálogo de eventos canónicos estandarizado: 21 eventos transaction.* y transfer.*, con nombres estables en X-Infi-Event y en el campo event del cuerpo. Ver Eventos.
• Eventos nuevos entregados por primera vez: transaction.partially_refunded, transaction.infraction, transaction.dispute, transaction.protest, transaction.blocked, transaction.chargeback, transfer.created, transfer.processing, transfer.partially_refunded.
• Header nuevo: X-Infi-Event-Id con un identificador único por evento. Igual entre URLs del fanout y en reenvíos manuales — úsalo para dedup.
• Historial de entregas en el panel (60 días de retención): timeline de cada intento con payload exacto, HTTP status y duración. Disponible en la transacción o en la lista global.
• Reenvío manual de webhook: botón para disparar un nuevo intento de una entrega histórica. eventId se preserva (idempotencia), timestamp y signature se regeneran. Límite 10/h por cuenta. Ver Reenvío manual.

Rupturas de naming (notar si integraste antes de mayo/2026)

Los siguientes nombres fueron reemplazados por los canónicos:

Si comparabas por el nombre antiguo, actualízalo. El status en el cuerpo (campo estable) sigue igual.

2026-05-08 — 2FA en el panel (sin impacto en la API)

• Los comerciantes ahora pueden activar autenticación en dos pasos (TOTP) en el panel, en Configuración → Seguridad.
• Sin cambios en el contrato de la API REST. Las API keys siguen funcionando exactamente como antes — sin código adicional, sin header nuevo, sin cambios en solicitudes o respuestas.
• Los retiros iniciados desde el panel pasan a exigir código TOTP en el momento de la operación. Los retiros vía POST /v1/withdraw quedan inalterados (autenticación por API key + IP allowlist + rate limit).

2026-05 — Lanzamiento de la documentación pública

• Versión inicial cubriendo:
  • POST /v1/pix — creación de cobro PIX.
  • POST /v1/withdraw — retiro PIX.
  • GET /v1/balance — saldo.
  • GET /v1/transactions y GET /v1/transactions/:id — listado y consulta.
  • Webhook único entregado al endpoint configurado por el comerciante, firmado por HMAC.

[POR CONFIRMAR CON EL EQUIPO INFI]: alinear la política de versionado de la API (semver, breaking changes, plazos de deprecación) y el formato definitivo de este changelog.