API de factura electrónica y API SII para Chile: emite DTE desde tu propio sistema

La API de factura electrónica de Tupana es una API SII REST: emite facturas, boletas, notas de crédito, guías de despacho y documentos de exportación al SII desde tu software. Envías hasta 500 documentos en una llamada, recibes el resultado por webhook y operas muchas empresas con una sola integración. Cada empresa emite con el facturador de mercado de Tupana o con el facturador gratuito del SII: tu integración es la misma.

De tu sistema al SII en cuatro pasos

La API vive en https://api.tupana.ai/v2/ y se autentica con una llave en el encabezado Authorization: Api-Key. Todo es JSON. El flujo de emisión es asíncrono: la API recibe tus documentos, los valida, los timbra y los envía al SII, y te avisa cuando cada uno queda aceptado o rechazado.

La referencia completa de cada endpoint está en docs.tupana.ai y la especificación está publicada en OpenAPI v2, para que generes un cliente en tu lenguaje.

Hay SDKs oficiales para Node.js y Python: npm install tupana (npm, GitHub) y pip install tupana (PyPI, GitHub). Traen reintentos, Idempotency-Key automático, errores tipados y verificación de webhooks, y el mismo código sirve en sandbox y en producción: solo cambia la key.

  1. Crea tu llave: En la consola de developers.tupana.ai generas tu API key. Las llaves nuevas parten en el ambiente de pruebas.
  2. Conecta las empresas: Cada empresa que va a emitir se conecta con su credencial del SII. Puedes administrar muchas desde la misma integración.
  3. Envía un lote: Haces un POST /v2/documents/batch/ con uno o hasta 500 documentos. La API responde de inmediato y procesa el lote en segundo plano.
  4. Recibe el resultado: Te llega un webhook por cada cambio de estado: emitido, rechazado, entregado al receptor. Con eso actualizas tu sistema sin consultar en bucle.

Qué documentos puedes emitir por API

El campo dte_type define qué documento emites. Si no lo envías, la API asume factura electrónica (33). Puedes referenciar órdenes de compra, HES y otros documentos en cada DTE. Si tienes dudas sobre cuál corresponde, revisa la guía de tipos de documentos tributarios.

DTE 33 · Factura electrónica

El documento base para ventas afectas a IVA entre empresas.

DTE 34 · Factura exenta

Ventas y servicios exentos. Las líneas exentas mezcladas con afectas solo se permiten con el facturador de mercado.

DTE 39 y 41 · Boleta electrónica

Afecta y exenta, para ventas a consumidor final, por ejemplo al confirmar un pago en tu tienda.

DTE 61 y 56 · Notas de crédito y débito

Anulan o corrigen un documento ya emitido, referenciándolo.

DTE 52 · Guía de despacho

Con los tipos de traslado del SII, para mover mercadería con o sin venta.

DTE 46 · Factura de compra

La emite quien compra cuando el vendedor no factura, con retención de IVA.

DTE 110, 111 y 112 · Exportación

Factura, nota de débito y nota de crédito de exportación.

Honorarios · Boleta de honorarios

Se emite a través del portal del SII con la clave de la persona; no pasa por el facturador de mercado.

Facturador de mercado o facturador gratuito del SII: tú eliges

Cada empresa conectada emite con uno de los dos caminos y tu código no cambia. Con el facturador de mercado de Tupana, la API timbra y envía el documento directamente al SII y maneja los folios por ti. Con el facturador gratuito del SII, Tupana opera el portal con la clave de la empresa.

El precio es el mismo en los dos casos. La diferencia está en los límites del facturador gratuito: hasta 3 referencias y 10 líneas de detalle por documento, alrededor de $100 millones por factura y del orden de 600 a 700 facturas al mes. Si tus clientes emiten documentos largos o en volumen, el facturador de mercado admite hasta 60 líneas y 40 referencias por documento, sin esos topes de monto ni de cantidad. Más detalle en ¿Facturador del SII o facturador de mercado?.

  • Folios (CAF) solicitados al SII de forma automática cuando hacen falta.
  • XML timbrado, PDF y estado del SII disponibles para cada documento.
  • Envío automático del documento por correo al receptor, si lo configuras.
  • Cesión de facturas al factoring disponible en la API v2.

Te avisamos cuando algo cambia

Registras una URL y Tupana te envía un POST por cada evento. Cada aviso va firmado con HMAC-SHA256 en el encabezado X-Pana-Signature, para que verifiques que viene de Tupana antes de procesarlo. Puedes enviar un evento webhook.test para probar tu endpoint.

Documentos

document.issued, document.issue_failed, document.rejected, document.delivered, document.paid, document.unpaid, document.cancelled y cambios de seguimiento.

Facturas programadas

scheduled_document.created, run_started, run_succeeded y run_failed, para saber cuándo se emitió cada recurrencia.

Cobros

payment_request.paid cuando el cliente paga, payment_request.document_issued y payment_request.expired.

Credenciales y conexiones

credential.invalid y credential.validated, más connection.active y connection.requires_action.

Folios

folio_request.completed y folio_request.failed, para enterarte si una solicitud de folios al SII no salió.

Lotes

batch.intake_failed si un lote no pudo procesarse al recibirlo.

Una integración para todas tus empresas

Si construyes un software que factura por sus clientes, un ERP con muchas empresas o un servicio de contabilidad, no quieres una integración por empresa. Con Tupana conectas cada empresa con su credencial del SII y emites para cualquiera de ellas con la misma llave. Cada empresa mantiene aislados sus documentos, sus folios y su credencial.

Para que tus usuarios conecten su empresa sin salir de tu producto, Tupana Connect ofrece un flujo de conexión que puedes integrar en tu aplicación. Los detalles están en developers.tupana.ai.

Prueba todo antes de emitir de verdad

Las llaves nuevas parten en el ambiente de pruebas. Ahí puedes emitir documentos, recibir webhooks y probar errores sin que nada llegue al SII: los folios salen numerados como SANDBOX-1, SANDBOX-2 y así sucesivamente. Cuando todo funciona, pasas a producción con el mismo código.

El ambiente de pruebas incluye empresas y facturas de prueba, webhooks de prueba, el buscador de empresas por RUT y el servidor MCP, para que tu asistente de IA te ayude a construir la integración.

Integraciones típicas, paso a paso

  1. Boleta al confirmar un pago en tu tienda: Cuando tu e-commerce confirma el pago, envías un lote con una boleta 39 y los datos del cliente. Al llegar document.issued, adjuntas el PDF al correo de confirmación.
  2. Facturación mensual de un SaaS: El día de cobro generas un lote con la factura 33 de cada cliente activo, hasta 500 por llamada. Si un documento falla, document.issue_failed te dice cuál y por qué, y reintentas solo ese.
  3. ERP para muchas empresas: Cada cliente de tu ERP conecta su empresa una vez. Desde ahí emites con la misma API key indicando el emisor, y escuchas credential.invalid para pedirle que actualice su clave cuando cambie.
  4. Nota de crédito por devolución: Cuando se aprueba una devolución en tu sistema, emites una nota de crédito 61 referenciando la factura original, y el estado te llega por webhook.

Precios de la API, por empresa conectada

Si construyes software que factura para otras empresas, pagas por empresa que conectas. Los valores son netos y se les agrega IVA; el pago es con tarjeta. Ejemplo: 10 empresas facturando = 5 UF al mes. Tabla completa, ejemplos y preguntas en precios de la API. Los planes de la plataforma web son otro producto: desde Starter incluyen acceso a la API solo para las empresas de tu propia cuenta.

0,5 UF al mes por empresa · Facturación

100 documentos (facturas, guías de despacho, facturas de exportación, notas de crédito y de débito, y boletas de honorarios de terceros) y 1.000 boletas de venta al mes por cada empresa (adicional: 0,004 UF por documento y 0,0004 UF por boleta de venta). Facturas, boletas, notas de crédito y boletas de honorarios, sin restricción de monto, productos ni referencias. Solo por API, sin la plataforma web. Si necesitas más, se arma un plan a la medida.

0,35 UF al mes por banco · Lectura bancaria

Cuentas, saldos y movimientos sincronizados sin límite, con el estado de la conexión.

0,2 UF al mes por empresa · Lectura SII

Registro de compra y venta y boletas de honorarios recibidas y de terceros emitidas por la empresa, más acuse de recibo, aceptación o reclamo de las facturas recibidas. Requiere la clave del SII de la empresa.

2% de lo recaudado · Recaudación

Opcional y sin costo fijo: link de pago en un paso, integrado a Transbank, con webhook cuando llega el dinero.

Documentación y ejemplos

Preguntas frecuentes

¿Qué es una API SII?

Es una API que conecta tu sistema con el Servicio de Impuestos Internos para emitir y consultar documentos tributarios sin pasar por el portal. El SII no entrega una API REST para emitir: recibe los documentos firmados con certificado digital por sus propios servicios de envío. La API de Tupana hace ese trabajo por ti (folios, firma, envío y estado) y te lo expone como REST con JSON.

¿Qué diferencia hay entre una API de factura electrónica y el portal del SII?

En el portal emites a mano, documento por documento. Con la API tu sistema emite solo: al confirmar una venta, al cerrar el mes o cuando ocurre un cobro, y recibe el estado de cada documento por webhook.

¿Cuántos documentos puedo enviar en una llamada?

Hasta 500 documentos por lote en POST /v2/documents/batch/. El lote se procesa en segundo plano y recibes el resultado de cada documento por webhook.

¿Cómo me entero de si el SII aceptó o rechazó un documento?

Por webhook: document.issued cuando queda emitido, document.issue_failed o document.rejected si algo falla. Cada aviso va firmado con HMAC-SHA256 en el encabezado X-Pana-Signature.

¿Hay ambiente de pruebas?

Sí. Las llaves nuevas parten en el ambiente de pruebas: los documentos se numeran SANDBOX-1, SANDBOX-2, etc. y nunca llegan al SII. Pasas a producción con el mismo código.

¿Puedo emitir para muchas empresas con una sola integración?

Sí. Conectas cada empresa con su credencial del SII y emites para cualquiera de ellas con la misma API key. Cada empresa mantiene aislados sus documentos, folios y credencial.

¿Tengo que usar el facturador de mercado de Tupana?

No. Cada empresa puede emitir con el facturador de mercado de Tupana o con el facturador gratuito del SII, al mismo precio. Tu integración no cambia; solo considera los límites del gratuito: hasta 3 referencias, 10 líneas por documento, alrededor de $100 millones por factura y de 600 a 700 facturas al mes.

¿Cuánto cuesta la API?

Para quienes construyen software que factura por otras empresas, Facturación cuesta 0,5 UF + IVA al mes por empresa conectada, con 100 documentos (facturas, guías de despacho, facturas de exportación, notas de crédito y de débito, y boletas de honorarios de terceros) y 1.000 boletas de venta al mes por empresa (adicional: 0,004 UF por documento y 0,0004 UF por boleta de venta); lectura SII 0,2 UF, bancos 0,35 UF por banco y recaudación 2% + IVA, sin mínimo. El detalle está en developers.tupana.ai/pricing. Los planes de la plataforma web son otro producto: desde Starter incluyen API solo para las empresas de tu propia cuenta.

¿Dónde está la documentación?

En docs.tupana.ai, con la especificación OpenAPI v2 publicada. La consola, las llaves y los precios están en developers.tupana.ai, y hay ejemplos y recursos en github.com/tupana-ai.

Sigue leyendo