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

# Crear sesión de Tupana Connect (API v2)

> Crea la sesión de corta duración con la que tu frontend abre el widget de Tupana Connect. La llama tu backend con tu API key; al navegador solo llega el client_token.

Es el primer paso de [Tupana Connect](https://docs.tupana.ai/api-reference/v2/connect/tupana-connect.md):
tu backend crea la sesión con su API key y le pasa al frontend solo el
`client_token`. Tu API key nunca va al navegador y la clave del SII de tu
usuario nunca pasa por tu código.

## Abrir el widget

Con el token abres `https://developers.tupana.ai/connect?token=…` en un iframe
o en una ventana. El token dura 30 minutos y sirve una sola vez: créalo justo
cuando tu usuario hace clic en "Conectar empresa".

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

## Confirmar la conexión

El widget te avisa por `postMessage` con `event: "success"` cuando el usuario
termina, pero eso solo sirve para cerrar tu modal. La conexión es real cuando
tu backend recibe el webhook `connection.active`; si la clave estaba mala,
llega `connection.requires_action`. Después la ves en
[Listar conexiones](https://docs.tupana.ai/api-reference/v2/connections/list.md) con su `company_id`.


## OpenAPI

````yaml api-reference/openapi-v2.json POST /connect-sessions/
openapi: 3.0.0
info:
  title: Tupana API — v2
  description: >-
    API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
    boleta de honorarios y nómina. Los identificadores de recursos son public
    IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
  version: 2.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
security:
  - apiKeyAuth: []
paths:
  /connect-sessions/:
    post:
      tags:
        - Conexiones
      summary: Crear sesión de Tupana Connect
      description: >-
        Crea una sesión de corta duración para abrir el widget de Tupana
        Connect. La llama tu backend con tu API key; al frontend solo le pasas
        el `client_token`, que dura 30 minutos y sirve una sola vez. La conexión
        queda confirmada cuando recibes el webhook `connection.active`, no con
        el evento `success` del widget.
      operationId: createConnectSession_v2
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                capabilities:
                  type: array
                  items:
                    type: string
                    enum:
                      - invoicing
                      - sii_data
                      - banking
                  default:
                    - invoicing
                  description: >-
                    Qué podrá hacer la conexión: `invoicing` emite documentos,
                    `sii_data` lee el registro de compras y ventas, `banking`
                    lee cuentas y movimientos. Puedes pedir varias.
                tax_id:
                  type: string
                  example: 78.152.641-K
                  description: >-
                    RUT de la empresa a conectar. Si lo mandas, el widget no lo
                    vuelve a pedir.
                app_name:
                  type: string
                  maxLength: 120
                  example: Mi ERP
                  description: Nombre de tu app, se muestra dentro del widget.
                external_customer_id:
                  type: string
                  maxLength: 120
                  example: cust_8841
                  description: >-
                    Tu identificador del cliente. Vuelve en los webhooks de la
                    conexión.
                return_url:
                  type: string
                  format: uri
                  example: https://mi-erp.cl/integraciones/tupana
                  description: >-
                    Si abres el widget en una ventana en vez de un iframe,
                    adónde vuelve al terminar.
                environment:
                  type: string
                  enum:
                    - sandbox
                    - production
                  description: >-
                    Por defecto sigue al ambiente de tu API key. Una key de
                    sandbox solo puede abrir sesiones sandbox.
              example:
                capabilities:
                  - invoicing
                app_name: Mi ERP
                external_customer_id: cust_8841
      responses:
        '201':
          description: Sesión creada
          content:
            application/json:
              schema:
                type: object
                properties:
                  connect_session_id:
                    type: string
                    example: cses_4829301923847120394
                    description: Id de la sesión, con prefijo `cses_`.
                  client_token:
                    type: string
                    example: cst_9f2b7c1e4d8a...
                    description: >-
                      Token para abrir el widget:
                      `https://developers.tupana.ai/connect?token=…`. Se muestra
                      una sola vez.
                  expires_at:
                    type: string
                    format: date-time
                    example: '2026-10-29T19:45:00+00:00'
        '400':
          description: >-
            Payload inválido (capability desconocida, lista vacía, ambiente no
            permitido para la key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: capabilities debe ser una lista con al menos un valor.
        '402':
          description: Developer sin tarjeta registrada abriendo Connect en producción
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API Key para autenticación. Debe proporcionarse en el header
        Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo
        'Api-Key ' seguido de tu API key)

````

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