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

# Primera lectura de un banco

> Conecta un banco con Tupana Link, lista las cuentas y trae los movimientos del mes

# Primera lectura de un banco

De cero a los movimientos del mes en cuatro llamadas. Necesitas una API key
con el permiso `banking:read` escrito en ella.

**1. Conecta el banco con Tupana Link**

Crea una sesión con `capabilities: ["banking"]` y abre el widget para tu
usuario. Él elige el banco y entra con su clave; tú nunca la ves.

```bash theme={null}
curl -X POST https://api.tupana.ai/v2/connect-sessions/ \
  -H "Authorization: Api-Key TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capabilities": ["banking"], "tax_id": "76.830.546-3", "app_name": "Mi SaaS" }'
```

Cuando el banco acepta la clave recibes `connection.active` con el
`connection_id` (`cred_…`). Guárdalo: es la conexión.

**2. Lista las cuentas de esa conexión**

```bash theme={null}
curl "https://api.tupana.ai/v2/bank-accounts/?connection_id=cred_9Pq5028174639201" \
  -H "Authorization: Api-Key TU_API_KEY"
```

Cada cuenta trae `type`/`subtype`, `number_mask` y `balances` con
`refreshed_at`. Ese es el saldo de la última lectura: la API nunca va al
banco cuando la llamas.

**3. Trae los movimientos del mes**

```bash theme={null}
curl "https://api.tupana.ai/v2/bank-accounts/bacc_7Hk2938475610293/movements/?since=2026-10-01&until=2026-10-31" \
  -H "Authorization: Api-Key TU_API_KEY"
```

Pagina con `page` hasta que `links.next` sea `null`.

**4. Interpreta direction, status y counterparty**

* `amount` no lleva signo: `direction: "inbound"` entró, `"outbound"` salió.
* `status: "pending"` todavía no está contabilizado; puede desaparecer o
  volver como `posted`. Trabaja con `posted` para cerrar el mes.
* `counterparty` trae a quien pagó o cobró, con RUT cuando Tupana lo
  resuelve. `category` dice qué es el dinero.

## Cuándo volver a leer

Tupana lee cada banco en su propio ciclo y `refreshed_at` te dice cuándo fue la
última vez. Llamar más seguido no trae datos más frescos. Si una conexión pasa
a `requires_action`, el usuario tiene que
[reautorizarla](https://docs.tupana.ai/api-reference/v2/connections/reauthorize.md).


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