Skip to main content
POST
/
documents
/
batch
Envío de documentos en lote
curl --request POST \
  --url https://api.tupana.ai/v1/documents/batch \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {
      "dte_type": {
        "code": "33"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "details": [
        {
          "item_name": "Servicio de Consultoría",
          "quantity": 1,
          "unit_price": 100000
        }
      ]
    }
  ]
}
'
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "documents": [
    {
      "index": 0,
      "status": "created",
      "document": {
        "id": 12345,
        "folio": "1",
        "date_issued": "2024-01-15",
        "amount_with_iva": 119000,
        "receiver_id": 456,
        "is_draft": false,
        "can_be_issued": true,
        "dte_type": {
          "code": "33",
          "description": "Factura Electrónica"
        },
        "sender": {
          "id": 123,
          "name": "Mi Empresa SpA",
          "tax_id": "12345678-9"
        },
        "receiver": {
          "id": 456,
          "name": "Cliente Importante Ltda",
          "tax_id": "98765432-1"
        },
        "items": [
          {
            "item_name": "Servicio de Consultoría",
            "item_description": null,
            "quantity": 1,
            "unit_price": 100000,
            "unit": "UN",
            "item_code": null,
            "item_type_code": null,
            "discount_percent": null,
            "other_tax": null
          }
        ],
        "document_total": {
          "net_amount": 100000,
          "iva_rate": 19,
          "iva_amount": 19000,
          "total_amount": 119000
        },
        "pdf_url": "https://s3.amazonaws.com/bucket/documento_12345.pdf?signature=...",
        "pdf_download_url": "/api/master-entities/123/documents/12345/file/"
      }
    }
  ]
}
Crea hasta 200 documentos tributarios electrónicos en una sola llamada. La respuesta con el PDF y los detalles completos se entrega a través del webhook configurado.

​
Headers

​
Idempotency-Key (Opcional)

  • Tipo: String
  • Descripción: Header opcional que previene la creación de lotes duplicados
  • Restricciones: Máximo 256 caracteres, expira después de 24 horas
  • Ejemplo: "batch_2024_01_15_001"

​
X-Use-Defaults (Opcional)

⚠️ IMPORTANTE: Se recomienda encarecidamente usar el header X-Use-Defaults: true en todas tus solicitudes de emisión masiva de documentos. Este header simplifica significativamente la creación de documentos al hacer opcionales muchos campos y completar automáticamente los datos faltantes según tu configuración en Tu Pana.
  • Tipo: String
  • Valores permitidos: "true", "false"
  • Por defecto: "false"
  • Descripción: Si se establece como "true", el sistema usará valores por defecto para campos no proporcionados, reduciendo la complejidad y cantidad de datos que necesitas enviar

​
Campos que se vuelven opcionales o se completan automáticamente

A nivel del documento:
  • date_issued: Si no se proporciona, se usa la fecha actual (en zona horaria de Chile)
  • folio: Si no se proporciona, se genera automáticamente por el sistema
  • dte_type.code: Si no se proporciona, se usa "33" (Factura Electrónica) por defecto
  • header.payment_method: Si no se proporciona, se establece como "2" (crédito)
En document_issuer (solo con RUT): Con X-Use-Defaults: true, solo necesitas proporcionar el rut del emisor. El sistema completa automáticamente todos los demás campos desde tu configuración:
  • business_name: Razón social del emisor
  • business_activity: Giro o actividad económica
  • address: Dirección del emisor
  • district: Comuna
  • city: Ciudad
  • email: Email de contacto
  • phone_number: Teléfono
  • activity_code: Código de actividad económica
En document_receiver (solo con RUT): Con X-Use-Defaults: true, solo necesitas proporcionar el rut del receptor. El sistema completa automáticamente todos los demás campos desde la configuración del cliente o datos disponibles:
  • business_name: Razón social del receptor ✅ Opcional
  • contact: Contacto del receptor ✅ Opcional
  • business_activity: Giro o actividad económica ✅ Opcional (no se valida si está vacío)
  • address: Dirección del receptor ✅ Opcional (no se valida si está vacío)
  • district: Comuna ✅ Opcional (no se valida si está vacío)
  • city: Ciudad ✅ Opcional (no se valida si está vacío)

​
Request Body

​
documents (Obligatorio)

  • Tipo: Array
  • Descripción: Lista de documentos a crear en el lote
  • Restricciones: Máximo 200 documentos por lote

​
Estructura de cada documento

​
Campos base (aplican a todos los tipos de documentos)

dte_type (Obligatorio)
  • Tipo: Object
  • Campos:
    • code (String): Código del tipo de documento
date_issued (Condicional)
  • Tipo: String (formato YYYY-MM-DD)
  • Descripción: Fecha de emisión del documento
  • Obligatorio: Sí, excepto si se usa X-Use-Defaults: true (usa fecha actual)
folio (Opcional)
  • Tipo: Integer
  • Descripción: Número de folio del documento
  • Comportamiento: Si no se proporciona, se genera automáticamente

​
Tipos de Documentos Soportados

​
Respuesta

​
Respuesta Inmediata de la API

​
201 - Documentos creados exitosamente

  • Tipo: Object
  • Campos:
    • batch_id (String): Identificador único del lote
    • status (String): Estado del procesamiento ("processing")
    • total_documents (Integer): Número total de documentos en el lote
    • message (String): Mensaje descriptivo del estado

​
413 - Límite excedido

  • Descripción: Más de 200 documentos en el array
  • Campos:
    • error (String): Descripción del error
    • code (String): Código de error

​
400 - Credenciales no activas

  • Descripción: La empresa emisora no tiene credenciales SII activas configuradas
  • Campos:
    • error (String): Mensaje descriptivo indicando que no hay credenciales activas para el RUT especificado

​
422 - Error de validación

  • Descripción: Cuerpo malformado o fallo de validación
  • Campos:
    • error (String): Descripción del error
    • details (Array): Detalles específicos de los errores de validación

​
Respuesta del Webhook

Cuando un documento se emite exitosamente, Tu Pana envía un webhook con la siguiente estructura: event (Obligatorio)
  • Tipo: String
  • Valor: "document.issued"
  • Descripción: Tipo de evento del webhook
created_at (Obligatorio)
  • Tipo: String (ISO 8601)
  • Descripción: Timestamp de cuando se generó el webhook
data (Obligatorio)
  • Tipo: Object
  • Descripción: Datos completos del documento emitido

​
Campos del objeto data

Información básica del documento:
  • id (Integer): ID único del documento en Tu Pana
  • folio (String): Folio asignado por el SII
  • date_issued (String): Fecha de emisión (formato YYYY-MM-DD)
  • amount_with_iva (Number): Monto total con IVA incluido
  • is_sandbox (Boolean): Indica si es un documento de prueba
dte_type (Object):
  • code (String): Código del tipo de documento
  • description (String): Descripción del tipo de documento
sender (Object):
  • id (Integer): ID del emisor en Tu Pana
  • name (String): Nombre/razón social del emisor
  • tax_id (String): RUT del emisor (formato con puntos y guión)
  • email (String): Email del emisor
receiver (Object):
  • id (Integer): ID del receptor en Tu Pana
  • name (String): Nombre/razón social del receptor
  • tax_id (String): RUT del receptor (formato con puntos y guión)
  • email (String): Email del receptor
header (Object):
  • purchase_transaction_type (Integer): Tipo de transacción de compra
  • sale_transaction_type (Integer): Tipo de transacción de venta
  • payment_method (String): Método de pago
  • due_date (String): Fecha de vencimiento (formato YYYY-MM-DD)
  • retention_type (String): Tipo de retención (solo para boletas de honorarios)
document_issuer (Object):
  • rut (String): RUT del emisor
  • business_name (String): Razón social
  • business_activity (String): Giro o actividad económica
  • phone_number (String): Teléfono
  • email (String): Email
  • activity_code (Integer): Código de actividad económica
  • sii_branch_code (String): Código de sucursal SII
  • address (String): Dirección
  • district (String): Comuna
  • city (String): Ciudad
document_receiver (Object):
  • rut (String): RUT del receptor
  • business_name (String): Razón social
  • business_activity (String): Giro o actividad económica
  • contact (String): Contacto
  • address (String): Dirección
  • district (String): Comuna
  • city (String): Ciudad
document_total (Object):
  • net_amount (Number): Monto neto (sin IVA)
  • iva_rate (Number): Tasa de IVA aplicada
  • iva_amount (Number): Monto del IVA
  • total_amount (Number): Monto total
details (Array): Lista de productos/servicios del documento. Cada elemento contiene:
  • item_name (String): Nombre del producto/servicio
  • item_description (String): Descripción del producto/servicio
  • quantity (Number): Cantidad
  • unit_price (Number): Precio unitario sin IVA
  • item_code (String): Código del producto/servicio
  • item_type_code (String): Código del tipo de ítem
  • unit (String): Unidad de medida
  • discount_percent (Number): Porcentaje de descuento
  • other_tax (Number): Otros impuestos
references (Array): Referencias a otros documentos (solo para notas de crédito). Cada elemento contiene:
  • dte_type_code (String): Código del tipo de DTE de referencia
  • reference_folio (String): Folio del documento referenciado
  • reference_date (String): Fecha del documento referenciado
  • reference_reason (String): Razón de la referencia
Archivos generados:
  • pdf_file (String): URL temporal para descargar el PDF del documento
  • xml_file (String): URL temporal para descargar el XML del documento
json_param (Object):
  • Descripción: Campos personalizados adicionales que se pueden incluir en el documento
  • Estructura: Objeto flexible que puede contener cualquier información adicional

​
Consideraciones Especiales por Tipo de Documento

​
Ejemplos de Uso por Tipo de Documento

​
Factura Electrónica (DTE 33)

{
  "documents": [
    {
      "dte_type": {
        "code": "33"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "details": [
        {
          "item_name": "Servicio de Consultoría",
          "quantity": 1,
          "unit_price": 100000
        }
      ]
    }
  ]
}

​
Factura de Compra (DTE 46)

{
  "documents": [
    {
      "dte_type": {
        "code": "46"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "98765432-1",
        "business_name": "Proveedor SpA"
      },
      "document_receiver": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "header": {
        "purchase_transaction_type": 1,
        "payment_method": "2"
      },
      "details": [
        {
          "item_name": "Equipo de Oficina",
          "quantity": 2,
          "unit_price": 50000
        }
      ]
    }
  ]
}

​
Factura de Exportación (DTE 110)

{
  "documents": [
    {
      "dte_type": {
        "code": "110"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Exportadora SpA"
      },
      "document_receiver": {
        "rut": "99999999-9",
        "business_name": "Importador Internacional Inc",
        "address": "123 Main Street",
        "city": "New York",
        "country": "USA"
      },
      "header": {
        "sale_transaction_type": 1,
        "currency": "USD"
      },
      "export_data": {
        "transport_mode": "2",
        "destination_country": "US",
        "destination_port": "JFK",
        "origin_port": "SCL",
        "export_clause": "1"
      },
      "details": [
        {
          "item_name": "Producto Exportado",
          "quantity": 100,
          "unit_price": 50
        }
      ]
    }
  ]
}

​
Nota de Crédito (DTE 61)

{
  "documents": [
    {
      "dte_type": {
        "code": "61"
      },
      "date_issued": "2024-01-16",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "references": [
        {
          "dte_type_code": "33",
          "reference_folio": 12345,
          "reference_date": "2024-01-15",
          "reference_reason": "Corrección de precio"
        }
      ],
      "details": [
        {
          "item_name": "Ajuste por Corrección",
          "quantity": -1,
          "unit_price": 5000
        }
      ]
    }
  ]
}

​
Boleta de Honorarios por usuario autorizado (DTE 80)

El emisor de la boleta es document_issuer.rut, pero la emite un usuario autorizado por el SII (dueño de una credencial sii_company). header.authorized_user_rut indica cuál credencial usar cuando hay varias accesibles. 
{
  "documents": [
    {
      "dte_type": {
        "code": "80"
      },
      "document_issuer": {
        "rut": "76543210-3"
      },
      "document_receiver": {
        "rut": "12345678-9"
      },
      "header": {
        "retention_type": "RETRECEPTOR",
        "authorized_user_rut": "19615893-6"
      },
      "details": [
        {
          "item_name": "Asesoría profesional",
          "quantity": 1,
          "unit_price": 50000
        }
      ]
    }
  ]
}

​
Boleta de Honorarios de Terceros (DTE 90)

Ejemplo mínimo con header X-Use-Defaults: true: con solo RUT en emisor y receptor el backend completa business_name y el resto si existen en Tu Pana; usa fecha actual si se omite date_issued. 
{
  "documents": [
    {
      "dte_type": {
        "code": "90"
      },
      "document_issuer": {
        "rut": "76543210-3"
      },
      "document_receiver": {
        "rut": "12345678-9"
      },
      "header": {
        "retention_type": "RETRECEPTOR"
      },
      "details": [
        {
          "item_name": "Servicio de reparto de pedidos",
          "quantity": 1,
          "unit_price": 15000
        }
      ]
    }
  ]
}

​
🧾 Factura de Compra (DTE 46)

​
Campos específicos del header:

  • purchase_transaction_type (Integer, Obligatorio):
    • 1: Compras del giro - Productos/servicios relacionados con tu actividad principal
    • 2: Compras fuera del giro - Productos/servicios no relacionados con tu actividad principal
    • 3: Activo fijo - Bienes que se incorporan al patrimonio de la empresa (maquinaria, muebles, etc.)
  • payment_method (String, Opcional):
    • "1": Contado - Pago inmediato
    • "2": Crédito - Pago diferido
    • "3": Sin costo - Producto/servicio recibido gratuitamente

​
Validaciones importantes:

  • Registro contable: Este documento genera asiento automático en tu contabilidad
  • IVA recuperable: El IVA pagado puede ser recuperado según el tipo de compra
  • Proveedor extranjero: Si el proveedor es extranjero, usar RUT genérico 55555555-5
  • Fecha límite: Las compras deben registrarse dentro del mes siguiente a la recepción

​
Casos de uso comunes:

  • Registro de compras a proveedores locales
  • Incorporación de activos fijos
  • Servicios profesionales recibidos
  • Compras de materias primas o insumos

​
✈️ Factura de Exportación (DTE 110)

​
Campos requeridos en export_data:

  • transport_mode (String, Obligatorio):
    • "1": Marítimo - Envío por barco
    • "2": Aéreo - Envío por avión
    • "3": Terrestre - Envío por tierra (camión, tren)
    • "4": Multimodal - Combinación de modos de transporte
  • destination_country (String, Obligatorio):
    • Código ISO del país de destino (ej: "US", "BR", "AR")
    • Debe coincidir con el país del receptor
  • destination_port (String, Obligatorio):
    • Nombre del puerto/aeropuerto/ciudad de destino
    • Ejemplos: "JFK", "Santos", "Buenos Aires"
  • origin_port (String, Obligatorio):
    • Nombre del puerto/aeropuerto/ciudad de origen en Chile
    • Ejemplos: "SCL", "IQQ", "ANF"
  • export_clause (String, Obligatorio):
    • "1": A firme - Compromiso incondicional de exportar
    • "2": Bajo protesta - Exportación sujeta a condiciones
    • "3": Sin cláusula - Exportación sin especificar condiciones

​
Campos específicos del header:

  • sale_transaction_type (Integer, Obligatorio):
    • 1: Operación constituye venta - Venta normal
    • 2: Ventas por acto o contrato - Contratos especiales
    • 3: Boleto de pasaje - Para agencias de viajes
  • currency (String, Obligatorio):
    • "USD": Dólares americanos
    • "EUR": Euros
    • "CLP": Pesos chilenos
    • "UF": Unidades de Fomento

​
Información del receptor extranjero:

  • RUT: Puede usar identificadores especiales como 99999999-9 para extranjeros
  • Dirección: Dirección completa en el extranjero
  • País: País de destino (debe coincidir con destination_country)

​
Precios y cálculos:

  • FOB (Free on Board): Los precios deben incluir costos hasta la entrega al transportista
  • Moneda: Debe coincidir con header.currency
  • Sin IVA: Las exportaciones están exentas de IVA chileno

​
Requisitos legales:

  • Registro de exportación: Debe estar registrado en el sistema aduanero
  • Certificado de origen: Puede requerirse según acuerdos comerciales
  • Documentos aduaneros: Factura comercial, certificado de origen, etc.

​
💼 Boletas de Honorarios (DTE 80, 90)

​
Campos específicos del header:

  • retention_type (String, Obligatorio):
    • "RETRECEPTOR": La retención la realiza el receptor (99% de los casos)
    • "RETCONTRIBUYENTE": La retención la realiza el contribuyente emisor (casos excepcionales)
  • authorized_user_rut (String, Opcional): RUT del usuario autorizado por el SII (dueño de la credencial sii_company) que emite en representación del emisor. Selecciona determinísticamente la credencial cuando hay varias accesibles. Solo válido para DTE 80 y 90.

​
Retención automática del 14.5%:

  • Cálculo: Se aplica sobre el monto bruto antes de IVA
  • Responsable: Normalmente el pagador retiene y declara el impuesto
  • Pago al profesional: Se paga el 85.5% restante (bruto menos retención)

​
Información del receptor (profesional):

  • Campos opcionales: A diferencia de facturas, no todos los datos son obligatorios
  • RUT obligatorio: Siempre se requiere el RUT del profesional
  • Actividad económica: Debe corresponder a servicios profesionales

​
Diferencias entre DTE 80 y 90:

DTE 80 - Boleta de Honorarios:
  • Emisión directa por el pagador al profesional
  • Relación directa pagador-profesional
  • document_issuer: Quien paga (empresa o persona que contrata)
DTE 90 - Boleta de Honorarios de Terceros:
  • Emisión por intermediario (plataformas, marketplaces)
  • document_issuer: Contribuyente real (quien paga — restaurante, empresa cliente)
  • document_receiver: Profesional que recibe (repartidor, freelancer, instructor)
  • Requiere enrolamiento de usuarios autorizados para emisión por terceros
  • Misma estructura de request que DTE 80; solo cambia dte_type.code: "90"

​
Validaciones específicas:

  • Tope mensual: Límite de emisión sin retención ampliada
  • Tipo de servicio: Debe corresponder a honorarios profesionales
  • Declaración: El retenedor debe declarar y pagar el impuesto retenido

​
Casos de uso:

  • DTE 80: Honorarios de abogados, contadores, médicos; servicios de consultoría; pagos directos a freelancers
  • DTE 90: Apps de delivery (Rappi, Uber Eats); plataformas freelance; marketplaces de servicios; plataformas educativas

​
🔒 Seguridad y URLs temporales

​
URLs de archivos temporales:

  • PDF y XML: URLs válidas por 1 hora aproximadamente
  • Autenticación: Incluyen tokens de acceso automático
  • Recomendación: Descargar inmediatamente al recibir el webhook

​
Medidas de seguridad:

  • Encriptación: Archivos transmitidos de forma segura
  • Validación: Solo el emisor puede acceder a sus documentos
  • Auditoría: Todas las descargas quedan registradas

Authorizations

​
Authorization
string
header
required

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)

Headers

​
Idempotency-Key
string

Previene lotes duplicados (≤ 256 caracteres, expira después de 24 h)

​
X-Use-Defaults
boolean
default:false

Si se establece como true, el sistema usará valores por defecto para campos no proporcionados:

  • Fecha actual para date_issued
  • Datos del emisor según configuración de la plataforma o primera actividad/dirección disponible
  • Datos del receptor según configuración del cliente o primera actividad/dirección disponible
  • Payment method = '2' (crédito) en el header del documento

Body

application/json

Lote de documentos a crear

​
documents
object[]
required

Array de documentos a crear (máximo 200)

Response

Solicitud de creación de documentos aceptada. Los resultados se enviarán por webhook.

​
batch_id
string<uuid>

Identificador único del lote

​
status
enum<string>

Estado del batch

Available options:
created,
processing,
completed,
failed
Example:

"processing"

​
created_at
string<date-time>

Fecha y hora de creación del batch

​
documents
object[]

Array de documentos procesados en el batch