Emisión masiva de documentos

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"
      },
      "document_issuer": {
        "rut": "<string>",
        "business_name": "<string>",
        "phone_number": "<string>",
        "email": "<string>",
        "business_activity": "<string>",
        "activity_code": 123,
        "sii_branch_code": "<string>",
        "address": "<string>",
        "district": "<string>",
        "city": "<string>"
      },
      "document_receiver": {
        "rut": "<string>",
        "business_name": "<string>",
        "contact": "<string>",
        "business_activity": "<string>",
        "address": "<string>",
        "district": "<string>",
        "city": "<string>"
      },
      "details": [
        {
          "item_name": "<string>",
          "quantity": 123,
          "unit_price": 123,
          "item_description": "<string>",
          "discount_percent": 123,
          "item_total": 123,
          "item_code": "<string>",
          "unit": "<string>",
          "other_tax": 123,
          "item_type_code": 123
        }
      ],
      "date_issued": "2023-12-25",
      "folio": "<string>",
      "header": {
        "purchase_transaction_type": 123,
        "sale_transaction_type": 123,
        "payment_method": "<string>",
        "due_date": "2023-12-25",
        "vat_withheld": false,
        "retention_type": "RETRECEPTOR"
      },
      "references": [
        {
          "reference_type": 123,
          "reference_folio": 123,
          "reference_date": "2023-12-25",
          "reference_reason": "ANULA DOCUMENTO DE LA REFERENCIA",
          "dte_type_code": "<string>"
        }
      ],
      "json_param": {},
      "export_data": {
        "tax_id_receptor": "<string>",
        "destination_country_code": "US",
        "currency_code": "USD",
        "exchange_rate": "800.50",
        "departure_port_code": "<string>",
        "arrival_port_code": "<string>",
        "departure_port_name": "<string>",
        "arrival_port_name": "<string>",
        "total_packages": "<string>",
        "sale_mode_code": "<string>",
        "export_type": "0"
      }
    }
  ]
}
'

{
  "batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "documents": [
    {
      "index": 123,
      "document_id": 123,
      "status": "created",
      "errors": {}
    }
  ]
}

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.

​

Parámetros de Entrada

​

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)

​

Cuerpo de la Solicitud (Request Body)

​

documents (Obligatorio)

• Tipo: Array
• Descripción: Lista de documentos a crear en el lote
• Restricciones: Máximo 200 documentos por lote
• Estructura: Cada elemento del array debe contener los siguientes campos según el tipo de documento

​

Estructura de cada documento

Cada documento en el array debe contener los siguientes campos base:

dte_type (Obligatorio)

• Tipo: Object
• Descripción: Tipo de documento tributario electrónico
• Campos:
  • code (String): Código del tipo de documento
    • "33": Factura Electrónica
    • "34": Factura Exenta
    • "61": Nota de Crédito
    • "80": Boleta de Honorarios
    • "90": Boleta de Honorarios de Terceros

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

​

Campos Específicos por Tipo de Documento

Nota: Si usas el header X-Use-Defaults: true, algunos campos como date_issued y datos del emisor/receptor pueden ser opcionales. El sistema usará valores por defecto según la configuración.

​

Facturas Electrónicas (DTE 33, 34)

​

document_issuer (Obligatorio)

• Tipo: Object
• Descripción: Datos del emisor del documento
• Campos obligatorios:
  • rut (String): RUT del emisor
  • business_name (String): Razón social - Opcional con X-Use-Defaults: true
  • business_activity (String): Giro o actividad económica - Opcional con X-Use-Defaults: true
  • address (String): Dirección - Opcional con X-Use-Defaults: true
  • district (String): Comuna - Opcional con X-Use-Defaults: true
  • city (String): Ciudad - Opcional con X-Use-Defaults: true
  • email (String): Email de contacto - Opcional con X-Use-Defaults: true
  • phone_number (String): Teléfono - Opcional con X-Use-Defaults: true
  • activity_code (Integer): Código de actividad económica - Opcional con X-Use-Defaults: true

​

document_receiver (Obligatorio)

• Tipo: Object
• Descripción: Datos del receptor del documento
• Campos obligatorios:
  • rut (String): RUT del receptor
  • business_name (String): Razón social - Opcional con X-Use-Defaults: true
  • business_activity (String): Giro o actividad económica - Opcional con X-Use-Defaults: true
  • address (String): Dirección - Opcional con X-Use-Defaults: true
  • district (String): Comuna - Opcional con X-Use-Defaults: true
  • city (String): Ciudad - Opcional con X-Use-Defaults: true

​

details (Obligatorio)

• Tipo: Array
• Descripción: Lista de productos/servicios del documento
• Campos de cada elemento:
  • item_name (String): Nombre del producto/servicio
  • quantity (Number): Cantidad (debe ser mayor a 0)
  • unit_price (Number): Precio unitario
  • item_total (Number): Total del ítem (debe ser igual a quantity × unit_price)

​

Notas de Crédito (DTE 61)

Incluye todos los campos de las Facturas Electrónicas más los siguientes campos adicionales:

​

references (Obligatorio)

• Tipo: Array
• Descripción: Referencias al documento que se anula o modifica
• Campos de cada elemento:
  • dte_type_code (String): Código del documento original (ej: “33”, “34”)
  • reference_folio (Integer): Folio del documento original
  • reference_date (String): Fecha del documento original (formato YYYY-MM-DD)
  • reference_reason (String): Razón de la referencia
    • Para anulación total: "ANULA DOCUMENTO DE LA REFERENCIA"
    • Para corrección: Descripción del motivo de corrección

​

Boletas de Honorarios (DTE 80)

Incluye todos los campos de las Facturas Electrónicas con las siguientes particularidades:

​

header (Obligatorio)

• Tipo: Object
• Descripción: Configuración específica del documento
• Campos obligatorios:
  • retention_type (String): Tipo de retención
    • "RETRECEPTOR": La retención la realiza el receptor (por defecto)
    • "RETCONTRIBUYENTE": La retención la realiza el contribuyente emisor

​

document_receiver (Opcional)

• Tipo: Object
• Descripción: Datos del receptor del documento
• Nota: Para boletas de honorarios, este campo es opcional. Si no se proporciona, se puede usar solo el RUT en el campo receiver_rut

​

Boletas de Honorarios de Terceros (DTE 90)

Incluye todos los campos de las Boletas de Honorarios (DTE 80) con las siguientes características:

​

Diferencia principal

• Uso: Se utiliza cuando una empresa emite boletas de honorarios en nombre de un tercero (ej: plataformas digitales)
• Estructura: Misma que DTE 80, incluyendo el campo header.retention_type obligatorio

​

header (Obligatorio)

• Tipo: Object
• Descripción: Configuración específica del documento
• Campos obligatorios:
  • retention_type (String): Tipo de retención
    • "RETRECEPTOR": La retención la realiza el receptor
    • "RETCONTRIBUYENTE": La retención la realiza el contribuyente emisor

​

Parámetros de Respuesta

​

Respuesta Inmediata de la API

La API devuelve una respuesta inmediata con el estado del lote:

​

201 - Documentos creados exitosamente

• Tipo: Object
• Descripción: Confirmación de que el lote fue procesado correctamente
• 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

​

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:

​

Campos principales del webhook

• Tipo: Object
• Descripción: Notificación de documento emitido exitosamente

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
• item_total (Number): Total del ítem
• 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:

• reference_type.code (String): Código del tipo 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

Para boletas de honorarios (DTE 80, 90)

• El campo header.retention_type indica el tipo de retención aplicada
• Los campos de totales en document_total reflejan el cálculo con retención del 14.5%
• Las URLs de archivos (pdf_file, xml_file) son temporales y expiran después de un tiempo determinado

Seguridad y URLs temporales

• Las URLs de descarga de PDF y XML son temporales y requieren los parámetros de autenticación incluidos
• Se recomienda descargar y almacenar los archivos inmediatamente después de recibir el webhook