APILista de migración
Qué revisar en tu integración tras los ajustes del contrato v1.
Si integraste antes del 5 de noviembre de 2026, revisa esta lista una vez. Ninguna fila quita un campo ni una ruta, pero varias cambian una respuesta que tu código pudo haber asumido. El detalle de cada cambio está en Cambios.
Beneficiarios y latam
| Antes | Ahora | Qué hacer |
|---|---|---|
Un alta latam inválida quedaba en 202 processing | Responde 422 invalid_beneficiary | Maneja ese 422, corrige los datos y usa una clave nueva. Ver Pago LatAm |
El alta latam no recibía tipo de cuenta, y Perú no se podía registrar | Acepta account_type, y Perú lo exige | Envíalo cuando account_type_required sea true |
| Países y bancos se pedían a tu ejecutivo | GET /v1/latam/countries y GET /v1/latam/countries/{country}/entities | Consúltalos en vez de fijarlos en tu código |
Pagos y errores
| Antes | Ahora | Qué hacer |
|---|---|---|
failure_code podía ser null en un pago failed | Nunca es null en un pago failed, tampoco si el detalle ya no se puede leer | Quita la rama de failed sin código. Sigue tolerando códigos nuevos |
Los eventos payment.* no traían failure_code | Todos lo traen, con valor sólo en payment.failed | Léelo del evento si te sirve |
Un rechazo registrado podía decir retryable: true | Siempre dice retryable: false, también con in_review | Decide por retryable de la respuesta, no por el código. Ver Qué hacer con la clave tras un rechazo |
| El tope del cuerpo no estaba declarado | 413 a partir de 64 KB, con el código invalid_request | Parte los lotes grandes. Repetir no sirve. Ver Límites |
Una Idempotency-Key con otro cuerpo dejaba de rechazarse a los 7 días | 422 idempotency_key_reused también después | No reutilices claves |
Cobros y altas con 202
| Antes | Ahora | Qué hacer |
|---|---|---|
POST /v1/collections no comprobaba payer: en la cuenta de prueba, un cobro por SPEI sin payer daba 201 | Sin un required, o fuera de options, responde 400 invalid_request con payer.<campo> en details.fields. La prueba por SPEI pide firstName, lastName y email | Envía payer según payer_fields. El cuerpo corregido necesita otra Idempotency-Key |
Las claves de payer se pedían a tu ejecutivo | payer_fields de GET /v1/collection-methods las da por método | Arma payer desde esa lista. Ver Cobros |
GET /v1/collections/{id} no daba instruction.type ni expires_at | Los da | Quita la copia que guardabas del alta |
Repetir la clave tras un 202 de POST /v1/collections, POST /v1/deposit-addresses o POST /v1/beneficiaries repetía ese 202 | Entrega el resultado en cuanto existe | Repite con la misma clave hasta tener el resultado |
Webhooks y eventos
| Antes | Ahora | Qué hacer |
|---|---|---|
Los webhooks no traían resource_id | Lo traen, igual que GET /v1/events | Úsalo para agrupar por recurso |
Event.type, Event.data y WebhookEndpoint.status eran abiertos en el contrato | Son enumeraciones y formas declaradas | Regenera tu cliente. Sigue ignorando los tipos que no conozcas |
system.egress_ips.changing no se emitía | Trae ip, change, effective_at y un resource_id con egr_. Llega una vez por destino, también al que se activa hasta una hora antes del cambio | Vigílalo si filtras por IP. Ver IP de webhooks |
| No había una respuesta sobre gestionar destinos por API | v1 sólo los consulta, por decisión: todo cambio va por el panel | No esperes esas operaciones. Ver Dar de alta un destino |
Movimientos, recibos y llaves
| Antes | Ahora | Qué hacer |
|---|---|---|
Una fila de GET /v1/movements que cambiaba podía perderse | Puede repetirse, y nunca se omite otra | Deduplica por id y guarda next_cursor en cada página. Ver Paginación |
completed_at podía traer fecha en un recibo no completado | null si el movimiento no terminó en completed | No lo uses para fechar un pago devuelto |
| El calendario de avisos de caducidad no estaba publicado | Producción caduca a 180 días, y el panel avisa a 30, 7 y 1 días | Prevé la rotación. Ver Vencimiento |
Cuenta de prueba
| Antes | Ahora | Qué hacer |
|---|---|---|
POST /sandbox/v1/webhooks/trigger mandaba un data reducido | Manda la forma real de cada tipo, con datos ficticios y simulated: true | Prueba tu receptor con todos los tipos |
No había catálogo latam | GET /sandbox/v1/latam/countries da países ficticios con available: false | No esperes un alta latam aquí: responde 403 rail_not_enabled |
Errores comunes
- Tratar un
202de alta como un fallo y cambiar de clave. - Copiar la tabla de países en tu código en vez de consultar la API.
- Corregir
payery repetir con la misma clave.