Emitir facturas electrónicas en lote por API

Esta guía arma una emisión masiva de punta a punta: preparar el lote, enviarlo sin riesgo de duplicados, leer la respuesta y recibir el resultado final de cada documento. La referencia completa del endpoint está en Emisión masiva de documentos.

Antes de empezar

Una API key (empieza con una de sandbox: simula la emisión y no envía nada al SII). Ver Tu primera llamada.
La empresa emisora conectada con Tupana Link. En producción, sin una conexión activa la API responde 400 (credenciales no activas).
Un webhook para la empresa, para recibir el estado final y los archivos.

1. Arma el lote

Un lote es un objeto con un arreglo documents. Cada documento lleva al menos el tipo (dte_type.code), el emisor, el receptor y el detalle. Puedes mezclar tipos de documento en un mismo lote.

{
  "documents": [
    {
      "dte_type": { "code": "33" },
      "document_issuer": { "rut": "76123456-7" },
      "document_receiver": { "rut": "77987654-3", "business_name": "Cliente Uno SpA" },
      "details": [{ "item_name": "Plan mensual", "quantity": 1, "unit_price": 50000 }],
      "json_param": { "external_order_id": "PED-1001" }
    },
    {
      "dte_type": { "code": "33" },
      "document_issuer": { "rut": "76123456-7" },
      "document_receiver": { "rut": "76555444-3", "business_name": "Cliente Dos Ltda" },
      "details": [{ "item_name": "Plan mensual", "quantity": 1, "unit_price": 50000 }],
      "json_param": { "external_order_id": "PED-1002" }
    }
  ]
}

Hasta 200 documentos por llamada. Si tienes más, divide en varios lotes.
json_param guarda tus propios datos (tu id de pedido, por ejemplo). Vuelve en la respuesta y en los webhooks, y puedes filtrar por él en GET /v2/documents/ con json_param__external_order_id=PED-1001.
Los tipos soportados (33, 34, 39, 41, 46, 52, 56, 61, 80, 90, 110, 111, 112) y sus campos están en Tipos de documentos.

2. Envía el lote sin duplicados

curl -X POST https://api.tupana.ai/v2/documents/batch/ \
  -H "Authorization: Api-Key $TUPANA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Use-Defaults: true" \
  -H "Idempotency-Key: facturacion-2026-10-cierre-lote-01" \
  -d @lote.json

Header	Para qué
`Idempotency-Key`	Si la llamada se corta y la repites con la misma clave, recibes el lote original sin volver a emitir al SII. Máximo 256 caracteres; dura 24 horas. Usa una clave por lote, derivada de tus datos (no aleatoria en cada reintento).
`X-Use-Defaults: true`	Completa fecha, actividad económica, dirección y forma de pago con la configuración de cada empresa. Recomendado siempre.

3. Lee la respuesta

La API acepta el lote y lo procesa en segundo plano. La respuesta trae un batch_id, el estado de cada documento y, si mandaste campos que no existen, un arreglo warnings:

{
  "batch_id": "doba_4829301923847561203",
  "status": "processing",
  "warnings": [
    {
      "document_index": 0,
      "field": "header.transfer_indicator",
      "code": "unknown_field",
      "message": "Campo desconocido: se ignoró.",
      "suggestion": "transport_data.transport_type"
    }
  ]
}

Código	Qué significa	Qué hacer
`202` / `201`	Lote aceptado	Espera el webhook o consulta los documentos
`400`	La empresa emisora no tiene una conexión activa	Conéctala con Tupana Link
`413`	Más de 200 documentos	Divide el lote
`422`	Error de validación, con la posición del documento y la ruta del campo	Corrige y reenvía con una nueva `Idempotency-Key`

Con validación estricta (activa en las API keys nuevas), un campo desconocido responde 422 en vez de warnings. El catálogo completo está en Errores.

4. Recibe el resultado de cada documento

Cada documento emitido dispara document.issued con el folio, los montos y el PDF; si el SII lo rechaza, llega document.rejected, y si la emisión falla, document.issue_failed. Configúralo en Recibir avisos de estado. Si prefieres consultar, lista los documentos de la empresa:

curl "https://api.tupana.ai/v2/documents/?master_entity_id=ment_4829301923847&json_param__external_order_id=PED-1001" \
  -H "Authorization: Api-Key $TUPANA_API_KEY"

Facturador de mercado o facturador gratuito del SII

Tupana emite de dos maneras, y lo decide la configuración de cada empresa, no tu código:

Facturador de mercado de Tupana: emite directo al SII con los folios (CAF) y el certificado de la empresa. Sin los límites del portal del SII.
Facturador gratuito del SII: Tupana emite en el portal del SII con la clave de la empresa. Tiene límites propios del SII (referencias, líneas por documento, monto y volumen) y algunos campos no están disponibles.

La comparación completa está en Cómo elegir una API de facturación electrónica.

Relacionado

Referencia: emisión masiva
Documentos programados para facturación recurrente
Facturar para varias empresas

Primeros Pasos

Guías por tarea

Agentes de IA

SDKs

Elegir y comparar

Referencia

Novedades

Emitir facturas electrónicas en lote por API

Antes de empezar

1. Arma el lote

2. Envía el lote sin duplicados

3. Lee la respuesta

4. Recibe el resultado de cada documento

Facturador de mercado o facturador gratuito del SII

Relacionado

​Antes de empezar

​1. Arma el lote

​2. Envía el lote sin duplicados

​3. Lee la respuesta

​4. Recibe el resultado de cada documento

​Facturador de mercado o facturador gratuito del SII

​Relacionado

Antes de empezar

1. Arma el lote

2. Envía el lote sin duplicados

3. Lee la respuesta

4. Recibe el resultado de cada documento

Facturador de mercado o facturador gratuito del SII

Relacionado