> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tupana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Bancaria — Introducción

> Lee las conexiones bancarias de tus empresas: qué bancos existen, cómo se conectan con Tupana Link y qué significa cada estado — API v2

# 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](https://docs.tupana.ai/api-reference/v2/connect/tupana-link.md); tu SaaS nunca ve la clave,
y desde ahí Tupana lee el banco todos los días.

Publica **instituciones**, **conexiones**, **cuentas** con sus saldos,
**movimientos** con la contraparte resuelta, la **sincronización por cursor**
y los **eventos** consultables. Para empezar, sigue la guía
[Primera lectura de un banco](https://docs.tupana.ai/api-reference/v2/banking/guides/first-sync.md);
para mantener una copia al día, [Sincronizar con cursor](https://docs.tupana.ai/api-reference/v2/banking/guides/sync.md);
para probar sin un banco real, [Sandbox bancario](https://docs.tupana.ai/api-reference/v2/banking/guides/sandbox.md);
para las tarjetas, [Tarjetas de crédito](https://docs.tupana.ai/api-reference/v2/banking/guides/credit-cards.md).

## Permiso

Las cuentas y los movimientos exigen una API key con **`banking: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

| Recurso | Qué es | Id |
| - | - | - |
| Empresa | La empresa cuyos datos lees. Es la misma de toda la API. | `ment_…` |
| Conexión | Un login de una persona en una institución. Una empresa puede tener una conexión por banco; una misma persona puede cubrir varias empresas con una sola conexión. | `cred_…` |
| Institución | Un banco que se puede conectar y lo que entrega. | `code` (`cl_banco_santander`) |
| Cuenta | Una cuenta en una institución: corriente, vista, ahorro, tarjeta o línea. Cuelga de una conexión y de una empresa. | `bacc_…` |
| Movimiento | Un abono o cargo en una cuenta, con la glosa cruda del banco y la contraparte que Tupana resuelve. | `move_…` |
| Estado de cuenta | La cartola de un período: de una tarjeta o importada a una cuenta corriente, con su PDF original. | `ccs_…` / `bsu_…` |

La conexión de banco es la misma `connection_id` que devuelve Tupana Link y que
lista [`GET /connections/`](https://docs.tupana.ai/api-reference/v2/connections/list) 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 varias `company_id`, y por eso al reautorizar una conexión
compartida hay que decir a qué empresa te refieres.

## Estados

| `status` | Qué significa | Qué hacer |
| - | - | - |
| `active` | La conexión sirve y se está leyendo. | Nada. |
| `pending` | Conector propio: todavía no terminó la primera lectura. | Esperar `connection.active`. |
| `requires_action` | El banco pidió volver a entrar, o la clave dejó de servir. | [Reautorizar](https://docs.tupana.ai/api-reference/v2/connections/reauthorize.md): el usuario final vuelve a entrar en Tupana Link y la conexión conserva su id. |
| `degraded` | Alguna cuenta quedó detenida tras fallos repetidos; las demás siguen. | Nada por tu lado; Tupana la revisa. Si persiste, reautorizar. |
| `inactive` | Alguien la desactivó con [`DELETE`](https://docs.tupana.ai/api-reference/v2/connections/delete). | Volver a conectar con Tupana Link si hace falta. |

Los cambios de estado llegan por webhook: `connection.active`,
`connection.requires_action` y `connection.degraded`.

## Por qué no hay refresh bajo demanda

Ningún `GET` 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](https://docs.tupana.ai/api-reference/v2/banking/webhooks.md)).

## Sandbox

Con una API key de sandbox, los mismos endpoints responden con un set de datos
sintético en tus propias empresas: tres cuentas y \~120 movimientos que cambian
todos los días, con webhooks, eventos y cursor funcionando igual que en
producción. Nada de eso existe para una key de producción. Ver
[Sandbox bancario](https://docs.tupana.ai/api-reference/v2/banking/guides/sandbox.md).

## 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`).

> [!NOTE]
>
> Todo lo de esta API vive en **v2**. Los identificadores son public IDs con
> prefijo (`cred_…`, `ment_…`); las listas van en `data`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.