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

# Leer movimientos bancarios de tus clientes por API

> Conecta el banco de cada cliente con Tupana Link y lee sus abonos y cargos por la API v2: sesión, webhook connection.active, documentos 100 y 101 y aviso document.paid.

Esta guía conecta el banco de un cliente de tu SaaS y lee sus movimientos desde tu backend. La clave del banco la escribe tu cliente dentro de Tupana Link: tu sistema nunca la ve y solo guarda un `connection_id` (`cred_…`). La conexión es de solo lectura: no puede mover dinero.

## Bancos disponibles en Tupana Link

Banco de Chile, Santander, BancoEstado, BCI, Itaú, Scotiabank, Security, BICE y Falabella. Para cuentas de empresa y de persona.

## 1. Abre una sesión con `banking`

Desde tu backend, con tu API key. Si ya conoces el RUT de la empresa, mándalo como `tax_id` y el widget no lo vuelve a pedir.

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

La respuesta trae un `client_token` de un solo uso que dura 30 minutos. Con una API key de sandbox la sesión es de sandbox y nada toca un banco real.

## 2. Abre el widget en tu frontend

```html theme={null}
<iframe src="https://developers.tupana.ai/connect?token=cst_9f2b…"
        width="460" height="660" frameborder="0"></iframe>
```

Tu cliente elige su banco, escribe el RUT de la persona que entra a la cuenta y su clave. El widget espera la respuesta del banco y le muestra sus cuentas. El detalle de eventos (`open`, `success`, `exit`) está en [Tupana Link](/api-reference/v2/connect/tupana-link).

## 3. Confirma la conexión por webhook

`success` en el widget solo mueve tu interfaz. La confirmación llega a tu backend:

| Evento | Qué significa |
| - | - |
| `connection.active` | El banco aceptó la clave y listó las cuentas. Guarda el `connection_id` y el `company_id` |
| `connection.requires_action` | La clave no sirvió. El widget deja reintentar |

```json theme={null}
{
  "event": "connection.active",
  "data": {
    "connection_id": "cred_5028174639201",
    "company_id": "ment_4829301923847",
    "type": "bank",
    "status": "active",
    "external_customer_id": "cus_912"
  }
}
```

Suscríbete a estos eventos con [`POST /v2/webhooks/`](/api-reference/v2/webhooks-pages/create). Responde 2xx y procesa después: el mismo aviso puede llegar dos veces.

## 4. Lee los movimientos

Cada movimiento sincronizado queda como un documento de pago de la empresa: tipo `100` para los abonos (entradas de dinero) y tipo `101` para los cargos (salidas). Se leen con el mismo endpoint de documentos:

```bash theme={null}
curl "https://api.tupana.ai/v2/documents/?master_entity_id=ment_4829301923847&dte_type__code__in=100,101&issue_date_gte=2026-10-01&page_size=100" \
  -H "Authorization: Api-Key $TUPANA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "docu_9f2a7c1b8e4d0",
      "dte_type_code": "100",
      "folio": null,
      "date_issued": "2026-10-14",
      "amount_with_iva": 595000
    }
  ],
  "meta": { "page": 1, "page_size": 100, "total": 1, "total_pages": 1 },
  "links": { "next": null, "prev": null }
}
```

Con los SDKs oficiales es la misma llamada:

```ts Node.js theme={null}
import Tupana from "tupana";

const tupana = new Tupana(); // lee TUPANA_API_KEY
for await (const mov of tupana.documents.listAutoPaging({
  master_entity_id: "ment_4829301923847",
  dte_type__code__in: ["100", "101"],
  issue_date_gte: "2026-10-01",
})) {
  console.log(mov.date_issued, mov.dte_type_code, mov.amount_with_iva);
}
```

```python Python theme={null}
from tupana import Tupana

tupana = Tupana()  # lee TUPANA_API_KEY
for mov in tupana.documents.list_auto_paging(
    "ment_4829301923847",
    dte_type__code__in=["100", "101"],
    issue_date_gte="2026-10-01",
):
    print(mov["date_issued"], mov["dte_type_code"], mov["amount_with_iva"])
```

## Cada cuánto se actualizan

Tupana sincroniza las cuentas conectadas cada hora y deduplica los movimientos, así que leer dos veces el mismo rango no trae repetidos. Lee por fecha (`issue_date_gte`) desde la última vez que consultaste.

## 5. Entérate cuando una factura queda pagada

Cuando un abono se concilia con una factura emitida, Tupana envía `document.paid` con la factura pagada. Si la conciliación se revierte, llega `document.unpaid`. Así tu sistema marca la factura como cobrada sin cruzar montos por su cuenta. Detalle de los payloads en la [guía de webhooks](/user-guide/webhooks).

## Cortar la conexión

[`DELETE /v2/connections/{connection_id}/`](/api-reference/v2/connections/delete) la deja `inactive` y suelta la clave. Para listar las conexiones de tus clientes usa [`GET /v2/connections/`](/api-reference/v2/connections/list).

## Precio

La lectura bancaria cuesta **0,35 UF al mes por banco** conectado, más IVA, con movimientos sincronizados sin límite. El sandbox es gratis. Detalle en [Precios](/precios).

> **[Leer el SII por API](/guias/lectura-sii)**
>
> Registro de compras y ventas, DTE emitidos y recibidos y boletas de honorarios.

> **[Tupana Link](/api-reference/v2/connect/tupana-link)**
>
> Sesión, widget, eventos y confirmación por webhook.


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