# Emitir DTE

`POST /api/v1/billing/dte`

Emite un Documento Tributario Electrónico. Soporta los 12 tipos SII:
facturas (33, 34), boletas (39, 41), liquidación factura (43), factura
de compra (46), guía de despacho (52), notas de débito/crédito (56, 61)
y documentos de exportación (110, 111, 112).

Flujo: validación, asignación de folio desde el CAF activo, generación
del XML, timbre electrónico (TED), firma digital y persistencia. La
respuesta `201` retorna inmediatamente con estado `firmado`; el envío
al SII ocurre de forma **asíncrona**. Use webhooks o polling en
`GET /api/v1/billing/dte/{id}` para seguir el estado.

Requiere el header `Idempotency-Key` (UUID). Un reintento con la misma
key retorna la respuesta original con `X-Idempotency-Replay: true`.

> **Beta privada**: la emisión y las escrituras vía API key están en
> beta privada (solicitar acceso: hola@simplo.cl); las API keys hoy
> operan en modo lectura.

- Autenticación: header `X-Api-Key: sk_simplo_...` (o `Authorization: Bearer <jwt>` para sesiones de la plataforma).
- operationId: `emitirDTE` — contrato completo en https://docs.simplo.cl/openapi.yaml
- Versión HTML: https://docs.simplo.cl/api/operations/emitirdte/

## Parámetros

| Nombre | En | Tipo | Requerido | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string (uuid) | sí | UUID único para garantizar idempotencia. |

## Request body (application/json)

Schema: `EmitirDTERequest`

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tipo_dte` | integer (33 \| 34 \| 39 \| 41 \| 43 \| 46 \| 52 \| 56 \| 61 \| 110 \| 111 \| 112) | sí | Código SII del tipo de Documento Tributario Electrónico (33 factura, 39 boleta, 52 guía de despacho, 56/61 notas, 110-112 exportación). |
| `fecha_emision` | string (date) | no | Fecha de emisión tributaria del DTE en formato YYYY-MM-DD. |
| `receptor` | Receptor | sí |  |
| `detalle` | LineaDetalle[] | sí |  |
| `comisiones` | ComisionDTE[] | no | Comisiones de Liquidación Factura (tipo 43) |
| `impuestos_retenciones` | ImpuestoRetencion[] | no | Impuestos retenidos en Totales/ImptoReten. |
| `referencias` | Referencia[] | no | Requerido para notas de crédito (61), notas de débito (56), y exportación (111, 112) |
| `ind_traslado` | integer (1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9) | no | Tipo de traslado para Guía de Despacho (tipo 52): - 1: Operación constituye venta - 2: Venta por efectuar - 3: Consignación - 4: Entrega gratuita - 5: Traslado interno - 6: Otros traslados no venta - 7: Guía de devolución - 8: Traslado para exportación (no venta) - 9: Venta para exportación |
| `tipo_despacho` | integer (1 \| 2 \| 3) | no | Modo de despacho para Guía de Despacho (tipo 52): - 1: Despacho por cuenta del comprador - 2: Despacho por cuenta del emisor a instalaciones del comprador - 3: Despacho por cuenta del emisor a otras instalaciones |
| `ind_servicio` | integer (1 \| 2 \| 3 \| 4 \| 5 \| 6) | no | Indicador de servicio: - 1: Facturación de servicios periódicos domiciliarios - 2: Facturación de otros servicios periódicos - 3: Factura de servicio; en exportación, servicio calificado por Aduana - 4: Factura de exportación por servicios de hotelería - 5: Factura de exportación por transporte terrestre internacional - 6: Factura de exportación por servicios prestados y utilizados totalmente en el extranjero |
| `descuentos_globales` | DscRcgGlobal[] | no | Descuentos y recargos globales aplicados sobre el neto |
| `auto_send` | boolean | no | Cuando es `true` (default), el DTE se encola para envío individual al SII inmediatamente después de emitirse. |
| `export_data` | ExportData | no | Datos de exportación para tipos 110, 111, 112 |
| `metadata` | object | no | Metadata extensible definida por el integrador |

### Receptor

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `rut` | string | sí | RUT del receptor con dígito verificador |
| `razon_social` | string | sí |  |
| `giro` | string | no |  |
| `direccion` | string | no |  |
| `comuna` | string | no |  |
| `ciudad` | string | no |  |

### LineaDetalle

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tipo_doc_liq` | string | no | Tipo de documento liquidado. |
| `ind_exe` | integer (1) | no | Marca una línea como exenta cuando el tipo de DTE lo requiere. |
| `cod_imp_adic` | integer | no | Código de impuesto adicional por línea. |
| `nombre` | string | sí | Nombre del item o servicio |
| `dsc_item` | string | no | Descripción adicional de la línea. |
| `cantidad` | number | no | Cantidad (soporta decimales para unidades fraccionarias). |
| `unidad` | string | no | Unidad de medida opcional del item, por ejemplo `UN`, `Kg` o `Lt` |
| `precio` | integer | no | Precio unitario en pesos chilenos. |
| `monto_item` | integer | no | Monto total de la línea. |
| `descuento_pct` | number | no | Descuento porcentual sobre la línea (0-100) |
| `recargo_pct` | number | no | Recargo porcentual sobre la línea (0-100) |

### ComisionDTE

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tipo_movim` | string (C \| O) | sí | `C` para cobro/comisión positiva, `O` para otros movimientos o rebajas. |
| `glosa` | string | sí |  |
| `tasa_comision` | number | no |  |
| `val_com_neto` | integer | sí |  |
| `val_com_exe` | integer | sí |  |
| `val_com_iva` | integer | no |  |

### ImpuestoRetencion

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tipo_imp` | integer | sí | Código SII del impuesto retenido. |
| `tasa_imp` | number | no | Tasa usada para calcular el monto retenido cuando `monto_imp` no viene informado. |
| `monto_imp` | integer | no | Monto retenido explícito. |

### Referencia

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tipo_doc_ref` | integer (33 \| 34 \| 39 \| 41 \| 43 \| 46 \| 52 \| 56 \| 61 \| 110 \| 111 \| 112) \| string | sí |  |
| `folio_ref` | integer | sí | Folio del documento referenciado |
| `fecha_ref` | string (date) | sí | Fecha del documento referenciado |
| `codigo_ref` | integer (1 \| 2 \| 3) | no | Código de referencia SII: - 1: Anula documento referenciado - 2: Corrige texto del documento referenciado - 3: Corrige montos del documento referenciado |
| `razon_ref` | string | sí | Razón de la referencia |

### DscRcgGlobal

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `nro_lin_dr` | integer | no | Número de línea del descuento/recargo |
| `tpo_mov` | string (D \| R) | sí | D = descuento, R = recargo |
| `tpo_valor` | string (% \| $) | sí | % = porcentaje, $ = monto fijo |
| `valor_dr` | number | sí | Valor del descuento/recargo. |
| `glosa_dr` | string | no | Glosa descriptiva |
| `ind_exe_dr` | integer (1 \| 2) | no | 1 = descuento/recargo global no afecto; 2 = no facturable. |

### ExportData

Datos de exportación para tipos 110, 111, 112

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `tpo_moneda` | string | sí | Código de moneda según tabla Aduanas (e.g., "DOLAR USA", "EURO") |
| `tpo_cambio` | number | no | Tipo de cambio fijado por el Banco Central para OtraMoneda cuando se informa |
| `mnt_export` | number | no | Monto auxiliar de compatibilidad para OtraMoneda |
| `nacionalidad` | string | no | Código o nombre de país para Receptor/Extranjero/Nacionalidad |
| `num_id` | string | no | Número de identificación del receptor extranjero/turista para Exportaciones/Extranjero/NumId |
| `tipo_doc_id` | integer | no | No usar en tipos 110, 111, 112; el XSD de Exportaciones no permite TipoDocID dentro de Receptor/Extranjero |
| `forma_pago_exp` | integer | no | Código Aduana de forma de pago de exportación |
| `modalidad_venta` | integer | no | Código Aduana de modalidad de venta |
| `clausula_venta` | string | no | Cláusula Aduana, acepta código numérico o etiqueta conocida como CIF, CFR, FOB |
| `total_clausula` | number | no | Total de la cláusula de venta |
| `via_transporte` | integer | no | Código Aduana de vía de transporte |
| `puerto_embarque` | string | no | Código o nombre de puerto de embarque |
| `puerto_desembarque` | string | no | Código o nombre de puerto de desembarque |
| `tara` | integer | no | Tara |
| `unidad_tara` | integer | no | Código Aduana de unidad de medida de tara |
| `peso_bruto` | number | no | Peso bruto |
| `unidad_peso_bruto` | integer | no | Código Aduana de unidad de peso bruto |
| `peso_neto` | number | no | Peso neto |
| `unidad_peso_neto` | integer | no | Código Aduana de unidad de peso neto |
| `tipo_bulto` | string | no | Tipo de bulto, acepta código numérico o etiqueta conocida |
| `total_bultos` | integer | no | Total de bultos |
| `marcas` | string | no | Marcas informadas dentro de TipoBultos cuando la operación lo exige |
| `mnt_flete` | number | no | Monto de flete en moneda de venta |
| `mnt_seguro` | number | no | Monto de seguro en moneda de venta |
| `pais_recep` | string | no | Código o nombre de país receptor según tabla Aduanas |
| `pais_dest` | string | no | Código o nombre de país destino según tabla Aduanas |

## Ejemplo (curl)

```sh
curl -X POST "https://api.simplo.cl/api/v1/billing/dte" \
  -H "X-Api-Key: $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tipo_dte": 33,
    "fecha_emision": "2026-08-01",
    "receptor": {
      "rut": "76543210-K",
      "razon_social": "Empresa Ejemplo SpA",
      "giro": "Desarrollo de software",
      "direccion": "Av. Providencia 1234",
      "comuna": "Providencia",
      "ciudad": "Santiago"
    },
    "detalle": [
      {
        "nombre": "Servicio de consultoria TI",
        "cantidad": 10,
        "unidad": "UN",
        "precio": 50000
      }
    ]
  }'
```

## Respuestas

### 201 — DTE emitido exitosamente

Schema: `EmitirDTEResponse`

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `id` | string (uuid) | sí |  |
| `folio` | integer | sí |  |
| `tipo_dte` | integer (33 \| 34 \| 39 \| 41 \| 43 \| 46 \| 52 \| 56 \| 61 \| 110 \| 111 \| 112) | sí | Código SII del tipo de Documento Tributario Electrónico (33 factura, 39 boleta, 52 guía de despacho, 56/61 notas, 110-112 exportación). |
| `estado` | string (borrador \| generado \| firmado \| enviando \| procesando \| aceptado \| rechazado \| con_reparos) | sí | Estado del DTE en su ciclo de vida. |
| `monto_total` | integer | sí | Monto total en pesos chilenos |
| `created_at` | string (date-time) | sí |  |

### 400 — Error de validación

Schema: `ErrorResponse`

### 401 — Token o API key inválido o ausente

Schema: `ErrorResponse`

### 409 — Conflicto.

Schema: `ErrorResponse`

### 422 — Idempotency-Key reutilizada con un body de request diferente al original (código `IDEMPOTENCY_BODY_MISMATCH`)

Schema: `ErrorResponse`

### 429 — Rate limit excedido

Schema: `ErrorResponse`

### 503 — Servicio de idempotencia temporalmente no disponible.

Schema: `ErrorResponse`