Tupana Connect

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://api.tupana.ai/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

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.

Reautorizar un banco

Cuando una conexión de banco queda en requires_action, no abras una sesión desde cero: POST /connections/{connection_id}/reauthorizations/ te devuelve un client_token con la empresa y el banco ya elegidos, y la conexión conserva su connection_id al terminar.

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 no avisa éxito al recibir la clave. Se queda en pantalla mientras la institución responde. Si la clave está mala, el error queda adentro y el usuario reintenta: no hay success. success sale cuando el flujo terminó; exit sale solo si la persona cierra antes. 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 Connect: conectar empresas al SII desde tu SaaS

Tupana Connect

Integra en tres llamadas

Body de la sesión

Query del widget

Reautorizar un banco

Lo que ve tu usuario

Cuándo el enrolamiento es exitoso

SII

Banco

Qué viaja por tu app

​Tupana Connect

​Integra en tres llamadas

​Body de la sesión

​Query del widget

​Reautorizar un banco

​Lo que ve tu usuario

​Cuándo el enrolamiento es exitoso

​SII

​Banco

​Qué viaja por tu app

Tupana Connect

Integra en tres llamadas

Body de la sesión

Query del widget

Reautorizar un banco

Lo que ve tu usuario

Cuándo el enrolamiento es exitoso

SII

Banco

Qué viaja por tu app