API Bancaria
La API Bancaria te da lectura de lo que las empresas conectadas a tu integración tienen en el banco. El usuario final conecta su banco dentro de Tupana Link; tu SaaS nunca ve la clave, y desde ahí Tupana lee el banco todos los días. Publica instituciones, conexiones, cuentas con sus saldos y movimientos con la contraparte resuelta. Para empezar, sigue la guía Primera lectura de un banco.Permiso
Las cuentas y los movimientos exigen una API key conbanking:read escrito
en ella. El comodín * que traen las keys al crearse no lo concede: los saldos
son de un tercero y no salen por una key que nunca pidió verlos. Sin él, 403
con código banking_permission_required.
El modelo
La conexión de banco es la misma
connection_id que devuelve Tupana Link y que
lista GET /connections/ con type: "bank".
Su provider es el banco (santander, estado, bci…) y su source dice por
dónde lee Tupana: fintoc (proveedor de bancos), scraper (conector propio) o
manual_upload (cartolas subidas a mano). Para ti es informativo: los datos se
leen igual.
Quién es el titular
La conexión pertenece a la persona que entró al banco, no a la empresa. Por eso una gestora que opera varias empresas con el mismo login tiene una conexión asociada a variascompany_id, y por eso al reautorizar una conexión
compartida hay que decir a qué empresa te refieres.
Estados
Los cambios de estado llegan por webhook:
connection.active,
connection.requires_action y connection.degraded.
Por qué no hay refresh bajo demanda
NingúnGET de esta API toca al banco: devuelve lo que dejó la última lectura,
con balances.refreshed_at. Cada lectura extra es riesgo de bloqueo para la
cuenta del usuario, así que no hay un botón para forzarla. La frescura la marca
el ciclo de sincronización de Tupana, y tu backend se entera por webhook:
suscríbete a bank_account.refreshed y movement.created (ver
Webhooks bancarios).
Lo que nunca se expone
- La clave del banco. Viaja del usuario final a Tupana dentro del widget.
- Los tokens con que Tupana lee el banco.
- Conexiones de empresas que no son de tu integración: para tu API key no existen (
404).
Todo lo de esta API vive en v2. Los identificadores son public IDs con
prefijo (
cred_…, ment_…); las listas van en data.