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

# Facturación

> API de Facturación v2 - Emisión masiva de documentos electrónicos

# Introducción a la API de Facturación

La API de Facturación está integrada directamente al **facturador gratuito del SII** y permite emitir documentos de forma masiva usando Batch Documents. El sistema **emite por ti** y además **recibe automáticamente el PDF y XML final** de cada factura a través de webhooks. La integración se apoya en un flujo simple:

1. **obtener tu API Key**
2. **partir en modo Sandbox** (recomendado)
3. **conectar la empresa con [Tupana Link](/api-reference/v2/connect/tupana-link)** (el widget; en v2 no se crean credenciales por API)
4. **crear batches para emitir documentos**
5. **configurar webhooks por empresa para recibir los resultados**
6. **(opcional) usar campos avanzados** como direcciones y actividades económicas personalizadas
7. **monitorear todo desde la plataforma**

<Note>
  En **v2** todo identificador de recurso es un **public ID**: un string con prefijo
  de tipo y número aleatorio (`ment_4829301923847` para una entidad, `docu_…` para
  un documento). No es una codificación del ID interno ni un entero incremental —
  es un identificador propio, imposible de enumerar. Ese `id` es el que usas en las
  rutas y en el cuerpo de las peticiones.
</Note>

## 1) API Key (por usuario)

La API Key es por usuario y sirve para operar sobre todas las empresas enroladas bajo ese usuario.

Existe operación en **Sandbox** y en **Producción**.

Se recomienda comenzar en Sandbox para validar el flujo completo sin riesgos.

## 2) Conectar la empresa con Tupana Link

Antes de emitir, cada empresa tiene que estar conectada, y en v2 la clave no
viaja por API: abres el widget de
[Tupana Link](/api-reference/v2/connect/tupana-link). Tu backend pide un
`client_token`, el usuario entrega la clave adentro del widget, y tú guardas el
`connection_id` (`cred_…`) cuando la conexión queda activa. Las conexiones se
listan y se quitan en
[`/connections/`](/api-reference/v2/connections/list).

Si ya conoces el RUT, mándalo como `tax_id` en la sesión o en la URL del
widget y ese paso no se pide.

## 3) Emisión: crear el Batch Document

Una vez que la empresa está lista, basta con:

* Crear un **Batch Document** con el detalle de las facturas a emitir.
* Usar el flag `use_default` (o equivalente) para que el sistema utilice la configuración/credencial por defecto de esa empresa.

Con eso, el batch queda procesándose y la emisión ocurre de forma automática.

## 4) Webhooks: un webhook por empresa

Para recibir el resultado de cada emisión, debes configurar un webhook por empresa.

También puedes hacerlo:

* **Desde la plataforma**, o
* **Desde la API**: crea un webhook para la empresa.

El webhook es clave porque es el canal donde se envía el estado final y los archivos asociados.

### Ids en los webhooks (`api_version`)

Los webhooks tienen su propio contrato de identificadores, independiente de la
ruta por la que los creaste. El campo `api_version` del webhook define el
formato de **todos** los ids del payload (`data.id`, `sender.id`,
`receiver.id`, programados, folios):

* **`2`:** ids públicos (`docu_…`, `ment_…`), los mismos que devuelve esta API.
* **`1`:** ids enteros. Es el contrato de la API v1 y se conservó en los
  webhooks creados **antes de octubre de 2026** para no romper integraciones
  que validan el id numérico.

Si no mandas `api_version` al crear, el default sigue el contexto: un webhook
creado por `/v2/webhooks/` nace en **2**; uno creado por `/v1/webhooks/` nace
en **1**; desde la plataforma nace en la versión que ya usa la empresa (1 si
tiene algún webhook con enteros, 2 si no). Mandar `api_version` explícito
siempre gana.

Si migraste de v1 a v2 y tus webhooks siguen entregando enteros, súbelos a la
versión 2 con [`PATCH /v2/webhooks/{id}/`](/api-reference/v2/webhooks-pages/update):

```bash theme={null}
curl -X PATCH https://api.tupana.ai/v2/webhooks/dowe_2c9e5a1b7f3d0/ \
  -H "Authorization: Api-Key $TUPANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_version": 2}'
```

También puedes hacerlo desde la plataforma (**Configuración → Webhooks**,
selector *Formato de identificadores*). Para verificar, usa **Probar**: el
`webhook_id` del evento `webhook.test` debe llegar como `dowe_…`. El detalle de
cada payload está en la [guía de webhooks](/user-guide/webhooks#identificadores-en-el-payload).

## 5) Recepción de resultados (XML y PDF)

Una vez configurado el webhook, el sistema **recibe automáticamente del SII** el PDF y XML final de cada factura emitida. Vas a recibir las notificaciones del procesamiento del batch, incluyendo:

* Estado / respuesta de emisión desde el SII
* **XML final** generado por el SII
* **PDF final** generado por el SII

## 6) Opciones avanzadas (direcciones y actividades económicas personalizadas)

Si necesitas direcciones o actividades económicas personalizadas, el flujo es:

1. Pedir la entidad (master entity) por RUT para obtener los datos disponibles
   (direcciones/actividades), cada una con su `id` (`addr_…`, `acti_…`).
2. Incluir esos identificadores en el Batch Document al crear el batch.

Esto te permite controlar con precisión qué dirección/actividad se usa al emitir.

## 7) Monitoreo y trazabilidad en la plataforma

Además de operar por API, puedes revisar todo en la plataforma:

* Vista detallada de empresas enroladas, credenciales, batches y estados.
* **Modo Sandbox** en la plataforma para ver exclusivamente lo que entra por Sandbox.
* **Modo Producción** para ver lo que está en operación real.

Puedes activar/usar Sandbox o Producción según el entorno que estés integrando.

## Convenciones v2

Estas convenciones aplican a **todos** los endpoints v2, de forma uniforme.

### Listas y paginación

Toda respuesta de lista tiene la misma forma:

```json theme={null}
{
  "data": [ { "id": "docu_…", "…": "…" } ],
  "meta": { "page": 1, "page_size": 25, "total": 128, "total_pages": 6 },
  "links": { "next": "…", "prev": null }
}
```

* Controla el tamaño de página con `?page_size=` (**máximo 200**; si pides más se
  recorta a 200).

### Selección de campos (sparse fieldsets)

Pide solo los campos que necesitas con `?fields=`, separados por coma. El `id`
siempre viene incluido. Sirve para respuestas más livianas:

```bash theme={null}
GET /v2/documents/?fields=folio,amount,status
```

### Errores

Formato único `{ "error": { "type", "code", "message", … } }` — ver
[Errores](/api-reference/v2/errors). Los errores internos (≥500) devuelven un
mensaje genérico + `request_id` (nunca detalle crudo del servidor).

### Campos desconocidos y validación estricta

Los documentos del batch se comparan con los campos que acepta la API. Un campo
desconocido nunca se usa al emitir:

* **Modo aviso:** el documento se crea sin ese campo y la respuesta trae un
  arreglo `warnings` con `document_index`, `field`, `code` (`unknown_field`),
  `message` y `suggestion` (el campo correcto, si se reconoce).
* **Validación estricta (por API key):** la API responde `422` con el error bajo
  `documents` → posición del documento → ruta del campo (el mismo cuerpo que v1) y
  no crea el batch. Está activada en las **API keys
  nuevas**; las integraciones existentes reciben primero `warnings` para corregir
  sus campos.

Ver [Errores](/api-reference/v2/errors).

## Endpoints relacionados

* **[Tupana Link](/api-reference/v2/connect/tupana-link)** — Conectar una empresa (widget)
* **Listar Credenciales** — Ver conexiones ya activas
* **Listar Documentos** — Consultar documentos emitidos
* **Obtener Documento Específico** — Ver detalles de un documento
* **Consultar Estados de Documento** — Ver historial de estados
* **Registrar Estado de Documento** — Registrar eventos manualmente


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