Tupana Link

El widget que abres en tu app para que tu usuario final conecte su empresa. La clave del SII (o del facturador, o del banco) viaja a Tupana. Tu backend nunca la ve. En v2 la clave no se manda por API: conectas con este widget y guardas el connection_id (cred_…), que es lo único que tu SaaS conoce de la empresa.

Integra en tres llamadas

Tu backend abre una sesión

POST /api/v2/connect-sessions/ con tu API key. Te devuelve un client_token de 30 minutos. Si ya conoces el RUT, mándalo como tax_id y el widget no lo vuelve a pedir.

curl -X POST "https://app.tupana.ai/api/v2/connect-sessions/" \
  -H "Authorization: Api-Key TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["invoicing"],
    "app_name": "Mi SaaS",
    "tax_id": "78.152.641-K",
    "external_customer_id": "cus_912"
  }'

{
  "connect_session_id": "cses_7391028471023",
  "client_token": "cst_9f2b…",
  "expires_at": "2026-09-25T18:30:00Z"
}

Tu frontend abre el widget

Iframe o ventana. El token es el client_token. tax_id en la URL gana sobre el de la sesión.

<iframe src="https://developers.tupana.ai/connect?token=cst_9f2b…&tax_id=78.152.641-K"
        width="460" height="660" frameborder="0"></iframe>

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://developers.tupana.ai') return;
  if (event.data.source !== 'tupana-connect') return;

  if (event.data.event === 'success') {
    // event.data.connection_id → "cred_…" (es la credencial)
    closeModal();
  }
  if (event.data.event === 'exit') closeModal();
});

`event`	Para qué
`open`	El widget cargó
`success`	El flujo terminó. Cierra el modal. No es la fuente de verdad
`exit`	El usuario cerró antes de terminar

Igual que el widget de Fintoc: success y exit solo mueven tu interfaz. La conexión existe cuando tu backend recibe connection.active o GET /api/v2/connections/enrollments/{enrollment_id}/ la muestra lista.

Tu backend guarda la conexión

Cuando el SII valida la clave, el webhook trae el cred_…. Con eso emites. También puedes listarlas con GET /connections/.

{
  "event": "connection.active",
  "data": {
    "connection_id": "cred_5028174639201",
    "company_id": "ment_4829301923847",
    "external_customer_id": "cus_912"
  }
}

Body de la sesión

Campo	Requerido	Qué hace
`capabilities`		`invoicing`, `sii_data`, `banking`. Default `["invoicing"]`
`tax_id`		RUT de la empresa. El widget salta ese paso
`app_name`		El nombre que ve el usuario adentro
`external_customer_id`		Tu id de cliente. Vuelve en el webhook
`environment`		`sandbox` o `production`. Default: el de la API key
`return_url`		A dónde vuelve al terminar

Parámetro	Requerido	Qué hace
`token`	Sí	El `client_token`
`tax_id`		RUT. Si viene acá y en la sesión, gana la URL
`rut`		Alias de `tax_id`

El client_token es de un solo uso y dura 30 minutos. Créalo cuando el usuario va a conectar, no antes. Una API key de sandbox no abre producción.

Lo que ve tu usuario

SII gratuito
Facturador de mercado
Banco

Widget: RUT de la empresa — RUT de la empresa — no aparece si mandaste tax_id.

Widget: SII gratuito — Detectamos SII. El RUT del representante se formatea solo.

Cuándo el enrolamiento es exitoso

El widget de Fintoc no avisa éxito al recibir la clave. Se queda en pantalla mientras el banco responde. Si la clave está mala, el error queda adentro y el usuario reintenta: no hay onSuccess. onSuccess sale cuando el flujo terminó (el banco aceptó y existe el Link). onExit sale solo si la persona cierra antes. Fintoc pide no usar esos callbacks para saber si el Link existe: eso lo confirma el webhook link.created en el webhookUrl, que trae el link_token. Tupana Link funciona igual. El postMessage mueve tu modal. El webhook dice si la credencial quedó.

Qué ves	Qué significa
`success`	El flujo terminó. Cierra el modal y guarda el `connection_id`
`exit`	Cerró antes de terminar. No hay conexión nueva
`connection.active`	La institución aceptó la clave. Esta es la confirmación
`connection.requires_action`	La clave no sirvió. El widget deja reintentar

SII

El login no termina en el request. La respuesta trae status: "connecting" y un enrollment_id (cenr_…). El widget espera en ws/connect/{client_token}/ y manda success solo con valid.

{
  "enrollment_id": "cenr_8420193847261",
  "company_id": "ment_4829301923847",
  "status": "connecting"
}

Puedes esperar el webhook o consultar GET /api/v2/connections/enrollments/{enrollment_id}/ hasta valid, invalid o error.

Banco

El widget no manda success cuando guarda la clave. Se queda en “estamos leyendo tus cuentas” hasta que el banco contesta.

El banco aceptó y hay cuentas: el widget las muestra y ahí manda success con el cred_…. Tu backend recibe connection.active.
La clave es inválida: el error queda en el widget, el usuario puede corregirla, y no hay success. Tu backend recibe connection.requires_action.
El usuario cierra antes: exit. Eso no confirma la conexión. Si el banco igual acepta la clave, llega connection.active.

Guardar la clave con estado interno VALID no es la confirmación. La confirmación es connection.active, cuando el banco ya listó las cuentas. Los movimientos no vienen en ese aviso. Cuando la cartola está sincronizada se leen como documentos tipo 100: GET /api/v2/documents/?master_entity_id={empresa}&dte_type__code__in=100. Responde 2xx al webhook y procesa después. Puede llegarte dos veces. Para ver o cortar conexiones usa GET /connections/ y DELETE /connections/{connection_id}/, que la deja inactive y suelta la clave.

Qué viaja por tu app

	Tu aplicación	Tupana
Clave del SII / facturador / banco	Nunca	Cifrada
Credencial (`cred_…`)	Sí	Sí
Documentos, movimientos, registros	Sí	Sí

Introducción

Entidades

Conexiones

Documentos

Estados de Documentos

Documentos Programados

Webhooks

Errores

Tupana Link

Tupana Link

Integra en tres llamadas

Body de la sesión

Query del widget

Lo que ve tu usuario

Cuándo el enrolamiento es exitoso

SII

Banco

Qué viaja por tu app

​Tupana Link

​Integra en tres llamadas

​Body de la sesión

​Query del widget

​Lo que ve tu usuario

​Cuándo el enrolamiento es exitoso

​SII

​Banco

​Qué viaja por tu app

Tupana Link

Integra en tres llamadas

Body de la sesión

Query del widget

Lo que ve tu usuario

Cuándo el enrolamiento es exitoso

SII

Banco

Qué viaja por tu app