> ## 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
🚚 Guía de Despacho (DTE 52) - Para amparar el traslado de mercaderías
**Campos específicos:**
**document\_issuer y document\_receiver (Obligatorio):** Mismos campos que Factura Electrónica. En un traslado para exportación el receptor es quien recibe la carga en Chile (por ejemplo, la agencia de aduanas), no el importador extranjero.
**Resolución Exenta SII N°154 (vigente desde el 1 de noviembre de 2026):** en la guía pasan a ser obligatorios el tipo de traslado, la patente, el RUT del transportista, el chofer (o una declaración de transporte no informado), el destino con comuna, la fecha y hora de salida y la unidad de medida de cada línea. Hasta esa fecha la API acepta la guía y devuelve un aviso por cada dato faltante en `warnings` (códigos `res154_*`); desde esa fecha responde `422`. Ver [Resolución 154](#resolucion-154-dte-52).
**transport\_data (Opcional hasta el 1 de noviembre de 2026)**
* **Tipo:** Object
* **Descripción:** Tipo de traslado, tipo de despacho, transportista, chofer, salida y llegada, destino y datos de Aduana de la guía. Ver la tabla completa en [Guía de Despacho (DTE 52)](#guia-de-despacho-dte-52-transport-data).
* **Campos principales:**
* `transport_type` (String): Tipo de traslado (`IndTraslado`), `"1"` a `"9"`. Por defecto `"1"` (operación constituye venta)
* `dispatch_type` (String): Tipo de despacho (`TipoDespacho`), `"1"` a `"3"`. Si no se envía, se emite `3`. No se permite con `transport_type` `"5"`
* `transport_rut`, `transport_plate`, `driver_rut`, `driver_name` (String): Transportista, patente y chofer. **Obligatorios desde el 1 de noviembre de 2026**, salvo que se declare `transport_unknown_reason`
* `trailer_plate` (String): Patente del carro o remolque, cuando el vehículo lleva uno
* `departure_date` (`YYYY-MM-DD`), `departure_time` (`HH:MM`): Fecha y hora de inicio del traslado. **Obligatorias desde el 1 de noviembre de 2026**
* `arrival_date` (`YYYY-MM-DD`): Fecha estimada de llegada; no puede ser anterior a la salida
* `transfer_reason` (String, 200): Motivo del traslado. En un traslado que no es venta permite omitir el precio unitario de las líneas
* `transport_unknown_reason` (String, 100): Declaración expresa de que no se conocen patente, transportista o chofer, y por qué
* `destination_address`, `destination_district`, `destination_city` (String): Destino, cuando es distinto de la dirección del receptor. **Desde el 1 de noviembre de 2026** la guía necesita dirección y comuna de destino: las propias o, en su defecto, las del receptor
* `transfer_issuer_code` (String): Quién realiza el traslado de exportación (`CdgTraslado`), `"1"` a `"4"`, **sólo con `transport_type` `"8"` o `"9"`**. Con `"4"` van también `authorization_resolution_number` y `authorization_resolution_date`
* `departure_port_code`, `arrival_port_code`, `gross_weight`, `gross_weight_unit_code`, `total_packages`, `package_type_code`: Datos de Aduana, **sólo con `transport_type` `"8"` o `"9"`**
* `destination_commune_role`, `destination_block_role`, `destination_property_role`, `work_execution_notice`, `destination_latitude`, `destination_longitude`: Destino de la madera, **sólo con `timber_enabled` y facturador de mercado**. El rol predial de destino es obligatorio desde el 1 de noviembre de 2026
**details (Obligatorio)**
* **Tipo:** Array
* **Campos de cada elemento:** Mismos campos que Factura Electrónica (`item_name`, `quantity`, `unit_price`), más:
* `unit` (String): Unidad de medida de la línea (`UN`, `KG`, `M3`, ...). **Obligatoria en la guía desde el 1 de noviembre de 2026** (`UnmdItem` pasa a obligatorio en el Formato DTE 2026-02)
* `is_exempt` (Boolean): **Opcional, por defecto `false`.** Marca la línea como no afecta o exenta de IVA (`IndExe = 1`): su monto va a `exempt_amount` y no genera IVA. Por ahora sólo se acepta en DTE 52; en otro tipo de documento la API responde `422`.
* `gross_unit_price` (Number): **No aplica a este tipo de documento.** Solo válido para boletas electrónicas (DTE 39 y 41).
**references (Opcional)**
* Mismos campos que Nota de Crédito. En un traslado para exportación se puede referenciar el DUS con `dte_type_code` `"807"`.
**Facturador gratuito del SII (MiPyme):** su formulario no admite los datos de Aduana, el destino de la madera ni `details[].is_exempt`. Tampoco tiene campos para `dispatch_type`, `destination_*`, salida, llegada, patente del carro ni motivos: esos datos se aceptan igual y se imprimen como texto en la primera línea del detalle, como permite la Resolución 154 mientras el formulario no los tenga. Si el emisor usa el facturador gratuito y envías alguno, la API responde `422` con el mensaje *"no disponible para emisores del facturador gratuito del SII"*. Además, **una guía con precios siempre lleva IVA 19%** en el facturador gratuito; para un traslado de exportación con valor sin IVA se necesita el facturador de mercado.
✈️ 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
**export\_data (Obligatorio)**
* **Tipo:** Object
* **Descripción:** Información detallada de la exportación requerida por aduanas y SII
* **Campos obligatorios:**
* `destination_country_code` (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.
* Es el destino final de la mercadería (`CodPaisDestin`). Si no se envían `receiver_country_code` ni `receiver_nationality_code`, también se usa como país y nacionalidad del receptor
* `currency_code` (String): **Moneda de la operación**
* Código de moneda del SII, como *string* (ej: `"13"` = Dólar USA). No es ISO 4217.
* `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:**
* `receiver_country_code` (String): **País del receptor** — el `CodPaisRecep` del DTE
* Dónde está el comprador, cuando no es el país de destino de la mercadería (por ejemplo, en una triangulación: el comprador está en Holanda y la carga va a Alemania).
* Mismo código de país del SII que `destination_country_code`. Si no se envía, se usa `destination_country_code`.
* `receiver_nationality_code` (String): **Nacionalidad del receptor** — el `Extranjero/Nacionalidad` del DTE
* Mismo código de país del SII. Si no se envía, se usa `receiver_country_code` y, si tampoco viene, `destination_country_code`.
* `sale_clause_code` (String): **Cláusula de venta / Incoterm** — el `CodClauVenta` del DTE
* Define hasta dónde llegan la responsabilidad y el costo del vendedor. **No es lo mismo que `sale_mode_code`**, que es la *modalidad* de venta.
* Se acepta el **código del SII o el nombre del Incoterm** (`"5"` o `"FOB"`, indistintamente; el nombre no distingue mayúsculas ni acentos).
* Códigos: `"1"` = CIF, `"2"` = CFR, `"3"` = EXW, `"4"` = FAS, `"5"` = FOB, `"6"` = S/CL, `"8"` = OTROS, `"9"` = DDP, `"10"` = FCA, `"11"` = CPT, `"12"` = CIP, `"17"` = DAT, `"18"` = DAP.
* Un valor fuera de esta tabla devuelve `400` con la lista de opciones válidas.
* Para exportación de **bienes** el SII la exige; para exportación de **servicios** es opcional.
* `export_payment_method_code` (String): **Forma de pago de exportación** — el `FmaPagExp` del DTE
* Cómo se paga la operación: cobranza, acreditivo (carta de crédito), anticipo, etc. **No es `header.payment_method`**: ése es la forma de pago de las facturas nacionales (contado / crédito) y no aplica a exportación.
* Se acepta el **código del SII o el nombre** (`"11"` o `"ACRED"`, indistintamente).
* Códigos: `"1"` = COB1, `"2"` = COBRANZA, `"11"` = ACRED, `"12"` = CBOF, `"21"` = S/PAGO, `"32"` = ANTICIPO, `"50"` = ANT/COB, `"60"` = ANT/CRED, `"80"` = S/PAGO/COB.
* Si no se envía, el documento se emite con `"21"` (sin pago); en ese caso el SII exige que el total en pesos vaya en cero.
* Un valor fuera de esta tabla devuelve `400` con la lista de opciones válidas.
* `exchange_rate` (String o Number): **Tipo de cambio** a pesos chilenos (ej: `"965.40"`)
* Si no se envía, la plataforma usa el observado del día de emisión.
* `tax_id_receptor` (String): Tax ID / identificador tributario del receptor extranjero
* `departure_port_code` / `departure_port_name` (String): Puerto de embarque (código del SII / nombre)
* `arrival_port_code` / `arrival_port_name` (String): Puerto de desembarque (código del SII / nombre)
* `total_packages` (Integer): Total de bultos
* `export_type` (String): `IndServicio` del DTE. Vacío o `"0"` = exportación de bienes; `"3"`/`"4"`/`"5"`/`"6"` = exportación de servicios.
**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
## Validación de campos desconocidos
La API compara cada documento con los campos que acepta. Un campo que no existe (por ejemplo, un nombre mal escrito o de una versión antigua de la documentación) **no se usa al emitir**: antes se descartaba sin aviso; ahora se informa.
### Modo aviso: `warnings`
La respuesta del batch (v1 y v2) puede incluir un arreglo `warnings` en el primer nivel, con un elemento por campo desconocido. El documento **se crea igual**, sin ese campo.
```json theme={null}
{
"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"
}
]
}
```
| Campo | Tipo | Descripción |
| - | - | - |
| `document_index` | Integer | Posición del documento en el arreglo `documents` (desde 0) |
| `field` | String | Ruta del campo dentro del documento |
| `code` | String | Tipo de aviso. Hoy siempre `"unknown_field"` |
| `message` | String | Texto para personas; puede cambiar, no lo parsees |
| `suggestion` | String o `null` | Campo correcto, si se reconoce el error; `null` si no hay sugerencia |
Sugerencias conocidas:
| Campo enviado | Campo correcto |
| - | - |
| `header.transfer_indicator` | `transport_data.transport_type` |
| `export_data.export_clause` | `export_data.sale_clause_code` |
| `export_data.destination_country` | `export_data.destination_country_code` |
Un aviso significa que **el dato no llegó al documento**. Por ejemplo, con `header.transfer_indicator` la guía se emite con el tipo de traslado por defecto (`"1"`, venta), y con `export_data.export_clause` la factura de exportación sale sin cláusula de venta. Revisa los `warnings` en cada respuesta y corrige tu integración.
### Modo estricto: `422`
Las API keys con **validación estricta** reciben `422` en vez del aviso, y no se crea ningún documento del batch. El error va bajo la posición del documento (como string, desde `"0"`) y la ruta del campo; en las listas (`details`, `references`, `payments`) la posición de la línea también es una llave:
```json theme={null}
{
"documents": {
"0": {
"header": {
"transfer_indicator": ["Campo desconocido. ¿Quisiste decir transport_data.transport_type?"]
},
"details": {
"1": {"exento": ["Campo desconocido."]}
}
}
}
}
```
Es el mismo formato que el resto de los errores de validación del batch, en v1 y en v2.
* Las **API keys nuevas** tienen la validación estricta activada.
* Las **integraciones existentes** reciben primero los `warnings`, para que puedan corregir sus campos sin que se rompa la emisión. El paso a modo estricto de una API key existente se coordina con Tupana.
* El texto del mensaje puede cambiar: usa la ruta del campo para identificar el error.
* **API keys del flujo diferido** (prefijo `gw_`): el aviso llega en el `202` junto a `batch_id`, y con validación estricta el `422` trae el mismo objeto dentro de `errors` (`{"errors": {"documents": {...}}, "request": {...}}`).
## 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
* `warnings` (Array, opcional): Avisos sobre campos desconocidos que se ignoraron. Ver [Validación de campos desconocidos](#validacion-de-campos-desconocidos)
#### 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
* **Cuerpo malformado** (por ejemplo `documents` no es una lista): `{"error": "..."}`.
* **Validación de documentos:** los errores van bajo `documents`, con la posición del documento como llave y la ruta del campo adentro. Ejemplo con una guía de traslado de exportación sin datos de Aduana:
```json theme={null}
{
"documents": {
"0": {
"transport_data": {
"gross_weight": ["Requerido en guías de traslado de exportación (transport_type 8 o 9): el SII lo exige en Transporte/Aduana."]
}
}
}
}
```
### 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 propios del cliente que se guardan tal cual junto con el documento. Se envía dentro de cada elemento de `documents` (mismo nivel que `header`, `details`, etc.).
* **Estructura:** Objeto JSON libre, ej. `{"external_order_id": "PED-123", "idempotency_key": "..."}`. No se valida ni se transforma.
* **Lectura:** vuelve en el detalle (`GET /documents/{document_id}/`) y en el listado.
* **Búsqueda:** el listado permite `json_param__=` (ver [Filtrar por json\_param](/api-reference/documents/list#filtrar-por-json-param-campos-personalizados)). Guarda ahí tu propio identificador (por ejemplo el `Idempotency-Key` con que creaste el batch) para reencontrar el documento aunque pierdas la respuesta de creación.
```json theme={null}
{
"documents": [
{
"dte_type": { "code": "33" },
"document_issuer": { "...": "..." },
"document_receiver": { "...": "..." },
"details": [ { "...": "..." } ],
"json_param": { "external_order_id": "PED-123" }
}
]
}
```
**additional\_info (String):**
Este campo solo tiene efecto si tu empresa usa el **PDF propio** (PDF personalizado de Tu Pana) o emite con el **facturador de mercado**. Si tu empresa usa el PDF oficial del SII, el texto se guarda y se devuelve en la API, pero **no aparece en el PDF**.
* **Descripción:** Texto libre que se imprime en un recuadro **"Información adicional"** al final del PDF, justo antes del timbre. Se envía dentro de cada elemento de `documents` (mismo nivel que `header`, `details`, etc.).
* **Largo máximo:** 1000 caracteres. Los saltos de línea (`\n`) separan líneas dentro del recuadro.
* **No se envía al SII:** no forma parte del XML del documento, solo del PDF.
* **Dónde aparece:** solo en el PDF propio de Tu Pana o del facturador de mercado (ver aviso arriba).
* **Edición:** se puede cambiar mientras el documento es borrador; una vez emitido no se puede modificar.
* **Lectura:** vuelve en la respuesta del batch, en el detalle (`GET /documents/{document_id}/`), en el listado y en los webhooks (`null` si no se envió).
```json theme={null}
{
"documents": [
{
"dte_type": { "code": "33" },
"document_issuer": { "...": "..." },
"document_receiver": { "...": "..." },
"details": [ { "...": "..." } ],
"additional_info": "Orden de compra N° 4500123\nPago por transferencia a la cuenta corriente 00-123-45678-09"
}
]
}
```
## 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
}
]
}
]
}
```
#### Guía de Despacho de venta (DTE 52)
Guía que acompaña una venta, despachada por el emisor a una bodega del cliente distinta de su dirección. Las líneas son afectas: la guía lleva IVA.
```json theme={null}
{
"documents": [
{
"dte_type": {
"code": "52"
},
"date_issued": "2026-09-15",
"document_issuer": {
"rut": "12345678-9"
},
"document_receiver": {
"rut": "98765432-1",
"business_name": "Cliente Importante Ltda"
},
"transport_data": {
"transport_type": "1",
"dispatch_type": "2",
"transport_rut": "76234567-6",
"transport_plate": "ABCD12",
"trailer_plate": "JK1234",
"driver_rut": "12345678-5",
"driver_name": "Juan Pérez",
"departure_date": "2026-11-02",
"departure_time": "08:30",
"arrival_date": "2026-11-02",
"destination_address": "Camino Lo Boza 120, Bodega 4",
"destination_district": "Pudahuel",
"destination_city": "Santiago"
},
"details": [
{
"item_name": "Pastillas de freno",
"quantity": 40,
"unit": "UN",
"unit_price": 12500
},
{
"item_name": "Discos de freno",
"quantity": 10,
"unit": "UN",
"unit_price": 38000
}
]
}
]
}
```
#### Guía de Despacho de traslado para exportación (DTE 52)
Traslado de mercadería de exportación desde la fábrica al aeropuerto. La venta va en la factura de exportación; la guía declara el tipo de traslado `"8"`, los datos de Aduana, el valor de la carga como línea exenta y el DUS como referencia.
```json theme={null}
{
"documents": [
{
"dte_type": {
"code": "52"
},
"date_issued": "2026-09-15",
"document_issuer": {
"rut": "12345678-9"
},
"document_receiver": {
"rut": "76123456-0",
"business_name": "Agencia de Aduanas Ejemplo Ltda"
},
"transport_data": {
"transport_type": "8",
"dispatch_type": "3",
"transfer_issuer_code": "1",
"transport_rut": "76234567-6",
"transport_plate": "PJRL69",
"driver_rut": "12345678-5",
"driver_name": "Juan Pérez",
"destination_address": "Aeropuerto Arturo Merino Benitez",
"destination_district": "Pudahuel",
"destination_city": "Santiago",
"departure_port_code": "992",
"arrival_port_code": "134",
"gross_weight": "1414.00",
"gross_weight_unit_code": "6",
"total_packages": 3,
"package_type_code": "22"
},
"details": [
{
"item_name": "Balatas de freno",
"item_description": "Partida arancelaria 6813.81.00",
"quantity": 3,
"unit_price": 1350000,
"is_exempt": true
}
],
"references": [
{
"dte_type_code": "807",
"reference_folio": "13717477-4",
"reference_date": "2026-09-15",
"reference_reason": "DUS 13717477-4"
}
]
}
]
}
```
La guía queda con `exempt_amount` 4.050.000, IVA 0 y total 4.050.000.
#### 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"
},
"header": {
"sale_transaction_type": 1,
"currency": "USD"
},
"export_data": {
"destination_country_code": "225",
"currency_code": "13",
"sale_mode_code": "1",
"sale_clause_code": "5",
"export_payment_method_code": "11",
"exchange_rate": "965.40"
},
"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
## 🚚 **Guía de Despacho (DTE 52)**
### Campos de transport\_data
Todos los campos son opcionales salvo lo que se indica. Los mismos campos se aceptan en `POST /v1/documents/batch/` y en `POST /v2/documents/batch/`. La columna **Res. 154** marca lo que pasa a ser obligatorio en la guía el **1 de noviembre de 2026** (ver [Resolución 154](#resolucion-154-dte-52)).
| Campo | Tipo | Obligatorio | Res. 154 | Validación | Campo del DTE |
| - | - | - | - | - | - |
| `transport_type` | String `"1"`–`"9"` | No (por defecto `"1"`) | Obligatorio | Tabla de tipos de traslado | `IdDoc/IndTraslado` |
| `dispatch_type` | String `"1"`–`"3"` | No (si no se envía, se emite `3`) | — | No se permite con `transport_type` `"5"` | `IdDoc/TipoDespacho` |
| `transport_rut` | String | No | Obligatorio (o `transport_unknown_reason`) | Si el dígito verificador es inválido se emite igual y la respuesta trae un aviso `invalid_rut` | `Transporte/RUTTrans` |
| `transport_plate` | String | No | Obligatorio (o `transport_unknown_reason`) | Se normaliza a mayúsculas sin guion ni espacios; máximo 8 caracteres | `Transporte/Patente` |
| `driver_rut` | String | Con `driver_name` | Obligatorio (o `transport_unknown_reason`) | Si el dígito verificador es inválido se emite igual y la respuesta trae un aviso `invalid_rut` | `Transporte/Chofer/RUTChofer` |
| `driver_name` | String | Con `driver_rut` | Obligatorio (o `transport_unknown_reason`) | Se trunca a 30 caracteres en el DTE | `Transporte/Chofer/NombreChofer` |
| `destination_address` | String | No | Obligatoria (vale la dirección del receptor) | Máximo 70 caracteres | `Transporte/DirDest` |
| `destination_district` | String | No | Obligatoria (vale la comuna del receptor) | Máximo 20 caracteres | `Transporte/CmnaDest` |
| `destination_city` | String | No | — | Máximo 20 caracteres | `Transporte/CiudadDest` |
| `transfer_issuer_code` | String `"1"`–`"4"` | Con traslado `"8"`/`"9"` (facturador de mercado) | — | Ver [Emisor del traslado](#emisor-del-traslado-transfer-issuer-code). Sólo con `transport_type` `"8"` o `"9"` | `Emisor/GuiaExport/CdgTraslado` |
| `authorization_resolution_number` | Integer | Con `transfer_issuer_code` `"4"` | — | Mayor a 0; no se permite con otro código | `Emisor/GuiaExport/FolioAut` |
| `authorization_resolution_date` | String `YYYY-MM-DD` | Con `transfer_issuer_code` `"4"` | — | No se permite con otro código | `Emisor/GuiaExport/FchAut` |
| `departure_port_code` | String | Con traslado `"8"`/`"9"` (facturador de mercado) | — | Código o nombre exacto de la tabla de puertos de Aduana | `Aduana/CodPtoEmbarque` |
| `arrival_port_code` | String | Con traslado `"8"`/`"9"` (facturador de mercado) | — | Código o nombre exacto de la tabla de puertos de Aduana | `Aduana/CodPtoDesemb` |
| `gross_weight` | String decimal | Con traslado `"8"`/`"9"` (facturador de mercado) | — | Mayor a 0, hasta 2 decimales | `Aduana/PesoBruto` |
| `gross_weight_unit_code` | String | Con traslado `"8"`/`"9"` (facturador de mercado) | — | Tabla de unidades de medida de Aduana | `Aduana/CodUnidPesoBruto` |
| `total_packages` | Integer | No | — | Mayor a 0 | `Aduana/TotBultos` |
| `package_type_code` | String | Si se envía `total_packages` | — | Tabla de tipos de bulto de Aduana | `Aduana/TipoBultos/CodTpoBultos` |
| `trailer_plate` | String | No | Aviso si hay patente y no viene carro (`res154_trailer_plate`, nunca `422`) | Igual que `transport_plate`: mayúsculas, sin guion ni espacios, máximo 8 | `Transporte/PatenteCarro` |
| `departure_date` | String `YYYY-MM-DD` | No | Obligatoria | Fecha válida | `Transporte/FchSalida` |
| `departure_time` | String `HH:MM` | No | Obligatoria | También se acepta `HH:MM:SS` | `Transporte/HraSalida` |
| `arrival_date` | String `YYYY-MM-DD` | No | — | No puede ser anterior a `departure_date` | `Transporte/FchLlegada` |
| `transfer_reason` | String | No | Obligatorio si un traslado que no es venta omite `unit_price` | Máximo 200 caracteres | Texto en el detalle |
| `transport_unknown_reason` | String | No | Reemplaza patente, transportista y chofer cuando no se conocen | Máximo 100 caracteres | Texto en el detalle |
| `timber_enabled`, `comuna_rol`, `manzana_rol`, `predio_rol`, `geo_ref_system`, `latitude`, `longitude`, `conaf_plan_code` | — | No | — | Sin cambios | `ManejoMadera` (CONAF) |
| `destination_commune_role`, `destination_block_role`, `destination_property_role` | String numérico (1 a 6 dígitos) | No | Obligatorios con `timber_enabled` (facturador de mercado) | Sólo con `timber_enabled` | `ManejoMadera/ComunaRolDestino`, `MnzRolDestino`, `PrdRolDestino` |
| `work_execution_notice`, `destination_latitude`, `destination_longitude` | String | No | — | Máximo 40 / 30 / 30 caracteres. Sólo con `timber_enabled` | `ManejoMadera/AvisoEjecucionFaena`, `LatitudDestinoMadera`, `LongitudDestinoMadera` |
Los campos de transporte y destino también se aceptan en otros tipos de documento; los de Aduana y el emisor del traslado, sólo con `transport_type` `"8"` o `"9"`.
### Tipo de traslado (`transport_type`)
| Código | Tipo de traslado | Código | Tipo de traslado |
| - | - | - | - |
| `"1"` | Operación constituye venta | `"6"` | Otros traslados no venta |
| `"2"` | Ventas por efectuar | `"7"` | Devolución de mercaderías |
| `"3"` | Consignaciones | `"8"` | Traslado para exportación (no venta) |
| `"4"` | Entrega gratuita | `"9"` | Venta para exportación |
| `"5"` | Traslados internos | | |
### Tipo de despacho (`dispatch_type`)
| Código | Tipo de despacho |
| - | - |
| `"1"` | Por cuenta del receptor (el cliente retira) |
| `"2"` | Por cuenta del emisor, a instalaciones del cliente |
| `"3"` | Por cuenta del emisor, a otras instalaciones |
### Datos de Aduana (traslados `"8"` y `"9"`)
* El SII los exige en guías con tipo de traslado 8 y 9: con el **facturador de mercado**, `transfer_issuer_code`, `departure_port_code`, `arrival_port_code`, `gross_weight` y `gross_weight_unit_code` son obligatorios.
* Mismos nombres que en `export_data` de la factura de exportación, para usar las mismas llaves en la guía y en la factura.
* Los puertos aceptan el **código o el nombre exacto** de la tabla de Aduana del SII (`"992"` o `"AEROP.A.M.BENITEZ"`, indistintamente). Ejemplos: `"906"` = SAN ANTONIO, `"905"` = VALPARAISO, `"992"` = AEROP.A.M.BENITEZ, `"134"` = NEW YORK, `"292"` = SANTOS.
* `gross_weight_unit_code` usa la tabla de unidades de Aduana (ej: `"6"` = KN). `package_type_code` usa la tabla de tipos de bulto (ej: `"22"` = CAJA DE CARTON).
* **Tablas completas de puertos, unidades y tipos de bulto:** [Códigos de transporte y Aduana](/user-guide/transport-codes).
Ejemplo:
```json theme={null}
"transport_data": {
"transport_type": "8",
"transfer_issuer_code": "1",
"departure_port_code": "AEROP.A.M.BENITEZ",
"arrival_port_code": "134",
"gross_weight": "1414.00",
"gross_weight_unit_code": "6",
"total_packages": 3,
"package_type_code": "22"
}
```
### Emisor del traslado (`transfer_issuer_code`)
En guías de traslado 8 y 9 el SII exige indicar en qué calidad se emite la guía (`Emisor/GuiaExport/CdgTraslado`). Sin este dato el SII acepta la guía con reparo (HED-2-804), por eso con el facturador de mercado es obligatorio.
| Código | Emisor del traslado |
| - | - |
| `"1"` | Exportador |
| `"2"` | Agente de Aduana |
| `"3"` | Vendedor |
| `"4"` | Contribuyente autorizado expresamente por el SII: requiere `authorization_resolution_number` y `authorization_resolution_date` |
### Resolución 154 (DTE 52)
La [Resolución Exenta SII N°154 de 2025](https://www.sii.cl/normativa_legislacion/resoluciones/2025/reso154.pdf), prorrogada por la Resolución Exenta N°52 de 2026, fija el contenido mínimo de la guía de despacho y rige desde el **1 de noviembre de 2026**. La API aplica las mismas reglas en v1 y v2:
* **Hasta el 31 de octubre de 2026:** la guía se acepta igual y la respuesta del batch trae un aviso por cada dato faltante en `warnings`, con `document_index`, `field`, `code` (`res154_*`), `message` y `suggestion`. Los avisos también aparecen en el borrador y en la vista previa de la plataforma.
* **Desde el 1 de noviembre de 2026:** los mismos datos faltantes responden `422` con el campo bajo `documents` → posición → `transport_data` o `details[]`, y la guía no se crea. El único aviso que nunca pasa a `422` es `res154_trailer_plate`.
| Código del aviso | Qué falta | Cómo resolverlo |
| - | - | - |
| `res154_transfer_type` | `transport_type` | Informar el tipo de traslado `"1"`–`"9"` |
| `res154_carrier` | `transport_plate`, `transport_rut` o `driver_rut` + `driver_name` | Informarlos, o declarar en `transport_unknown_reason` por qué no se conocen |
| `res154_destination` | Dirección o comuna de destino | `destination_address` + `destination_district`, o la dirección y comuna del receptor en `document_receiver` |
| `res154_departure` | `departure_date` o `departure_time` | Fecha y hora de inicio del traslado |
| `res154_unit` | `details[].unit` | Unidad de medida en cada línea (`UN`, `KG`, `M3`, ...) |
| `res154_transfer_reason` | Precio unitario | En un traslado que constituye venta (`"1"`, `"9"`) cada línea lleva `unit_price`; en los demás se puede omitir si viene `transfer_reason` |
| `res154_trailer_plate` | `trailer_plate` | Sólo aviso: si el vehículo lleva carro o remolque, informar su patente |
| `res75_timber_destination` | Rol predial de destino de la madera | `destination_commune_role`, `destination_block_role` y `destination_property_role` (sólo con `timber_enabled`, facturador de mercado) |
Ejemplo de aviso (misma forma en v1 y v2):
```json theme={null}
{
"warnings": [
{
"document_index": 0,
"field": "transport_data.departure_time",
"code": "res154_departure",
"message": "La hora de inicio del traslado es obligatoria.",
"suggestion": "Informe transport_data.departure_time (HH:MM)."
}
]
}
```
#### Origen efectivo del traslado
La resolución exige el **origen efectivo** de las mercaderías. La guía toma como origen la dirección del emisor (`document_issuer.address`, `district`, `city`). Puedes usar cualquier dirección de la empresa **registrada en el SII** (casa matriz o sucursal): Tupana las sincroniza al perfil de la empresa con su código de sucursal, y al coincidir el texto de `document_issuer.address` con una de ellas la guía sale con ese código en `Emisor/CdgSIISucur`. Usa exactamente el mismo texto que figura en el perfil de la empresa. Si la bodega no está registrada en el SII, regístrala primero allí; las direcciones no se administran por la API.
#### Anulación de una guía
Si cambia lo informado (cantidad, destino, transporte), la resolución pide **emitir una guía nueva que referencie a la anterior** (`references[]` con `dte_type_code` `"52"`) y registrar la original como anulada. La anulación se registra con el endpoint de estados del documento:
```bash theme={null}
curl -X POST "https://api.tupana.ai/v2/documents/{document_id}/states/" \
-H "Authorization: Api-Key TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event_code": "ANNULLED", "reason": "Reemplazada por guía folio 1051: cambió la cantidad de bultos"}'
```
Respuesta `200`:
```json theme={null}
{
"success": true,
"annulment": {
"annulled": true,
"already_annulled": false,
"registry": "delivery_note_book",
"registry_note": "La guía queda como anulada en el Libro de Guías de Despacho del período."
}
}
```
* Sólo el emisor puede anular (`403`), sólo guías (DTE 52) emitidas con folio y siempre con `reason` (`400` con `code` `annulment_only_for_delivery_notes`, `annulment_only_for_issued_delivery_notes` o `annulment_reason_required`).
* `registry` indica dónde queda el registro mientras el SII no habilite el Registro de Guías: `delivery_note_book` (Libro de Guías, facturador de mercado) o `portal_follow_up` (facturador gratuito del SII: además hay que anotarla en "Seguimiento del documento" del portal).
* Anular dos veces responde `200` con `already_annulled: true`. El mismo endpoint existe en v1 (`POST /v1/documents/{document_id}/states/`).
### Líneas exentas (`details[].is_exempt`)
* `is_exempt: true` marca la línea como no afecta o exenta (`IndExe = 1` en el DTE).
* Las líneas exentas suman a `document_total.exempt_amount` y no generan IVA; las afectas suman al neto y llevan IVA 19%. `total_amount = net_amount + iva_amount + exempt_amount`.
* Para una guía toda exenta, marca todas las líneas. No hay marca a nivel de documento.
* Por ahora sólo en DTE 52: en otros tipos de documento la API responde `422`.
### Facturador gratuito del SII (MiPyme)
| Campo | Facturador de mercado | Facturador gratuito |
| - | - | - |
| `transport_type` (incluidos `"8"` y `"9"`) | ✅ | ✅ |
| `transport_rut`, `transport_plate`, `driver_rut`, `driver_name`, madera (origen) | ✅ | ✅ |
| `trailer_plate`, `departure_date`, `departure_time`, `arrival_date`, `transfer_reason`, `transport_unknown_reason` | ✅ (tags del DTE o texto en el detalle) | ✅ (texto en la primera línea del detalle) |
| `destination_commune_role`, `destination_block_role`, `destination_property_role`, `work_execution_notice`, `destination_latitude`, `destination_longitude` | ✅ | ❌ `422` |
| `dispatch_type` | ✅ | ✅ (texto en la primera línea del detalle) |
| `destination_address`, `destination_district`, `destination_city` | ✅ | ✅ (texto en la primera línea del detalle) |
| Datos de Aduana | ✅ (obligatorios con `"8"`/`"9"`) | ❌ `422` (no se exigen con `"8"`/`"9"`) |
| `details[].is_exempt` | ✅ | ❌ `422` |
El mensaje de error indica que el campo está *"no disponible para emisores del facturador gratuito del SII"*. Lo que va como texto se escribe al inicio de la descripción de la primera línea, por ejemplo: `Destino: Camino Lo Boza 120, Pudahuel, Santiago. Despacho: Por cuenta del emisor a instalaciones del cliente. Salida: 02-11-2026 08:30.`
En el facturador gratuito del SII **una guía con precios siempre lleva IVA 19%**: el formulario del SII no permite líneas exentas. Para un traslado de exportación con valor sin IVA, el emisor necesita el facturador de mercado.
### Errores de validación (422)
La guía se valida al recibir el batch, antes de emitir, para no quemar folios con rechazos del SII. Cada error indica el documento y la ruta del campo:
| Caso | Respuesta |
| - | - |
| `transport_type` fuera de `"1"`–`"9"` o `dispatch_type` fuera de `"1"`–`"3"` | `422` con las opciones válidas |
| `dispatch_type` con `transport_type` `"5"` | `422` |
| Sólo `driver_rut` o sólo `driver_name` | `422`: se envían los dos o ninguno |
| `destination_address` > 70, `destination_district` > 20 o `destination_city` > 20 caracteres | `422` |
| Datos de Aduana con un `transport_type` distinto de `"8"`/`"9"` | `422` |
| Traslado `"8"`/`"9"` sin puertos, peso bruto o unidad (facturador de mercado) | `422` |
| Puerto, unidad o tipo de bulto fuera de la tabla de Aduana | `422` |
| `gross_weight` o `total_packages` menor o igual a 0 | `422` |
| `total_packages` sin `package_type_code` | `422` |
| `details[].is_exempt` en un documento que no es DTE 52 | `422`: no soportado para este tipo de documento |
| Aduana, destino de la madera o `is_exempt` con emisor del facturador gratuito | `422`: no disponible para emisores del facturador gratuito del SII |
| `trailer_plate` de más de 8 caracteres (sin guion ni espacios) | `422` |
| `arrival_date` anterior a `departure_date` | `422` |
| `transfer_reason` > 200 o `transport_unknown_reason` > 100 caracteres | `422` |
| Rol predial de destino de la madera con otra cosa que 1 a 6 dígitos | `422` |
| **Desde el 1 de noviembre de 2026:** falta tipo de traslado, patente/transportista/chofer (sin `transport_unknown_reason`), destino, salida, `details[].unit`, precio en una venta o rol predial de destino con madera | `422` (hasta esa fecha, aviso `res154_*`) |
Ejemplo de respuesta v1 (el error va en la posición del documento dentro de `documents`):
```json theme={null}
{
"documents": [
{
"transport_data": {
"dispatch_type": ["Valor inválido. Opciones: 1, 2, 3."]
}
}
]
}
```
En v2 el error usa el formato de [errores v2](/api-reference/v2/errors) con `type` `validation_error`.
### Respuesta
`GET /v1/documents/{id}` y `GET /v2/documents/{id}/` devuelven `transport_data` con todos los campos anteriores, `details[].is_exempt` y `document_total.exempt_amount`.
## ✈️ **Factura de Exportación (DTE 110)**
### Campos requeridos en export\_data:
* **`destination_country_code`** (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.
* Es el destino final de la mercadería (`CodPaisDestin`). Si el receptor está en otro país, ver la sección "País y nacionalidad del receptor" más abajo
* **`currency_code`** (String, Obligatorio):
* Código de moneda del SII (ej: `"13"` = Dólar USA). No es ISO 4217.
* **`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.
### País y nacionalidad del receptor
El DTE de exportación declara tres países distintos. Normalmente son el mismo y basta con `destination_country_code`. Cuando no coinciden (por ejemplo, el comprador es una distribuidora en Holanda y la carga va directo a Alemania), se informan por separado:
| Campo | Tag del DTE | Si no se envía |
| - | - | - |
| `destination_country_code` | `Aduana/CodPaisDestin` | Obligatorio |
| `receiver_country_code` | `Aduana/CodPaisRecep` | Se usa `destination_country_code` |
| `receiver_nationality_code` | `Receptor/Extranjero/Nacionalidad` | Se usa `receiver_country_code` y, si tampoco viene, `destination_country_code` |
Los tres usan los códigos de país del SII ([Países de exportación](/user-guide/export-countries)). Un código fuera de la tabla devuelve `400`.
```json theme={null}
"export_data": {
"destination_country_code": "563",
"receiver_country_code": "515",
"currency_code": "142",
"sale_mode_code": "1"
}
```
En este ejemplo la carga va a Alemania (`563`), el comprador está en Holanda (`515`) y su nacionalidad también queda como Holanda, porque no se envió `receiver_nationality_code`.
### Cláusula de venta (Incoterm)
* **`sale_clause_code`** (String, Opcional):
* Es el **Incoterm** de la operación (`CodClauVenta` del DTE): FOB, EXW, CIF, etc.
* **No confundir con `sale_mode_code`**: ése es la *modalidad* de venta (a firme, en consignación...). Son dos campos distintos del DTE.
* Se acepta el código o el nombre: `"5"` y `"FOB"` son equivalentes.
| Código | Cláusula | Código | Cláusula |
| - | - | - | - |
| `"1"` | CIF | `"8"` | OTROS |
| `"2"` | CFR | `"9"` | DDP |
| `"3"` | EXW | `"10"` | FCA |
| `"4"` | FAS | `"11"` | CPT |
| `"5"` | FOB | `"12"` | CIP |
| `"6"` | S/CL | `"17"` | DAT |
| | | `"18"` | DAP |
Ejemplo — pasar de Ex Works a FOB:
```json theme={null}
"export_data": {
"destination_country_code": "225",
"currency_code": "13",
"sale_mode_code": "1",
"sale_clause_code": "FOB"
}
```
### Forma de pago de exportación
* **`export_payment_method_code`** (String, Opcional, por defecto `"21"`):
* Es la **forma de pago** de la operación de exportación (`FmaPagExp` del DTE).
* **`header.payment_method` no aplica a exportación**: el DTE de exportación no lleva la forma de pago nacional (contado / crédito), así que ese campo se ignora en los tipos 110, 111 y 112.
* Se acepta el código o el nombre: `"11"` y `"ACRED"` son equivalentes.
| Código | Forma de pago | Código | Forma de pago |
| - | - | - | - |
| `"1"` | COB1 | `"32"` | ANTICIPO |
| `"2"` | COBRANZA | `"50"` | ANT/COB |
| `"11"` | ACRED | `"60"` | ANT/CRED |
| `"12"` | CBOF | `"80"` | S/PAGO/COB |
| `"21"` | S/PAGO | | |
* Sin el campo el documento sale como **sin pago** (`"21"`): el SII exige entonces que el total en pesos (`MntTotOtrMnda`) vaya en cero.
* Con **ANTICIPO** (`"32"`) el DTE declara como fecha de pago la fecha de emisión.
* La forma de pago se muestra en el PDF, en el recuadro de exportación.
### 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**: `document_receiver` no lleva país. Los países van en `export_data`: `destination_country_code` (destino) y, si son distintos, `receiver_country_code` y `receiver_nationality_code`
### 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 api-reference/openapi-v2.json POST /documents/batch/
openapi: 3.0.0
info:
title: Tupana API — v2
description: >-
API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
boleta de honorarios y nómina. Los identificadores de recursos son public
IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
version: 2.0.0
servers:
- url: https://api.tupana.ai/v2
description: Producción (v2)
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_v2
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: docu_9f2a7c1b8e4d0
folio: '1'
date_issued: '2024-01-15'
amount_with_iva: 119000
receiver_id: ment_4829301923847
is_draft: false
can_be_issued: true
dte_type:
code: '33'
description: Factura Electrónica
sender:
id: ment_4829301923847
name: Mi Empresa SpA
tax_id: 12345678-9
receiver:
id: ment_4829301923847
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
is_exempt:
type: boolean
description: >-
true si la línea es no afecta o exenta de IVA
(IndExe = 1).
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
exempt_amount:
type: number
nullable: true
description: >-
Monto exento: suma de las líneas con is_exempt en
true. total_amount = net_amount + iva_amount +
exempt_amount.
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
warnings:
type: array
description: >-
Avisos sobre campos desconocidos que se ignoraron (modo aviso). Sólo
aparece si hay avisos. Con validación estricta, la API responde 422
en vez de avisar.
items:
$ref: '#/components/schemas/BatchWarning'
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'
export_data:
$ref: '#/components/schemas/ExportData'
transport_data:
$ref: '#/components/schemas/TransportData'
json_param:
type: object
additionalProperties: true
nullable: true
description: >-
Campos propios del cliente (objeto JSON libre, ej.
`{"external_order_id": "PED-123"}`). Se guarda tal cual con el
documento, vuelve en `GET /documents/{document_id}/` y en el
listado, y permite buscar el documento con
`json_param__=` en `GET /documents/`. Úsalo para guardar
tu propio identificador (ej. el `Idempotency-Key` o el id de tu
pedido) y así reencontrar el documento aunque pierdas la respuesta
de creación.
example:
external_order_id: PED-123
additional_info:
type: string
maxLength: 1000
nullable: true
description: >-
Texto libre (máximo 1000 caracteres) que se imprime en un recuadro
"Información adicional" al final del PDF, justo antes del timbre. No
se envía al SII: no forma parte del XML. Solo se imprime si tu
empresa usa el PDF propio (PDF personalizado de Tu Pana) o emite con
el facturador de mercado; en cualquier otro caso (PDF oficial del
SII) el texto se guarda y se devuelve en la API, pero no aparece en
el PDF. Los saltos de línea se respetan. No se puede modificar una
vez emitido el documento.
example: 'Orden de compra N° 4500123 - Centro de costo: Operaciones'
BatchWarning:
type: object
description: >-
Aviso sobre un campo desconocido del documento: se ignoró al crear el
documento. Las API keys con validación estricta reciben 422 en vez del
aviso.
properties:
document_index:
type: integer
description: Posición del documento en el arreglo documents (desde 0).
example: 0
field:
type: string
description: Ruta del campo dentro del documento.
example: header.transfer_indicator
code:
type: string
description: >-
unknown_field: campo desconocido (se ignoró). invalid_rut: RUT de
transportista o chofer con dígito verificador inválido (se emitió
igual).
enum:
- unknown_field
- invalid_rut
example: unknown_field
message:
type: string
description: 'Texto para personas. Puede cambiar: no lo parsees.'
example: 'Campo desconocido: se ignoró.'
suggestion:
type: string
nullable: true
description: >-
Campo correcto, si se reconoce el error (ej:
header.transfer_indicator → transport_data.transport_type,
export_data.export_clause → export_data.sale_clause_code,
export_data.destination_country →
export_data.destination_country_code). null si no hay sugerencia.
example: transport_data.transport_type
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.
is_exempt:
type: boolean
default: false
description: >-
Marca la línea como no afecta o exenta de IVA (Detalle/IndExe = 1):
su monto va a exempt_amount y no genera IVA. Por ahora sólo en guía
de despacho (DTE 52); en otro tipo de documento la API responde 422.
No disponible para emisores del facturador gratuito del SII (422).
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
line_number:
type: integer
description: >-
Número de línea del ítem. Opcional: si no viene, se usa el orden del
arreglo.
example: 1
item_total:
type: number
description: >-
Total de la línea. La API lo recalcula a partir de quantity,
unit_price y discount_percent; el valor enviado no se usa para
emitir.
example: 4050000
show_item_type:
type: string
enum:
- '01'
- '02'
description: >-
Sólo boletas (39/41) de espectáculos emitidas por cuenta de terceros
(ItemEspectaculo): "01" si la línea es la entrada, "02" si es el
valor por servicio que cobra el emisor. Obligatorio en todas las
líneas en ese caso.
nullable: true
ticket:
type: object
nullable: true
description: >-
Datos del ticket de la entrada (línea con show_item_type "01"). El
SII exige imprimirlos en la boleta.
properties:
ticket_folio:
type: integer
description: Folio del ticket, único para el evento (máximo 6 dígitos).
generated_at:
type: string
format: date-time
description: Fecha y hora de generación del ticket.
event_name:
type: string
maxLength: 80
description: Nombre del espectáculo.
ticket_type:
type: string
maxLength: 10
description: Tipo de ticket.
event_code:
type: string
maxLength: 5
description: Código asociado al evento.
event_datetime:
type: string
format: date-time
description: Fecha y hora de realización del evento.
event_place:
type: string
maxLength: 80
description: Dirección o recinto donde se realiza el evento.
event_location:
type: string
maxLength: 20
description: Sector o sección de la ubicación en el evento.
row:
type: string
maxLength: 3
nullable: true
description: Fila de la ubicación.
seat:
type: string
maxLength: 3
nullable: true
description: Asiento de la ubicación.
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 final de la mercadería
(Aduana/CodPaisDestin). No es código ISO 3166-1. Si no se envían
receiver_country_code ni receiver_nationality_code, también es el
país y la nacionalidad del receptor. Ver
/user-guide/export-countries
example: '225'
receiver_country_code:
type: string
description: >-
Código de país del SII donde está el receptor (Aduana/CodPaisRecep),
cuando es distinto del destino, por ejemplo en una triangulación.
Opcional: si no se envía, se usa destination_country_code. Misma
tabla que destination_country_code.
example: '515'
receiver_nationality_code:
type: string
description: >-
Código de país del SII de la nacionalidad del receptor
(Receptor/Extranjero/Nacionalidad). Opcional: si no se envía, se usa
receiver_country_code y, si tampoco viene, destination_country_code.
Misma tabla que destination_country_code.
example: '515'
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
sale_clause_code:
type: string
description: >-
Cláusula de venta / Incoterm (CodClauVenta del DTE). No confundir
con sale_mode_code, que es la modalidad de venta. Se acepta el
código del SII o el nombre del Incoterm: 1=CIF, 2=CFR, 3=EXW, 4=FAS,
5=FOB, 6=S/CL, 8=OTROS, 9=DDP, 10=FCA, 11=CPT, 12=CIP, 17=DAT,
18=DAP.
example: '5'
export_payment_method_code:
type: string
description: >-
Forma de pago de exportación (FmaPagExp del DTE). No es
header.payment_method, que no aplica a exportación. Se acepta el
código del SII o el nombre: 1=COB1, 2=COBRANZA, 11=ACRED, 12=CBOF,
21=S/PAGO, 32=ANTICIPO, 50=ANT/COB, 60=ANT/CRED, 80=S/PAGO/COB. Si
no se envía, se emite 21 (sin pago).
example: '11'
export_type:
type: string
description: Tipo de exportación
default: '0'
TransportData:
type: object
description: >-
Datos de transporte de la guía de despacho (DTE 52): tipo de traslado,
tipo de despacho, transportista, chofer, destino y datos de Aduana. Los
campos de transporte y destino también se aceptan en otros tipos de
documento; los de Aduana, sólo con transport_type 8 o 9. Con
timber_enabled en true se incluyen los datos de origen de la madera que
exige el SII (CONAF). Res. Ex. SII N°154 (vigente desde el 2026-11-01):
tipo de traslado, patente, RUT del transportista, chofer (o
transport_unknown_reason), destino con comuna, fecha y hora de salida y
unidad de medida en cada línea pasan a ser obligatorios en la guía;
hasta esa fecha la respuesta del batch sólo trae un aviso (warnings,
code res154_*). Con emisores del facturador gratuito del SII (MiPyme),
los datos de Aduana y el destino de la madera no están disponibles: la
API responde 422; tipo de despacho, destino, salida, llegada, patente
del carro y motivos se imprimen como texto en la primera línea del
detalle porque el formulario del SII no tiene esos campos.
properties:
transport_type:
type: string
description: >-
Tipo de traslado (IdDoc/IndTraslado). 1=Operación constituye venta,
2=Ventas por efectuar, 3=Consignaciones, 4=Entrega gratuita,
5=Traslados internos, 6=Otros traslados no venta, 7=Devolución de
mercaderías, 8=Traslado para exportación (no venta), 9=Venta para
exportación. Si no se envía, se usa 1.
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
default: '1'
example: '1'
dispatch_type:
type: string
nullable: true
description: >-
Tipo de despacho (IdDoc/TipoDespacho). 1=Por cuenta del receptor (el
cliente retira), 2=Por cuenta del emisor a instalaciones del
cliente, 3=Por cuenta del emisor a otras instalaciones. Si no se
envía, se emite 3. No se permite con transport_type 5 (422). Con
emisores del facturador gratuito del SII (MiPyme) va como texto en
la primera línea del detalle (su formulario no tiene el campo).
enum:
- '1'
- '2'
- '3'
example: '2'
transport_rut:
type: string
nullable: true
description: >-
RUT de la empresa de transporte (Transporte/RUTTrans), formato
12345678-9. Si el dígito verificador es inválido se emite igual y la
respuesta trae un aviso invalid_rut.
example: 76234567-6
transport_plate:
type: string
nullable: true
description: >-
Patente del vehículo (Transporte/Patente). Se normaliza a mayúsculas
sin guion ni espacios y queda en máximo 8 caracteres.
example: PJRL69
driver_rut:
type: string
nullable: true
description: >-
RUT del chofer (Transporte/Chofer/RUTChofer). Si el dígito
verificador es inválido se emite igual y la respuesta trae un aviso
invalid_rut. Se envía junto con driver_name, o ninguno de los dos
(422 si falta uno).
example: 12345678-5
driver_name:
type: string
nullable: true
description: >-
Nombre completo del chofer (Transporte/Chofer/NombreChofer). Se
trunca a 30 caracteres en el DTE. Se envía junto con driver_rut, o
ninguno de los dos (422 si falta uno).
example: Juan Pérez
destination_address:
type: string
nullable: true
maxLength: 70
description: >-
Dirección de destino (Transporte/DirDest). Se informa cuando el
destino es distinto de la dirección del receptor. Con emisores del
facturador gratuito del SII (MiPyme) va como texto en la primera
línea del detalle (su formulario no tiene el campo).
example: Aeropuerto Arturo Merino Benitez
destination_district:
type: string
nullable: true
maxLength: 20
description: >-
Comuna de destino (Transporte/CmnaDest). Con emisores del facturador
gratuito del SII (MiPyme) va como texto en la primera línea del
detalle (su formulario no tiene el campo).
example: Pudahuel
destination_city:
type: string
nullable: true
maxLength: 20
description: >-
Ciudad de destino (Transporte/CiudadDest). Con emisores del
facturador gratuito del SII (MiPyme) va como texto en la primera
línea del detalle (su formulario no tiene el campo).
example: Santiago
transfer_issuer_code:
type: string
nullable: true
enum:
- '1'
- '2'
- '3'
- '4'
description: >-
Quién realiza el traslado de exportación
(Emisor/GuiaExport/CdgTraslado): 1=Exportador, 2=Agente de Aduana,
3=Vendedor, 4=Contribuyente autorizado expresamente por el SII. Sólo
con transport_type 8 o 9 (422 en otro caso); obligatorio con 8 o 9
en el facturador de mercado (sin él el SII acepta la guía con reparo
HED-2-804). No disponible para emisores del facturador gratuito del
SII (422).
example: '1'
authorization_resolution_number:
type: integer
nullable: true
minimum: 1
description: >-
Número de la resolución del SII que autoriza al contribuyente a
emitir la guía de exportación (Emisor/GuiaExport/FolioAut).
Obligatorio con transfer_issuer_code 4 y no permitido con otro
código (422).
example: 1234
authorization_resolution_date:
type: string
format: date
nullable: true
description: >-
Fecha de la resolución del SII que autoriza al contribuyente
(Emisor/GuiaExport/FchAut), formato YYYY-MM-DD. Obligatoria con
transfer_issuer_code 4 y no permitida con otro código (422).
example: '2024-03-01'
departure_port_code:
type: string
nullable: true
description: >-
Puerto de embarque (Aduana/CodPtoEmbarque). Código o nombre exacto
de la tabla de puertos de Aduana del SII (ej: 992 o
AEROP.A.M.BENITEZ; 906=SAN ANTONIO, 905=VALPARAISO). Sólo con
transport_type 8 o 9 (422 en otro caso); obligatorio con 8 o 9 en el
facturador de mercado. No disponible para emisores del facturador
gratuito del SII (422).
example: '992'
arrival_port_code:
type: string
nullable: true
description: >-
Puerto de desembarque (Aduana/CodPtoDesemb). Código o nombre exacto
de la tabla de puertos de Aduana del SII (ej: 134=NEW YORK,
292=SANTOS). Sólo con transport_type 8 o 9 (422 en otro caso);
obligatorio con 8 o 9 en el facturador de mercado. No disponible
para emisores del facturador gratuito del SII (422).
example: '134'
gross_weight:
type: string
format: decimal
nullable: true
pattern: ^\d{1,10}(\.\d{1,2})?$
description: >-
Peso bruto de la carga (Aduana/PesoBruto), mayor a 0 y con hasta 2
decimales. Sólo con transport_type 8 o 9 (422 en otro caso);
obligatorio con 8 o 9 en el facturador de mercado. No disponible
para emisores del facturador gratuito del SII (422).
example: '1414.00'
gross_weight_unit_code:
type: string
nullable: true
description: >-
Unidad del peso bruto (Aduana/CodUnidPesoBruto), según la tabla de
unidades de medida de Aduana del SII (ej: 6=KN). Sólo con
transport_type 8 o 9 (422 en otro caso); obligatorio con 8 o 9 en el
facturador de mercado. No disponible para emisores del facturador
gratuito del SII (422).
example: '6'
total_packages:
type: integer
nullable: true
minimum: 1
description: >-
Total de bultos (Aduana/TotBultos), mayor a 0. Si se envía,
package_type_code es obligatorio. Sólo con transport_type 8 o 9 (422
en otro caso). No disponible para emisores del facturador gratuito
del SII (422).
example: 3
package_type_code:
type: string
nullable: true
description: >-
Tipo de bulto (Aduana/TipoBultos/CodTpoBultos), según la tabla de
tipos de bulto de Aduana del SII (ej: 22=CAJA DE CARTON).
Obligatorio si se envía total_packages. Sólo con transport_type 8 o
9 (422 en otro caso). No disponible para emisores del facturador
gratuito del SII (422).
example: '22'
timber_enabled:
type: boolean
description: >-
Si es true, la guía incluye los datos de origen de la madera para
CONAF.
default: false
example: false
comuna_rol:
type: string
nullable: true
description: Código de comuna del SII del rol del predio de origen.
example: '13101'
manzana_rol:
type: string
nullable: true
description: Manzana del rol del predio de origen.
example: '12'
predio_rol:
type: string
nullable: true
description: Predio del rol del predio de origen.
example: '345'
geo_ref_system:
type: string
nullable: true
description: 'Código del sistema de referencia geográfica (ej: 1 = WGS84).'
example: '1'
latitude:
type: string
nullable: true
description: >-
Latitud del origen de la madera, como string (normalmente con dos
decimales, según el SII).
example: '-33.45'
longitude:
type: string
nullable: true
description: >-
Longitud del origen de la madera, como string (normalmente con dos
decimales, según el SII).
example: '-70.65'
conaf_plan_code:
type: string
nullable: true
description: Código del plan de manejo forestal de CONAF.
example: PM-2024-001
trailer_plate:
type: string
nullable: true
description: >-
Patente del carro o remolque (Transporte/PatenteCarro), cuando el
vehículo lleva uno. Se normaliza igual que transport_plate:
mayúsculas, sin guion ni espacios, máximo 8 caracteres. Res. Ex. SII
N°154.
example: JK1234
departure_date:
type: string
format: date
nullable: true
description: >-
Fecha de inicio del traslado (Transporte/FchSalida), AAAA-MM-DD.
Res. Ex. SII N°154: obligatoria en la guía desde el 2026-11-01.
example: '2026-11-02'
departure_time:
type: string
nullable: true
description: >-
Hora de inicio del traslado (Transporte/HraSalida), HH:MM (también
se acepta HH:MM:SS). Res. Ex. SII N°154: obligatoria en la guía
desde el 2026-11-01.
example: '08:30'
arrival_date:
type: string
format: date
nullable: true
description: >-
Fecha estimada de llegada (Transporte/FchLlegada), AAAA-MM-DD. No
puede ser anterior a departure_date (422).
example: '2026-11-02'
transfer_reason:
type: string
maxLength: 200
description: >-
Motivo del traslado. Res. Ex. SII N°154: en un traslado que no es
venta (transport_type distinto de 1 y 9) permite omitir el precio
unitario de las líneas. Se imprime en el detalle del documento.
example: Traslado a bodega central para reposición de stock
transport_unknown_reason:
type: string
maxLength: 100
description: >-
Declaración expresa de que no se conocen los datos del transporte
(patente, RUT del transportista, chofer) y por qué. Res. Ex. SII
N°154 y nota 4 del Formato DTE 2026-02: desde el 2026-11-01 la guía
se rechaza sin patente, transportista y chofer salvo que venga esta
declaración. Se imprime en el detalle del documento.
example: El cliente retira con transporte propio no informado
destination_commune_role:
type: string
pattern: ^\d{1,6}$
description: >-
Rol predial de destino de la madera: comuna
(ManejoMadera/ComunaRolDestino). Sólo con timber_enabled en true y
emisor del facturador de mercado; Res. Ex. SII N°75 de 2024,
obligatorio desde el 2026-11-01.
example: '13101'
destination_block_role:
type: string
pattern: ^\d{1,6}$
description: >-
Rol predial de destino de la madera: manzana
(ManejoMadera/MnzRolDestino). Sólo con timber_enabled en true y
emisor del facturador de mercado.
example: '1234'
destination_property_role:
type: string
pattern: ^\d{1,6}$
description: >-
Rol predial de destino de la madera: predio
(ManejoMadera/PrdRolDestino). Sólo con timber_enabled en true y
emisor del facturador de mercado.
example: '56'
work_execution_notice:
type: string
maxLength: 40
description: >-
Número del aviso de ejecución de faena de CONAF
(ManejoMadera/AvisoEjecucionFaena). Sólo con timber_enabled en true
y emisor del facturador de mercado.
example: AEF-2026-0457
destination_latitude:
type: string
maxLength: 30
description: >-
Latitud del destino de la madera
(ManejoMadera/LatitudDestinoMadera). Sólo con timber_enabled en true
y emisor del facturador de mercado.
example: '-36.82'
destination_longitude:
type: string
maxLength: 30
description: >-
Longitud del destino de la madera
(ManejoMadera/LongitudDestinoMadera). Sólo con timber_enabled en
true y emisor del facturador de mercado.
example: '-73.05'
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)
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.