Skip to main content

​
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 (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
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.

​
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. Antes de emitir, cada empresa tiene que estar conectada, y en v2 la clave no viaja por API: abres el widget de 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/. 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}/:
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.

​
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:
  • 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:

​
Errores

Formato único { "error": { "type", "code", "message", … } } — ver Errores. 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.

​
Endpoints relacionados

  • 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