← BBVA Net CashGUÍA DE INTEGRACIÓN

API BBVA Net Cash

Compra un cupo, conecta tu banco y genera el token en Mis conexiones bancarias. El token permite consultar únicamente esa conexión.

Autenticación

Envía el token en el encabezado. Guárdalo en tu servidor. Al regenerarlo, el anterior deja de funcionar inmediatamente.

Authorization: Bearer TU_TOKEN_DE_CONEXION
Accept: application/json

Base: https://byrperu.com/api/v2/banks/bbva

Consultar cuentas

GET https://byrperu.com/api/v2/banks/bbva/accounts

{"accounts":[{"id":"UUID_DE_CUENTA","label":"Cuenta empresa","currency":"PEN","last4":"1234"}]}

Usa el id público retornado. No envíes números completos de cuenta.

GET /status devuelve el estado de la conexión y las fechas del último intento y actualización.

Consultar movimientos

GET https://byrperu.com/api/v2/banks/bbva/movements?accountId=UUID_DE_CUENTA&from=2026-10-01&to=2026-10-12

accountId, from y to son obligatorios. Fechas YYYY-MM-DD, inicio anterior o igual al fin y diferencia máxima de 366 días. El resultado debe corresponder al rango exacto solicitado.

La respuesta incluye snapshotVersion, lastSuccessAt, ageSeconds, stale, sourceStatus, complete y data con los movimientos disponibles.

Revisa stale y lastSuccessAt antes de conciliar. Se marca como antiguo después de 120 segundos o cuando la fuente no está lista. Una actualización incompleta no reemplaza el último resultado completo.

Solicitar actualización

POST https://byrperu.com/api/v2/banks/bbva/refresh
Authorization: Bearer TU_TOKEN_DE_CONEXION
Idempotency-Key: IDENTIFICADOR_UNICO_DE_TU_SOLICITUD
Content-Type: application/json

{"accountId":"UUID_DE_CUENTA","from":"2026-10-01","to":"2026-10-12"}

Devuelve HTTP 202 con identificador y estado. Consulta GET /jobs/UUID_DEL_TRABAJO. La clave idempotente admite 1–128 caracteres. Repite la misma clave únicamente para la misma solicitud; evita crear trabajos duplicados ante un corte de red.

Las fechas son obligatorias. Puedes omitir accountId para actualizar las cuentas seleccionadas de la conexión. Solo puede haber un trabajo pendiente o en ejecución por conexión.

Respuestas de error

HTTP	Código	Qué hacer
401	invalid_token	Revisa o regenera el token.
403	subscription_expired	Renueva el cupo de esta conexión.
404	account_not_found / snapshot_not_available	Revisa la cuenta o solicita una actualización.
409	connection_requires_action	Reconecta desde el portal.
409	refresh_pending / idempotency_conflict	Consulta el trabajo en curso o usa una clave para la nueva solicitud.