> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tupana.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Emisión masiva de documentos
> Crea hasta 200 documentos en una sola llamada. La respuesta incluye información completa de cada documento creado, incluyendo PDF cuando está disponible. Los resultados también se enviarán por webhook si está configurado.
**Permisos requeridos:** La API Key debe tener el permiso `document:create` o permisos completos (`*`). Además, la entidad emisora debe tener credenciales SII válidas configuradas.
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](/user-guide/getting-started#paso-4%3A-configura-las-notificaciones-webhooks/).
## 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 Tupana.
* **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
📄 Factura Electrónica (DTE 33) - Documento tributario más común para ventas
**Campos específicos:**
**document\_issuer (Obligatorio)**
* **Tipo:** Object
* **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
* **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 sin IVA
* `gross_unit_price` (Number): **No aplica a este tipo de documento.** Solo válido para boletas electrónicas (DTE 39 y 41); en Factura Electrónica se debe enviar el neto en `unit_price`.
📄 Factura Exenta (DTE 34) - Para ventas exentas de IVA
**Campos específicos:**
Iguales a la Factura Electrónica (DTE 33), pero el documento no incluye IVA en los cálculos.
**Casos de uso:**
* Ventas a clientes exentos de IVA
* Exportaciones (aunque se recomienda usar DTE específico de exportación)
* Servicios específicos exentos por ley
**document\_issuer y document\_receiver:** Mismos campos que Factura Electrónica
**details:** Mismos campos que Factura Electrónica (solo `unit_price`; `gross_unit_price` no aplica a este tipo de documento)
🧾 Boleta Electrónica (DTE 39) - Venta a consumidor final, IVA incluido en el precio
**Campos específicos:**
**document\_issuer (Obligatorio)**
* **Tipo:** Object
* Mismos campos que Factura Electrónica
**document\_receiver (Opcional)**
* **Tipo:** Object
* **Descripción:** Al ser venta a consumidor final, los datos del receptor no son obligatorios. Con boletas (39/41) la dirección del receptor se blanquea automáticamente.
**details (Obligatorio)**
* **Tipo:** Array
* **Descripción:** Lista de productos/servicios del documento. Acepta **neto o bruto por línea**, pero no ambos en el mismo documento.
* **Campos de cada elemento:**
* `item_name` (String): Nombre del producto/servicio
* `quantity` (Number): Cantidad (puede ser negativa solo en boletas, ej. para aplicar descuentos, siempre que el total del documento sea positivo)
* `unit_price` (Number): Precio unitario **neto**, sin IVA
* `gross_unit_price` (Number): Precio unitario **bruto, con IVA incluido**. Alternativa a `unit_price` — **exclusiva de boletas (DTE 39 y 41)**.
* Si se usa en una línea, el `item_total` de esa línea queda en bruto y el neto/IVA del documento completo se derivan hacia atrás a partir del bruto.
* **No se puede mezclar** `unit_price` (neto) y `gross_unit_price` (bruto) entre líneas del mismo documento: todas las líneas deben usar el mismo modo.
* Si se usa `gross_unit_price` en cualquier tipo de documento que no sea 39 o 41, la API responde `422`.
**Ejemplo — boleta en bruto:**
```json theme={null}
{
"documents": [
{
"dte_type": { "code": "39" },
"document_issuer": { "rut": "12345678-9" },
"document_receiver": { "rut": "1-9" },
"details": [
{
"item_name": "Producto A",
"quantity": 1,
"gross_unit_price": 11900
}
]
}
]
}
```
🧾 Boleta Exenta Electrónica (DTE 41) - Venta a consumidor final exenta de IVA
**Campos específicos:**
Iguales a la Boleta Electrónica (DTE 39), pero el documento no incluye IVA en los cálculos.
**details:** Mismos campos que Boleta Electrónica, incluyendo `gross_unit_price` (bruto). Al no llevar IVA, en la práctica `unit_price` y `gross_unit_price` producen el mismo resultado, pero la restricción de no mezclar ambos modos en el mismo documento se mantiene.
🧾 Factura de Compra (DTE 46) - Para registro de compras realizadas
**Campos específicos:**
**document\_issuer (Obligatorio)**
* **Tipo:** Object
* **Descripción:** Datos del proveedor/vendedor
* **Campos obligatorios:**
* `rut` (String): RUT del proveedor
* `business_name` (String): Razón social del proveedor - Opcional con `X-Use-Defaults: true`
* `business_activity` (String): Giro del proveedor - Opcional con `X-Use-Defaults: true`
* `address` (String): Dirección del proveedor - Opcional con `X-Use-Defaults: true`
* `district` (String): Comuna del proveedor - Opcional con `X-Use-Defaults: true`
* `city` (String): Ciudad del proveedor - Opcional con `X-Use-Defaults: true`
**document\_receiver (Obligatorio)**
* **Tipo:** Object
* **Descripción:** Datos del comprador (tu empresa)
* **Campos obligatorios:**
* `rut` (String): RUT de tu empresa
* `business_name` (String): Razón social - Opcional con `X-Use-Defaults: true`
* `business_activity` (String): Giro - 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 comprados
* **Campos de cada elemento:**
* `item_name` (String): Nombre del producto/servicio comprado
* `quantity` (Number): Cantidad comprada
* `unit_price` (Number): Precio unitario sin IVA pagado
* `gross_unit_price` (Number): **No aplica a este tipo de documento.** Solo válido para boletas electrónicas (DTE 39 y 41).
**header (Obligatorio para ciertos casos)**
* **Tipo:** Object
* **Campos opcionales:**
* `purchase_transaction_type` (Integer): **Obligatorio para compras** - Clasifica el tipo de compra para efectos contables y tributarios
* `1`: **Compras del giro** - Productos/servicios directamente relacionados con tu actividad económica principal (ej: materias primas para fabricante)
* `2`: **Compras fuera del giro** - Productos/servicios no relacionados con tu giro (ej: útiles de oficina para una fábrica)
* `3`: **Activo fijo** - Bienes que se incorporan al patrimonio y se deprecian (ej: maquinaria, vehículos, muebles)
* `payment_method` (String): **Opcional** - Forma de pago acordada
* `"1"`: **Contado** - Pago inmediato al recibir la mercadería/servicio
* `"2"`: **Crédito** - Pago diferido (especificar plazo en `due_date`)
* `"3"`: **Sin costo** - Mercadería/servicio recibido gratuitamente (donación, regalo)
* `due_date` (String): **Condicional** - Fecha de vencimiento cuando `payment_method` es crédito
* Formato: `YYYY-MM-DD`
* Obligatorio cuando es compra a crédito
✈️ Factura de Exportación (DTE 110) - Para ventas al extranjero
**Campos específicos:**
**document\_issuer (Obligatorio)**
* **Tipo:** Object
* **Campos obligatorios:**
* `rut` (String): RUT del exportador
* `business_name` (String): Razón social - Opcional con `X-Use-Defaults: true`
* `business_activity` (String): Giro - 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 importador extranjero
* **Campos obligatorios:**
* `rut` (String): RUT extranjero (puede ser un identificador especial)
* `business_name` (String): Nombre del importador
* `business_activity` (String): Descripción de la actividad
* `address` (String): Dirección en el extranjero
* `city` (String): Ciudad del extranjero
* `country` (String): País de destino
**export\_data (Obligatorio)**
* **Tipo:** Object
* **Descripción:** Información detallada de la exportación requerida por aduanas y SII
* **Campos obligatorios:**
* `transport_mode` (String): **Modalidad de transporte utilizada**
* `"1"`: **Marítimo** - Envío por barco (contenedor, carga suelta)
* `"2"`: **Aéreo** - Envío por avión (carga aérea, courier)
* `"3"`: **Terrestre** - Envío por tierra (camión, ferrocarril, terrestre internacional)
* `"4"`: **Multimodal** - Combinación de dos o más modos de transporte
* `destination_country` (String): **País de destino final**
* **No es código ISO 3166-1.** Es el código de país del SII (tabla de Aduana), enviado como *string* (ej: `"225"` = U.S.A., `"220"` = Brasil, `"224"` = Argentina, `"216"` = México). Ver [Países de exportación](/user-guide/export-countries) para la tabla completa.
* Debe coincidir exactamente con el país del receptor extranjero
* Afecta tratados comerciales y aranceles
* `destination_port` (String): **Puerto/aeropuerto/ciudad de destino**
* Nombre oficial del punto de entrada (ej: `"JFK"`, `"Santos"`, `"Buenos Aires"`, `"Veracruz"`)
* Para transporte terrestre: ciudad fronteriza de destino
* Debe ser reconocible por autoridades aduaneras
* `origin_port` (String): **Puerto/aeropuerto/ciudad de origen en Chile**
* Punto chileno de salida (ej: `"SCL"`, `"IQQ"`, `"ANF"`, `"VAP"`)
* Para transporte terrestre: ciudad fronteriza chilena
* Determina jurisdicción aduanera chilena
* `sale_mode_code` (String): **Modalidad de venta** (código de Aduana del SII, no una cláusula Incoterm)
* **No es código FOB/CIF.** Ver [Modalidades de venta de exportación](/user-guide/export-sale-modes) para la tabla completa (`"1"` = A Firme, `"2"` = Bajo Condición, `"3"` = En Consignación Libre, `"4"` = En Consig. con Mínimo a Firme, `"9"` = Sin Pago).
* **Campos opcionales adicionales:**
* `transport_company` (String): Nombre de la empresa de transporte
* `tracking_number` (String): Número de seguimiento del envío
* `customs_declaration` (String): Número de declaración aduanera (si aplica)
**details (Obligatorio)**
* **Tipo:** Array
* **Descripción:** Lista de productos exportados
* **Campos de cada elemento:**
* `item_name` (String): Nombre del producto exportado
* `quantity` (Number): Cantidad exportada
* `unit_price` (Number): Precio unitario sin IVA FOB (Free on Board)
* `gross_unit_price` (Number): **No aplica a este tipo de documento.** Solo válido para boletas electrónicas (DTE 39 y 41).
**header (Obligatorio)**
* **Tipo:** Object
* **Campos obligatorios:**
* `sale_transaction_type` (Integer): Tipo de transacción de venta
* `1`: Operación constituye venta
* `2`: Ventas por acto o contrato
* `3`: Boleto de pasaje emitido por agencias
* `currency` (String): Moneda de la transacción
* `"USD"`: Dólares americanos
* `"EUR"`: Euros
* `"CLP"`: Pesos chilenos
📝 Nota de Crédito (DTE 61) - Para anular o corregir documentos emitidos
**Campos específicos:**
Incluye todos los campos de las Facturas Electrónicas más:
**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
**Casos de uso:**
* Anulación total de un documento
* Corrección de errores en documentos emitidos
* Descuentos o devoluciones
💼 Boleta de Honorarios (DTE 80) - Para pagos de servicios profesionales
**Campos específicos:**
Incluye todos los campos de las Facturas Electrónicas con:
**header (Obligatorio)**
* **Tipo:** Object
* **Campos obligatorios:**
* `retention_type` (String): **Tipo de retención del 14.5%**
* `"RETRECEPTOR"`: **Retención por el receptor** (99% de casos) - El pagador retiene y declara el impuesto
* `"RETCONTRIBUYENTE"`: **Retención por el emisor** (casos excepcionales) - El emisor retiene el impuesto
* `payment_method` (String): **Forma de pago** (opcional pero recomendado)
* `"1"`: Contado
* `"2"`: Crédito
* `due_date` (String): **Fecha de vencimiento** (opcional, formato YYYY-MM-DD)
* `authorized_user_rut` (String): **Opcional** - Emisión por **usuario autorizado**. RUT del usuario autorizado por el SII (dueño de la credencial `sii_company`) que emite la boleta en representación del emisor (`document_issuer.rut`). Úsalo cuando el RUT del emisor es distinto del usuario que tiene la sesión SII, para seleccionar **determinísticamente** qué credencial usar. Solo aplica a boletas de honorarios (DTE 80 y 90); en otros tipos de documento la API responde `422`.
**¿Cuándo usar `authorized_user_rut`?** El emisor de la boleta es siempre `document_issuer.rut`. Cuando una misma cuenta tiene acceso a **varias** credenciales `sii_company` (p. ej. un contador que emite para varios contribuyentes), enviar `header.authorized_user_rut` indica exactamente cuál usuario autorizado realiza la emisión. Sin este campo, la API elige una credencial `sii_company` accesible de forma no determinística. El campo no se persiste en el documento; queda registrado en los logs de la API.
**document\_receiver (Condicional)**
* **Tipo:** Object
* **Descripción:** Datos del profesional que recibe los honorarios
* **Obligatoriedad:** Condicional - se puede usar solo RUT, pero se recomienda información completa
* **Campos:**
* `rut` (String): **Obligatorio** - RUT del profesional
* `business_name` (String): **Opcional** - Nombre completo del profesional
* `business_activity` (String): **Opcional** - Profesión o especialidad (ej: "Abogado", "Contador", "Médico")
* `address` (String): **Opcional** - Dirección del profesional
* `district` (String): **Opcional** - Comuna del profesional
* `city` (String): **Opcional** - Ciudad del profesional
* `email` (String): **Opcional** - Email de contacto
**details (Obligatorio)**
* **Tipo:** Array
* **Campos de cada elemento:** Mismos campos que Factura Electrónica (`item_name`, `quantity`, `unit_price`)
* `gross_unit_price` (Number): **No aplica a este tipo de documento** (Boleta de Honorarios, DTE 80). Solo válido para boletas electrónicas de venta (DTE 39 y 41).
**Cálculo automático de retención:**
* **Tasa**: 14.5% sobre el monto bruto (antes de IVA)
* **Base imponible**: Suma de (quantity × unit\_price) por cada ítem en details
* **Retención**: `base_imponible × 0.145`
* **Pago neto**: `base_imponible - retención`
* **Responsable**: Normalmente el pagador declara y paga la retención al SII
**Características especiales:**
* Aplica retención del 14.5% sobre el monto bruto
* Se utiliza para pagos a profesionales independientes
* No requiere todos los datos del receptor obligatoriamente
🏢 Boleta de Honorarios de Terceros (DTE 90) - Para plataformas digitales
**Descripción:** Documento para que plataformas digitales emitan boletas de honorarios en nombre de terceros (contribuyentes reales). La estructura del request es **idéntica a DTE 80**; la diferencia está en el código `dte_type.code: "90"`.
**Código DTE:** `"90"` — Boleta de Honorarios a Terceros Electrónica (confirmado en normativa SII).
***
### Requisito previo: agregar el contribuyente real (SII Company)
**Antes de emitir DTE 90, debes registrar el contribuyente real en Tupana:**
1. El `document_issuer.rut` debe corresponder a una **MasterEntity** ya existente en Tupana.
2. Esa entidad debe tener **credenciales SII de tipo `sii_company`** configuradas y activas.
3. La API usa el RUT de `document_issuer` para buscar la entidad emisora; si no existe o no tiene credenciales, la emisión falla.
**¿Qué es sii\_company?** Es el tipo de credencial SII para empresas que emiten boletas de honorarios de terceros (a diferencia de credenciales personales). El contribuyente real (restaurante, empresa cliente) debe tener esta credencial en Tupana.
**Pasos para configurar:**
* Crear o importar la MasterEntity del contribuyente real (RUT, razón social, etc.).
* Configurar credenciales SII de tipo `sii_company` para esa entidad.
* Opcionalmente enrolar usuarios autorizados para emisión por terceros (ver [API de Honorarios](/api-reference/honorary/introduction)).
***
### X-Use-Defaults para DTE 90
**Sí se puede usar** `X-Use-Defaults: true`, pero con una limitación importante:
* **document\_issuer:** El sistema completa datos desde la MasterEntity que coincida con `document_issuer.rut`. Si el contribuyente real **no está registrado** en Tupana, X-Use-Defaults no podrá completar datos y deberás enviar todos los campos obligatorios.
* **document\_receiver:** Igual que DTE 80; si el RUT existe en Tupana, se completan datos.
* **date\_issued, header.payment\_method:** Se aplican los mismos defaults que para otros tipos.
**Recomendación:** Si emites DTE 90 de forma recurrente, registra los contribuyentes reales (restaurantes, clientes) como MasterEntity en Tupana para poder usar X-Use-Defaults con solo el RUT.
***
### Campos requeridos (mismos que DTE 80)
**dte\_type (Obligatorio)**
* `code` (String): `"90"` — Boleta de Honorarios a Terceros Electrónica
**document\_issuer (Obligatorio)** — Contribuyente real (el tercero en cuyo nombre emite la plataforma)
* **Tipo:** Object
* **Descripción:** Datos del contribuyente que paga los honorarios (restaurante, empresa cliente, etc.).
* **Campos obligatorios:**
* `rut` (String): RUT del contribuyente real — **debe existir como MasterEntity con credenciales sii\_company**
* `business_name` (String): Razón social del contribuyente real
* `activity_code` (Integer): Código de actividad económica (ej: 620900)
* **Con X-Use-Defaults:** Si el RUT existe en Tupana, los demás campos se completan automáticamente.
**document\_receiver (Obligatorio)** — Profesional que recibe los honorarios
* **Tipo:** Object
* **Campos obligatorios:** `rut` (String)
* **Opcionales:** `business_name`, `business_activity`, `address`, `district`, `city`, `contact`
**header (Obligatorio)**
* `retention_type` (String): `"RETRECEPTOR"` o `"RETCONTRIBUYENTE"`
* Opcionales: `payment_method`, `due_date`
**details (Obligatorio)**
* Array con `item_name`, `quantity`, `unit_price`
* `gross_unit_price`: **No aplica a este tipo de documento** (Boleta de Honorarios de Terceros, DTE 90). Solo válido para boletas electrónicas de venta (DTE 39 y 41).
**Responsabilidades:**
* **Contribuyente real** (document\_issuer): Debe estar en Tupana con credenciales sii\_company; es el responsable tributario.
* **Retención:** 14.5% sobre monto bruto, igual que DTE 80.
**Casos de uso:**
* Apps de delivery (Rappi, Uber Eats) — restaurante paga al repartidor
* Plataformas freelance — empresa paga al freelancer
* Marketplaces de servicios — cliente paga al proveedor
## 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, Tupana 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 Tupana
* `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 Tupana
* `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 Tupana
* `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 neto, sin IVA. Si el documento se emitió en bruto (boletas 39/41 con `gross_unit_price`), este campo refleja el monto bruto de la línea — `gross_unit_price` es solo de entrada y no se retorna en la respuesta.
* `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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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",
"sale_mode_code": "1"
},
"details": [
{
"item_name": "Producto Exportado",
"quantity": 100,
"unit_price": 50
}
]
}
]
}
```
#### Nota de Crédito (DTE 61)
```json theme={null}
{
"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.
```json theme={null}
{
"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 Tupana; usa fecha actual si se omite `date_issued`.
```json theme={null}
{
"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):
* **No es código ISO 3166-1.** Es el código de país del SII (ej: `"225"` = U.S.A., `"220"` = Brasil, `"224"` = Argentina). Ver [Países de exportación](/user-guide/export-countries) para la tabla completa.
* 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"`
* **`sale_mode_code`** (String, Obligatorio):
* Código de modalidad de venta del SII (no una cláusula Incoterm). Ver [Modalidades de venta de exportación](/user-guide/export-sale-modes) para la tabla completa.
### 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
## OpenAPI
````yaml POST /documents/batch
openapi: 3.0.0
info:
title: Tupana API
description: API para integración con el sistema Tupana - Facturación Electrónica
version: 1.0.0
servers:
- url: https://api.tupana.ai/v1
description: Servidor de producción
security:
- apiKeyAuth: []
paths:
/documents/batch:
post:
summary: Envío de documentos en lote
description: >-
Crea hasta 200 documentos en una sola llamada. La respuesta incluye
información completa de cada documento creado, incluyendo PDF cuando
está disponible. Los resultados también se enviarán por webhook si está
configurado.
**Permisos requeridos:** La API Key debe tener el permiso
`document:create` o permisos completos (`*`). Además, la entidad emisora
debe tener credenciales SII válidas configuradas.
operationId: createDocumentsBatch
parameters:
- name: Idempotency-Key
in: header
description: Previene lotes duplicados (≤ 256 caracteres, expira después de 24 h)
required: false
schema:
type: string
- name: X-Use-Defaults
in: header
description: >-
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
required: false
schema:
type: boolean
default: false
requestBody:
description: Lote de documentos a crear
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentBatch'
example:
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
required: true
responses:
'202':
description: >-
Solicitud de creación de documentos aceptada. Los resultados se
enviarán por webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
example:
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/
'403':
description: >-
Sin permisos para crear documentos. La API Key debe tener el permiso
'document:create' o permisos completos ('*'). Además, la entidad
emisora debe tener credenciales SII válidas configuradas.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Esta entidad no tiene credenciales SII válidas configuradas
'413':
description: Más de 200 documentos en el array
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Cuerpo malformado o fallo de validación
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- apiKeyAuth: []
components:
schemas:
DocumentBatch:
type: object
required:
- documents
properties:
documents:
type: array
description: Array de documentos a crear (máximo 200)
items:
$ref: '#/components/schemas/Document'
BatchResponse:
type: object
properties:
batch_id:
type: string
format: uuid
description: Identificador único del lote
status:
type: string
description: Estado del batch
enum:
- created
- processing
- completed
- failed
example: processing
created_at:
type: string
format: date-time
description: Fecha y hora de creación del batch
documents:
type: array
description: Array de documentos procesados en el batch
items:
type: object
properties:
index:
type: integer
description: Índice del documento en el array original
status:
type: string
enum:
- created
- processing
- success
- invalid
- temporary_error
- permanent_error
- incomplete
description: Estado de procesamiento del documento
document:
type: object
nullable: true
description: >-
Información completa del documento (solo presente si status
permite tener documento)
properties:
id:
type: integer
description: ID único del documento creado
folio:
type: string
nullable: true
description: Número de folio del documento
date_issued:
type: string
format: date
description: Fecha de emisión del documento
amount_with_iva:
type: number
format: float
description: Monto total con IVA
receiver_id:
type: integer
nullable: true
description: ID de la entidad receptora
is_draft:
type: boolean
description: Indica si el documento es un borrador
can_be_issued:
type: boolean
description: Indica si el documento puede ser emitido
dte_type:
type: object
properties:
code:
type: string
description: Código del tipo de DTE
description:
type: string
sender:
type: object
nullable: true
properties:
id:
type: integer
name:
type: string
tax_id:
type: string
receiver:
type: object
nullable: true
properties:
id:
type: integer
name:
type: string
tax_id:
type: string
items:
type: array
description: Array de productos/servicios del documento
items:
type: object
properties:
item_name:
type: string
item_description:
type: string
nullable: true
quantity:
type: number
nullable: true
unit_price:
type: number
nullable: true
unit:
type: string
nullable: true
item_code:
type: string
nullable: true
item_type_code:
type: integer
nullable: true
discount_percent:
type: number
nullable: true
other_tax:
type: number
nullable: true
document_total:
type: object
nullable: true
properties:
net_amount:
type: number
nullable: true
iva_rate:
type: number
nullable: true
iva_amount:
type: number
nullable: true
total_amount:
type: number
nullable: true
pdf_url:
type: string
format: uri
nullable: true
description: URL presignada al PDF del documento (válida por 2 horas)
pdf_download_url:
type: string
nullable: true
description: URL de descarga del PDF
retention_type:
type: string
nullable: true
description: Tipo de retención para boletas de honorarios (DTE 80, 90)
enum:
- RETRECEPTOR
- RETCONTRIBUYENTE
export_data:
type: object
nullable: true
description: >-
Datos de exportación para facturas internacionales (DTE
110, 111, 112)
errors:
type: object
nullable: true
description: Errores de validación si el estado es 'invalid' o hay errores
Error:
required:
- error
- message
type: object
properties:
error:
type: string
description: Código de error
example: VALIDATION_ERROR
enum:
- VALIDATION_ERROR
- AUTHENTICATION_ERROR
- AUTHORIZATION_ERROR
- NOT_FOUND
- SII_ERROR
- INTERNAL_ERROR
message:
type: string
description: Mensaje de error
Document:
type: object
required:
- dte_type
- document_issuer
- document_receiver
- details
properties:
date_issued:
type: string
format: date
description: >-
Fecha de emisión (YYYY-MM-DD). Si X-Use-Defaults es true y no se
proporciona, se usa la fecha actual.
folio:
type: string
description: >-
Folio del documento. Si X-Use-Defaults es true y no se proporciona,
se genera automáticamente.
dte_type:
$ref: '#/components/schemas/DteType'
document_issuer:
$ref: '#/components/schemas/DocumentIssuer'
document_receiver:
$ref: '#/components/schemas/DocumentReceiver'
details:
type: array
minItems: 1
items:
$ref: '#/components/schemas/DetailItem'
header:
$ref: '#/components/schemas/DocumentHeader'
references:
type: array
items:
$ref: '#/components/schemas/ReferenceItem'
json_param:
type: object
additionalProperties: true
description: JSON arbitrario almacenado textualmente
export_data:
$ref: '#/components/schemas/ExportData'
transport_data:
$ref: '#/components/schemas/TransportData'
DteType:
type: object
required:
- code
properties:
code:
type: string
description: |-
Código del tipo de documento:
- 33: Factura Electrónica
- 34: Factura Exenta Electrónica
- 39: Boleta Electrónica
- 41: Boleta Exenta Electrónica
- 46: Factura de Compra Electrónica
- 52: Guía de Despacho Electrónica
- 61: Nota de Crédito Electrónica
- 80: Boleta de Honorarios Electrónica
- 90: Boleta de Honorarios a Terceros Electrónica
- 110: Factura de Exportación Electrónica
enum:
- '33'
- '34'
- '39'
- '41'
- '46'
- '52'
- '61'
- '80'
- '90'
- '110'
DocumentIssuer:
type: object
required:
- rut
properties:
rut:
type: string
description: >-
RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
true, los demás campos se rellenarán automáticamente según la
configuración.
pattern: ^[0-9]{7,8}-[0-9K]$
business_name:
type: string
description: Razón social
phone_number:
type: string
description: Número de teléfono
email:
type: string
description: Correo electrónico
business_activity:
type: string
description: Giro comercial
activity_code:
type: integer
description: Código de actividad económica
sii_branch_code:
type: string
description: Código de sucursal SII
address:
type: string
description: Dirección
district:
type: string
description: Comuna
city:
type: string
description: Ciudad
DocumentReceiver:
type: object
required:
- rut
properties:
rut:
type: string
description: >-
RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
true, los demás campos se rellenarán automáticamente según la
configuración.
pattern: ^[0-9]{7,8}-[0-9K]$
business_name:
type: string
description: Razón social
contact:
type: string
description: Contacto
business_activity:
type: string
description: Giro comercial
address:
type: string
description: Dirección
district:
type: string
description: Comuna
city:
type: string
description: Ciudad
DetailItem:
type: object
required:
- item_name
- quantity
- unit_price
properties:
item_name:
type: string
description: Nombre del ítem
quantity:
type: number
description: Cantidad
unit_price:
type: number
format: float
minimum: 0
description: Precio unitario neto, sin IVA (no puede ser negativo)
gross_unit_price:
type: number
format: float
description: >-
Precio unitario bruto, con IVA incluido. Solo válido para boletas
electrónicas (dte_type 39 y 41); en cualquier otro tipo de documento
la API responde 422. No se puede combinar con unit_price en el mismo
documento: todas las líneas deben usar uno u otro. Si se envía, se
usa como unit_price para calcular item_total, y el neto/IVA del
documento se derivan a partir del bruto.
item_description:
type: string
description: Descripción del ítem
discount_percent:
type: number
format: float
description: Porcentaje de descuento
item_code:
type: string
description: Código del ítem
unit:
type: string
description: Unidad de medida
other_tax:
type: number
format: float
description: Otros impuestos
item_type_code:
type: integer
description: Código de tipo de ítem
DocumentHeader:
type: object
properties:
purchase_transaction_type:
type: string
description: Tipo de transacción de compra
nullable: true
sale_transaction_type:
type: string
description: Tipo de transacción de venta
nullable: true
payment_method:
type: string
description: Método de pago
enum:
- '1'
- '2'
- '3'
nullable: true
due_date:
type: string
format: date
description: Fecha de vencimiento
nullable: true
vat_withheld:
type: boolean
description: >-
Indica si el IVA está retenido. Solo aplicable para facturas de
compra (DTE 46) y notas de crédito que referencian facturas de
compra.
example: false
nullable: true
retention_type:
type: string
description: >-
Tipo de retención obligatorio para boletas de honorarios (DTE 80,
90). Define quién retiene el 14,5% legal.
enum:
- RETRECEPTOR
- RETCONTRIBUYENTE
example: RETRECEPTOR
nullable: true
purchase_type:
type: string
description: Tipo de compra para facturas recibidas en el SII
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
example: '1'
nullable: true
ReferenceItem:
type: object
required:
- reference_folio
- reference_date
- dte_type_code
properties:
reference_folio:
type: integer
description: Folio de referencia
reference_date:
type: string
format: date
description: Fecha de referencia
reference_reason:
type: string
description: >-
Razón de referencia. Para notas de crédito totales debe ser 'ANULA
DOCUMENTO DE LA REFERENCIA'.
example: ANULA DOCUMENTO DE LA REFERENCIA
dte_type_code:
type: string
description: Código del tipo de DTE del documento referenciado
ExportData:
type: object
description: >-
Datos específicos para facturas de exportación (DTE 110) y notas de
crédito de exportación (DTE 112). Solo requerido cuando se selecciona
uno de estos tipos de documento.
properties:
tax_id_receptor:
type: string
description: Identificación tributaria del receptor en el país de destino
destination_country_code:
type: string
description: >-
Código de país del SII del destino (tabla de Aduana). No es código
ISO 3166-1. Ver /user-guide/export-countries
example: '225'
currency_code:
type: string
description: >-
Código de moneda del SII (tabla de Aduana). No es código ISO 4217.
Ver /user-guide/export-currencies
example: '13'
exchange_rate:
type: string
description: Tipo de cambio aplicado
example: '800.50'
departure_port_code:
type: string
description: Código del puerto de embarque
arrival_port_code:
type: string
description: Código del puerto de desembarque
departure_port_name:
type: string
description: Nombre del puerto de embarque
arrival_port_name:
type: string
description: Nombre del puerto de desembarque
total_packages:
type: string
description: Número total de bultos
sale_mode_code:
type: string
description: Código de modalidad de venta
export_type:
type: string
description: Tipo de exportación
default: '0'
TransportData:
type: object
description: >-
Transport details for electronic dispatch guides (DTE 52) and related
flows. When `timber_enabled` is true, include CONAF timber origin fields
as required by SII for wood products.
required:
- transport_type
properties:
transport_type:
type: string
description: Transfer type code per SII (1–9).
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
example: '1'
transport_rut:
type: string
nullable: true
description: Tax ID (RUT) of the transport company, format 12345678-9.
example: 76123456-7
transport_plate:
type: string
nullable: true
description: Vehicle license plate.
example: ABCD12
driver_rut:
type: string
nullable: true
description: Driver tax ID (RUT).
example: 12345678-9
driver_name:
type: string
nullable: true
description: Driver full name.
example: Juan Pérez
timber_enabled:
type: boolean
description: When true, the dispatch includes timber origin data for CONAF.
default: false
example: false
comuna_rol:
type: string
nullable: true
description: SII commune code for the origin property roll (rol de origen).
example: '13101'
manzana_rol:
type: string
nullable: true
description: Block (manzana) of the origin property roll.
example: '12'
predio_rol:
type: string
nullable: true
description: Lot (predio) of the origin property roll.
example: '345'
geo_ref_system:
type: string
nullable: true
description: Geographic reference system code (e.g. 1 = WGS84).
example: '1'
latitude:
type: string
nullable: true
description: >-
Timber origin latitude as string (typically two decimal places per
SII).
example: '-33.45'
longitude:
type: string
nullable: true
description: >-
Timber origin longitude as string (typically two decimal places per
SII).
example: '-70.65'
conaf_plan_code:
type: string
nullable: true
description: CONAF forest management plan code.
example: PM-2024-001
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
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)
````