---
title: "Integración para la emisión de DTE"
description: "Sigue los pasos para emitir documentos tributarios desde tu software usando API Gayeway."
type: "academy"
category: "course"
tags: [api-gateway-legacy]
authors: [Anonymous]
date: "2026-08-27"
last_update: "2026-08-21"
time_minutes: 54
draft: false
unlisted: false
image: "https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/integracion.jpg"
url: "https://www.stage.apigateway.cl/academy/integracion-para-la-emision-de-dte"
---

# Integración para la emisión de DTE




---

## Introducción



---

### ¿Qué es un DTE?

Aprende qué son los Documentos Tributarios Electrónicos, su marco legal en Chile, ventajas y obligatoriedad

# ¿Qué es un DTE?

Un **Documento Tributario Electrónico (DTE)** es la versión digital de los documentos tributarios tradicionales en papel, que tiene la misma validez legal y tributaria que su contraparte física.

Los DTEs son documentos generados, firmados y transmitidos electrónicamente, que cumplen con los estándares técnicos y normativos establecidos por el Servicio de Impuestos Internos (SII).

### Características Principales

1. **Formato XML**: Los DTEs se estructuran en formato XML (eXtensible Markup Language)
2. **Firma Electrónica**: Cada documento está firmado digitalmente, garantizando su autenticidad
3. **Folio Único**: Cada DTE tiene un número de folio autorizado por el SII
4. **Trazabilidad**: Todo el ciclo de vida del documento es auditable
5. **Validez Legal**: Tiene el mismo valor tributario que un documento en papel

### Componentes de un DTE


- Datos del Emisor
- Datos del Receptor
- Detalle de Productos/Servicios
- Totales e Impuestos
- Firma Electrónica
- Timbre Electrónico SII

---

## Marco Legal en Chile

### Normativa Principal

La facturación electrónica en Chile está regulada por:

1. **[Ley N° 20.727 (2014)](https://www.sii.cl/factura_electronica/ley/ley_fe_20727.htm)**
   - Establece la obligatoriedad gradual de la emisión electrónica
   - Define los documentos tributarios electrónicos
   - Otorga facultades al SII para su implementación

2. **[Resolución Exenta SII N° 18 (2003)](https://www.sii.cl/preguntas_frecuentes/factura_electronica/001_003_3429.htm#:~:text=Resoluci%C3%B3n%20N%C2%B018%20de,en%20los%20casos%20que%20indica.)**
   - Primera normativa que autorizó la factura electrónica
   - Estableció los estándares técnicos iniciales

### Documentos Regulados

Los documentos tributarios que pueden emitirse electrónicamente incluyen:

- Facturas (afectas y exentas)
- Boletas (afectas y exentas)
- Notas de Crédito y Débito
- Guías de Despacho
- Facturas de Compra
- Liquidaciones Factura
- Documentos de Exportación

---

## Ventajas de la Facturación Electrónica

### Para las Empresas

1. **Reducción de Costos**
2. **Eficiencia Operacional**
3. **Mejor Control y Gestión**
4. **Sustentabilidad**

### Para los Clientes

1. **Recepción Inmediata**: Documentos en el correo al instante
2. **Almacenamiento Digital**: Sin pérdida de documentos físicos
3. **Validación en Línea**: Verificación de autenticidad en el SII
4. **Gestión Simplificada**: Organización digital de documentos

### Para el Estado

1. **Mayor Recaudación**: Reducción de la evasión fiscal
2. **Fiscalización Eficiente**: Control en tiempo real
3. **Información Actualizada**: Datos económicos precisos
4. **Modernización**: Digitalización del sistema tributario

---

## Conceptos Clave para Recordar

- Un DTE es la versión electrónica de los documentos tributarios tradicionales
- Tiene la misma validez legal que un documento en papel
- Está firmado electrónicamente y validado por el SII
- Es obligatorio para todos los contribuyentes en Chile

## Recurso Adicional

- [Curso en linea SII](https://capacita.sii.cl/)


    
---

### Tipos de Documentos Tributarios Electrónicos

Conoce todos los tipos de DTEs disponibles en Chile, sus características y casos de uso

# Tipos de Documentos Tributarios Electrónicos

En el mundo de la facturación electrónica, no todas las transacciones comerciales se documentan de la misma manera. El SII ha definido diferentes tipos de documentos para cubrir todas las situaciones posibles del comercio.

**¿Por qué existen diferentes tipos?** Cada documento tiene un propósito tributario específico y genera diferentes obligaciones tanto para el emisor como para el receptor.

---

## 1. Documentos de Venta

Los documentos de venta son los más comunes en el día a día empresarial. La elección correcta depende de dos factores principales:
- **¿Quién es tu cliente?** (Empresa o consumidor final)
- **¿La operación tiene IVA?** (Afecta o exenta)

### Tipos de Documentos de Venta

| Código | Tipo | Descripción | Características | Cuándo Usar |
|--------|------|-------------|-----------------|-------------|
| **33** | **Factura Electrónica** | Documento tributario que respalda operaciones entre contribuyentes con derecho a crédito fiscal | • IVA desglosado<br>• Permite crédito fiscal<br>• Requiere datos completos del receptor | • Ventas B2B<br>• Cliente necesita recuperar IVA<br>• Operaciones gravadas |
| **34** | **Factura Exenta** | Documento para operaciones no gravadas con IVA | • Sin IVA<br>• Para servicios/productos exentos<br>• Formato similar a factura afecta | • Servicios de salud<br>• Educación<br>• Arriendos habitacionales |
| **39** | **Boleta Electrónica** | Documento simplificado para consumidores finales | • IVA incluido<br>• Datos comprador opcionales<br>• Emisión diaria obligatoria | • Ventas al detalle<br>• Servicios a personas<br>• Ventas B2C |
| **41** | **Boleta Exenta** | Boleta para operaciones exentas | • Sin IVA<br>• Para consumidor final<br>• Productos exentos | • Algunos servicios de salud o actividades culturales. |

### Ejemplo Práctico

**Situación**: Tienes una tienda de computadores.
- Si vendes a una **empresa**: Emites Factura (33) - El cliente puede recuperar el IVA
- Si vendes a una **persona natural**: Emites Boleta (39) - El IVA va incluido en el precio

![Árbol de decisión de Boletas y Facturas](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/factura-boleta.png)

---

## 2. Documentos de Compra

A veces necesitas documentar compras cuando el vendedor no puede emitir facturas. Aquí entran los documentos de compra y traslado.

### Tipos de Documentos de Compra

| Código | Tipo | Descripción | Características | Cuándo Usar |
|--------|------|-------------|-----------------|-------------|
| **46** | **Factura de Compra** | Emitida por comprador cuando vendedor no puede facturar | • Emisor es el comprador<br>• Genera retención IVA<br>• Para productores sin inicio actividades | • Compra a agricultores<br>• Compra a recolectores<br>• Vendedor sin facturación |
| **52** | **Guía de Despacho** | Ampara traslado de mercaderías | • Sin efecto tributario directo<br>• Puede generar factura posterior<br>• Obligatoria para transporte | • Traslado entre bodegas<br>• Envío antes de facturar<br>• Exhibición o demostración |

### Tipos de Traslado en Guía de Despacho

La Guía de Despacho (52) es especial porque debe indicar el **motivo del traslado**:

| Tipo | Código | Uso | Ejemplo |
|------|--------|-----|---------|
| **Operación constituye venta** | 1 | Mercadería que se facturará posteriormente | Envías productos hoy, facturas a fin de mes |
| **Ventas por efectuar** | 2 | Mercadería que se venderá en el futuro | Productos en consignación para venta |
| **Consignaciones** | 3 | Para venta por terceros | Dejas productos en otra tienda para vender |
| **Entrega gratuita** | 4 | Donaciones o regalos | Muestras gratuitas o donaciones |
| **Traslados internos** | 5 | Entre sucursales de la misma empresa | De bodega central a tienda |
| **Otros traslados no venta** | 6 | Traslados que no son venta | Reparaciones, mantenimiento |
| **Guía de devolución** | 7 | Retorno de mercaderías | Cliente devuelve productos |
| **Traslado para exportación (no venta)** | 8 | Mercadería que se exportará | Productos para exportación |
| **Venta para exportación** | 9 | Venta directa al extranjero | Venta de productos al exterior |

### Caso de Uso

**Situación**: Compras verduras a un pequeño agricultor sin inicio de actividades.
- **Documento a usar**: Factura de Compra (46)
- **Importante**: Debes retener el IVA y pagarlo al SII

---

## 3. Notas de Crédito y Débito

¿Qué pasa cuando necesitas corregir un documento ya emitido? No puedes modificarlo, pero sí puedes emitir notas de ajuste.

### Tipos de Notas

| Código | Tipo | Descripción | Efecto | Cuándo Usar |
|--------|------|-------------|--------|-------------|
| **61** | **Nota de Crédito** | Anula total o parcialmente facturas/boletas | **Disminuye** el monto cobrado | • Anulación ventas<br>• Descuentos post-venta<br>• Devoluciones<br>• Corrección errores |
| **56** | **Nota de Débito** | Aumenta valor de factura emitida | **Aumenta** el monto cobrado | • Intereses por mora<br>• Diferencias de precio<br>• Gastos adicionales |

### Regla de Oro

> **Nota de Crédito** = Devolver dinero al cliente (↓)
> **Nota de Débito** = Cobrar más al cliente (↑)

### Ejemplo Práctico

**Caso 1**: Emitiste una factura por $100.000 pero era $80.000
- **Solución**: Nota de Crédito por $20.000

**Caso 2**: Olvidaste cobrar el flete de $15.000
- **Solución**: Nota de Débito por $15.000

![Árbol de decisión de Notas de Crédito y Débito](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/notas-credito-debito.png)

---

## 4. Documentos de Exportación

Si tu empresa vende al extranjero, necesitas documentos especiales que no tienen IVA.

### Documentos para Exportación

| Código | Tipo | Para qué sirve |
|--------|------|----------------|
| **110** | **Factura Exportación** | Venta de productos o servicios al extranjero |
| **111** | **Nota Crédito Exportación** | Anular o disminuir una factura de exportación |
| **112** | **Nota Débito Exportación** | Aumentar el valor de una factura de exportación |

**Características especiales**:
- Valores en moneda extranjera (generalmente USD)
- Sin IVA (exportaciones están exentas)
- Requieren información aduanera adicional

![Árbol de decisión de Documentos de Exportación](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/exportacion.png)

---

## 5. Otros Documentos

### Documentos Especiales

| Código | Tipo | Descripción | Característica Principal |
|--------|------|-------------|-------------------------|
| **43** | **Liquidación Factura** | Documento usado en contratos de consignación donde un consignatario vende bienes por cuenta de un consignante | Empresa emite, retiene y paga impuestos del vendedor |

**¿Cuándo se usa?**
- En ventas por consignación.
- El consignatario (quien vende) emite el documento al consignante (dueño de los productos).
- Detalla las ventas realizadas y cobra su comisión.

**Ejemplo típico**:
- Una tienda (consignatario) vende productos de un proveedor (consignante)
- Al final del período, la tienda emite una Liquidación Factura que:
  - Detalla todo lo vendido
  - Calcula la comisión correspondiente
  - Liquida el monto a pagar al proveedor

![Árbol de decisión de Liquidación Factura](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/liquidacion-factura.png)

---

## Relaciones entre Documentos

Es importante entender que algunos documentos pueden generar otros:

| Documento Original | Puede generar | ¿Por qué? |
|-------------------|---------------|-----------|
| Guía de Despacho (52) | Factura (33/34) | Formalizar la venta después del despacho |
| Factura (33/34) | Nota Crédito (61) | Anular o corregir |
| Factura (33/34) | Nota Débito (56) | Cobrar adicionales |
| Boleta (39/41) | Nota Crédito (61) | Solo casos especiales con RUT |

---


    
---

### Documentos Soportados por API Gateway

Conoce qué DTEs puedes emitir con API Gateway y las consideraciones especiales

# Documentos Soportados por API Gateway

API Gateway soporta la gran mayoría de los Documentos Tributarios Electrónicos definidos por el SII. Esto permite que las empresas puedan digitalizar casi todos sus procesos de facturación a través de nuestra plataforma.

En esta lección veremos qué documentos están disponibles, cuáles son sus características especiales en la implementación y qué consideraciones debes tener al momento de integrarlos.

---

## Documentos Disponibles en API Gateway

### Documentos de Venta

| Código | Documento | Estado |
|--------|-----------|---------|
| **33** | Factura Electrónica | ✅ Disponible |
| **34** | Factura Exenta | ✅ Disponible |
| **39** | Boleta Electrónica | ✅ Disponible |
| **41** | Boleta Exenta | ✅ Disponible |

### Documentos de Compra

| Código | Documento | Estado |
|--------|-----------|---------|
| **46** | Factura de Compra | ✅ Disponible |
| **52** | Guía de Despacho | ✅ Disponible |

### Notas de Ajuste

| Código | Documento | Estado |
|--------|-----------|---------|
| **56** | Nota de Débito | ✅ Disponible |
| **61** | Nota de Crédito | ✅ Disponible |

### Documentos de Exportación

| Código | Documento | Estado |
|--------|-----------|---------|
| **110** | Factura Exportación | ✅ Disponible |
| **111** | NC Exportación | ✅ Disponible |
| **112** | ND Exportación | ✅ Disponible |

### Documentos NO Disponibles

| Código | Documento | Estado | Observación |
|--------|-----------|---------|-------------|
| **43** | Liquidación Factura | ❌ No disponible | Único documento no soportado actualmente |


    
---

### Flujo General de Emisión de un DTE

Comprende el proceso completo de emisión de un documento tributario electrónico

# Flujo General de Emisión de un DTE

La emisión de un Documento Tributario Electrónico no es solo generar un XML. Es un proceso que involucra múltiples pasos, validaciones y actores. En esta lección veremos el flujo completo desde que se origina la necesidad del documento hasta que llega al receptor.

---

## Visión General del Proceso

El proceso de emisión de un DTE se puede dividir en 4 grandes etapas:

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   GENERAR   │ --> │   ENVIAR    │ --> │  CONSULTAR  │ --> │ DISTRIBUIR  │
│     XML     │     │   AL SII    │     │   ESTADO    │     │     PDF     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
```

---

## Paso 1: Generar XML del DTE

### ¿Qué sucede en este paso?

1. **Tu sistema** envía los datos del documento a API Gateway
2. **API Gateway** valida y normaliza la información
3. Se genera el XML según el formato del SII
4. Se aplica la firma electrónica

### Datos Requeridos

```json
{
  "auth": {
    "cert": {
      "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
      "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
    }
  },
  "dte": {
    "Encabezado": { },
    "Detalle": [ ],
    "DscRcgGlobal": [ ]  // Opcional
  },
  "resolucion": {
    "fecha": "2019-12-23",
    "numero": 0
  },
  "caf": "CAF en base64"
}
```

### Respuesta

```json
{
  "dte": "XML solo del DTE en base64",
  "sii": "XML para enviar al SII en base64",
  "receptor": "XML para el receptor en base64"
}
```

---

## Paso 2: Enviar XML al SII

### ¿Qué sucede en este paso?

1. Se toma el XML firmado (campo `sii` de la respuesta anterior)
2. Se envía al servidor del SII
3. El SII valida el documento
4. Retorna un Track ID para seguimiento

### Solicitud

```json
{
  "auth": {
    "cert": {
      "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
      "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
    }
  },
  "emisor": "76192083-9",
  "xml": "XML del campo 'sii' en base64"
}
```

### Respuesta

```json
{
  "track_id": 4753411374,
  "certificacion": 0
}
```

### Consideraciones

- **Timeout recomendado**: 30 segundos
- **Reintentos**: Hasta 3 veces con espera exponencial
- **Contingencia**: Si falla, almacenar localmente

---

## Paso 3: Consultar Estado del Envío

### ¿Qué sucede en este paso?

1. Con el Track ID consultas el estado del procesamiento
2. El SII puede tardar desde segundos hasta minutos
3. Obtienes el estado final del documento

### Estados Posibles

Los estados principales que retorna el SII son:

| Estado | Descripción | Acción Requerida |
|--------|-------------|------------------|
| **EPR - En Proceso** | El SII está procesando el envío | Esperar y consultar más tarde |
| **DOK - Documento Recibido** | Documento aceptado sin reparos | Continuar con el proceso |
| **DNK - Documento Recibido con Reparos** | Aceptado pero con observaciones | Revisar los reparos detallados |
| **RCH - Rechazado por Error en Schema** | Error en la estructura XML | Corregir estructura y reenviar |
| **RCT - Rechazado por Error en Caratula** | Error en datos del envío | Revisar carátula del envío |
| **RCF - Rechazado por Error en Firma** | Problema con firma electrónica | Verificar certificado digital |
| **SOK - Schema Validado** | Primera validación exitosa | Esperar validación completa |

### Estados Específicos de Rechazo

Cuando un documento es rechazado, el campo `revision_detalle` puede contener:

- **Error en RUT**: RUT del emisor o receptor inválido
- **Error en Folios**: Folio ya utilizado o fuera de rango
- **Error en Montos**: Diferencias en cálculos de IVA o totales
- **Error en Fechas**: Fecha de emisión fuera de plazo
- **Error en Referencias**: Referencias a documentos inválidas (para NC/ND)

### Solicitud para Consulta

```json
{
  "auth": {
    "cert": {
      "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
      "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
    }
  },
  "emisor": "76192083-9",
  "track_id": "4753411374",
  "dte": "33",
  "folio": "1234567890"
}
```

### Estrategia de Consulta

```
Intento 1: Inmediato
Intento 2: +5 segundos
Intento 3: +15 segundos
Intento 4: +30 segundos
Intento 5+: Cada 60 segundos (máximo 24 horas)
```

---

## Paso 4: Generar y Distribuir PDF (Opcional)

### ¿Qué sucede en este paso?

1. Con el XML aceptado, generas la representación visual
2. El PDF incluye el timbre electrónico del SII
3. Se envía al receptor y se almacena

### Formatos Disponibles

| Formato | Uso | Características |
|---------|-----|-----------------|
| `estandar` | General | Diseño LibreDTE |
| `general` | Empresas | Diseño SASCO SpA |
| `servicios_basicos` | Utilities | Con gráficos de consumo |
| `papelContinuo` | POS | 57, 75, 80 o 110mm |

---

## Manejo de Contingencias

### Si el SII no responde

```
1. Guardar XML localmente
2. Asignar número de folio
3. Intentar envío cada 30 minutos
4. Máximo 72 horas para enviar
```

### Si el documento es rechazado

```
1. Identificar el error específico
2. Corregir los datos
3. Generar nuevo XML
4. Usar nuevo folio (no reutilizar)
5. Reenviar al SII
```

### Errores Comunes

El SII puede rechazar documentos por diversas razones:

| Tipo de Error | Descripción | Solución |
|---------------|-------------|----------|
| **RUT inválido** | RUT del receptor no válido o no existe | Verificar RUT del receptor |
| **CAF inválido** | Problemas con el CAF o folios | Verificar CAF vigente |
| **Firma inválida** | Error en la firma electrónica | Revisar certificado digital |
| **Montos incorrectos** | Cálculos de IVA o totales erróneos | Revisar cálculos |
| **Fecha inválida** | Fecha fuera de rango permitido | Verificar fecha de emisión |

> [!INFO] Importante
>
>El SII proporciona mensajes de error detallados en la respuesta. Siempre revisa el campo `revision_detalle` para obtener la descripción exacta del problema.


    
---

### Diagrama General de Emisión de un DTE

Comprende el proceso completo de emisión de un documento tributario electrónico

# Diagrama General de Emisión de un DTE

El siguiente diagrama general de emisión de un DTE, muestra el proceso completo de emisión de un documento tributario electrónico.


### Parte 1 del diagrama:


![Parte 1 del diagrama](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/diagrama-general-emision-1.png)


### Parte 2 del diagrama:


![Parte 2 del diagrama](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/diagrama-general-emision-2.png)


> [!NOTE] NOTA
>
> Para descargar el diagrama completo visualiza la sección de attachments.


    
---

### Requisitos de Emisión

Conoce todos los requisitos necesarios para emitir documentos tributarios electrónicos en Chile

# Requisitos de Emisión

Antes de emitir tu primer documento tributario electrónico, debes cumplir con una serie de requisitos establecidos por el SII. Estos requisitos aseguran que tu empresa está habilitada para operar en el sistema de facturación electrónica y que los documentos emitidos tendrán validez tributaria.

---

## Lista de Requisitos

Para emitir DTEs necesitas cumplir con los siguientes requisitos, de manera obligatoria:

| Requisito | Descripción |
|-----------|-------------|
| **Inicio de Actividades** | Estar registrado como contribuyente en el SII |
| **Resolución de Autorización** | Autorización específica para emitir DTEs |
| **Certificado Digital** | Firma electrónica vigente |
| **CAF (Código de Autorización de Folios)** | Folios autorizados para cada tipo de documento |
| **Representante Legal** | Con facultades para actuar ante el SII |
| **Domicilio Tributario** | Dirección registrada y actualizada |

---

## 1. Inicio de Actividades

### ¿Qué es?

El inicio de actividades es el trámite mediante el cual informas al SII que comenzarás a desarrollar actividades económicas que generan obligaciones tributarias.

### ¿Quién debe hacerlo?

- Personas naturales con actividades comerciales
- Empresas (sociedades, EIRL, SpA, etc.)
- Cualquier entidad que realice actividades gravadas

> [!INFO] Importante
>
> El inicio de actividades debe estar vigente y con la actividad económica correcta para emitir DTEs relacionados con tu giro.

---

## 2. Resolución de Autorización

### ¿Qué es?

Es la autorización formal del SII que te habilita para emitir documentos tributarios electrónicos en un Software de Mercado. Sin esta resolución, no puedes emitir DTEs válidos vía API Gateway.

### ¿Cómo se si tengo la resolución de autorización?

Puedes verificar si tienes la resolución de autorización en el [Portal de Autorizaciones](https://palena.sii.cl/cvc/dte/ee_empresas_dte.html).

#### Interpretación del Número de Resolución

El tipo de autorización se define por el **N° de resolución**, con excepción de las boletas electrónicas:

| N° Resolución | Significado | Requiere Certificación |
|---------------|-------------|------------------------|
| **99** | Afiliado al SII (sistema oficial) | **SÍ** - Están obligados a usar el sistema del SII |
| **80** | Software de Mercado | **SÍ** - Pueden usar software de terceros |
| **Otros números** | Casos especiales | Consultar con el SII |

> [!INFO] Importante
>
> Para software de mercado pueden existir varias resoluciones diferentes, no solo la 80.

#### Casos Especiales para Boletas Electrónicas

Las boletas electrónicas tienen reglas especiales **independientes del número de resolución**:

**Caso que SÍ requiere certificación:**
![Boleta que requiere certificación](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/boleta-requiere-certificacion.png)

**Caso que NO requiere certificación:**
![Boleta que no requiere certificación](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/boleta-no-requiere-certificacion.png)

**Caso que NO aparece el código 890 NO requiere certificación:**
![Boleta sin código 890](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/boleta-sin-codigo-890.png)

#### Ejemplos de Interpretación

**Ejemplo 1**: Resolución 99
- **Significado**: Afiliado al SII
- **Requiere certificación**: SÍ
- **Explicación**: Debes usar el sistema oficial del SII

**Ejemplo 2**: Resolución 80
- **Significado**: Software de Mercado
- **Requiere certificación**: SÍ
- **Explicación**: Puedes usar software de terceros como API Gateway

### ¿Cómo obtener la certificación de documentos?

Tienes dos opciones:

1. Servicio de Certificación (Recomendado)
   - Puedes solicitar este servicio en [Certificación LibreDTE](https://www.libredte.cl/certificacion-dte#cotizar).
   - Proceso guiado por expertos

2. Hacerlo por tu cuenta
   - Puedes realizarlo tú mismo siguiendo el curso de LibreDTE: [Certificación LibreDTE](https://www.libredte.cl/academy/certificacion-dte)
   - Esta opción no posee soporte.
   - Requiere conocimientos previos.

---

## 3. Certificado Digital

### ¿Qué es?

Es tu identidad electrónica que permite firmar digitalmente los documentos tributarios, garantizando su autenticidad y no repudio.

### Tipos de certificados

| Tipo | Uso |
|------|-----|
| **Persona Natural** | Individual |
| **Representante Legal** | En nombre de empresa |
| **Empresa** | Sello empresa |
| **Servidor** | Automatización |

### ¿Cómo obtenerlo?

1. **Elegir proveedor** autorizado
2. **Validar identidad** (presencial o por video)
3. **Pagar** el certificado
4. **Descargar** archivo .pfx o .p12
5. **Respaldar** en lugar seguro

> [!TIP]
>
> Guarda siempre una copia de respaldo de tu certificado y su contraseña en un lugar seguro.

---

## 4. CAF (Código de Autorización de Folios)

### ¿Qué es?

El CAF es un archivo XML firmado por el SII que contiene un rango de folios autorizados para emitir un tipo específico de documento.

### Características del CAF

- **Específico por tipo**: Necesitas un CAF para cada tipo de DTE
- **Rango limitado**: Contiene desde folio X hasta folio Y
- **No reutilizable**: Cada folio se usa una sola vez
- **Archivo XML**: Firmado digitalmente por el SII

### ¿Cómo solicitar CAF?

1. **Ingresar a www.sii.cl**
2. **Ir a**:
   - [Ambiente de Certificación y Prueba](https://www.sii.cl/factura_electronica/factura_mercado/menu_certificacion.html)
   - [Ambiente de Producción](https://palena.sii.cl/dte/menu.html)
3. **Seleccionar**:
   - Tipo de documento
   - Cantidad de folios
   - Sucursal (si aplica)
4. **Descargar** archivo CAF.xml

### Ejemplo de estructura CAF

```xml
<AUTORIZACION>
    <CAF version="1.0">
        <DA>
            <RE>76192083-9</RE>  <!-- RUT Emisor -->
            <RS>EMPRESA DEMO</RS> <!-- Razón Social -->
            <TD>33</TD>          <!-- Tipo DTE -->
            <RNG>                <!-- Rango -->
                <D>1</D>         <!-- Desde -->
                <H>100</H>       <!-- Hasta -->
            </RNG>
        </DA>
        <FRMA>...</FRMA>         <!-- Firma SII -->
    </CAF>
</AUTORIZACION>
```

### Gestión de folios

| Acción | Recomendación |
|--------|---------------|
| **Solicitar** | Antes de que se agoten (80% uso) |
| **Cantidad** | Según volumen mensual + 20% |
| **Monitoreo** | Alertas automáticas de folios bajos |
| **Respaldo** | Guardar todos los CAF históricos |


    
---

## Emisión de Documentos



---

### Conocimientos Previos

Revisa los conocimientos previos necesarios para emisión de documentos

# Conocimientos Previos

Antes de comenzar con la emisión de documentos, es importante que tengas en cuenta los siguientes conocimientos previos:

---

## Configuración del Certificado Digital

### Formatos de Certificado

API Gateway acepta certificados en los siguientes formatos:

| Formato | Extensión | Descripción |
|---------|-----------|-------------|
| **PFX/P12** | `.pfx`, `.p12` | Formato binario con clave privada incluida |
| **PEM** | `.pem`, `.crt`, `.key` | Formato texto, certificado y clave separados |

### Conversión de Formatos

#### De PFX a PEM (Linux/Mac)

```bash
# Extraer certificado
openssl pkcs12 -in certificado.pfx -clcerts -nokeys -out cert.pem

# Extraer clave privada
openssl pkcs12 -in certificado.pfx -nocerts -nodes -out key.pem

# Verificar certificado
openssl x509 -in cert.pem -text -noout
```

#### De PFX a PEM (Windows - PowerShell)

```powershell
# Usando OpenSSL para Windows
.\openssl.exe pkcs12 -in certificado.pfx -clcerts -nokeys -out cert.pem
.\openssl.exe pkcs12 -in certificado.pfx -nocerts -nodes -out key.pem
```

## Ambientes de Trabajo

API Gateway ofrece dos ambientes principales para la emisión de DTEs:

### 1. Ambiente de Certificación (Pruebas)

| Característica | Detalle |
|----------------|---------|
| **URL Base** | `https://legacy.apigateway.cl` |
| **Parámetro** | `?certificacion=1` |
| **Propósito** | Pruebas y desarrollo |
| **Datos** | Ficticios, sin validez legal |
| **Límites** | Más flexibles |
| **SII** | Ambiente de certificación del SII |

**Ejemplo de uso**:
```
POST https://legacy.apigateway.cl/api/v1/libredte/dte/envios/enviar?certificacion=1
```

### 2. Ambiente de Producción

| Característica | Detalle |
|----------------|---------|
| **URL Base** | `https://legacy.apigateway.cl` |
| **Parámetro** | `?certificacion=0` |
| **Propósito** | Emisión real de DTEs |
| **Datos** | Reales con validez legal |
| **Límites** | Según plan contratado |
| **SII** | Ambiente de producción del SII |

**Ejemplo de uso**:
```
POST https://legacy.apigateway.cl/api/v1/libredte/dte/envios/enviar?certificacion=0
```

---

## Configuración del Entorno de Desarrollo

### Variables de Entorno

Crea un archivo `.env` para gestionar configuraciones:

```env
# API Gateway
API_GATEWAY_URL=https://legacy.apigateway.cl
API_GATEWAY_ENV=0 # 0: Producción, 1: Certificación

# Certificados
CERT_PATH=./certs/cert.pem
KEY_PATH=./certs/key.pem

# Logs
LOG_LEVEL=DEBUG
LOG_PATH=./logs/
```


    
---

### Generar XML de un DTE

Aprende a generar el XML de un documento tributario electrónico usando API Gateway

# Generar XML de un DTE

El primer paso para emitir un DTE es generar su representación en XML. API Gateway simplifica este proceso permitiéndote enviar los datos en formato JSON y encargándose de toda la complejidad del formato XML requerido por el SII.

---

## Endpoint y Parámetros

### URL del Servicio

```http
[POST] https://legacy.apigateway.cl/api/v1/libredte/dte/documentos/generar
```

### Parámetros de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `normalizar` | int | `1` | `0`: No aplica normalización automática<br/>`1`: Aplica normalización automática |
| `formato` | string | `json` | `json` formato por defecto en JSON<br/>`xml` igual que `json` pero en formato XML<br/>`yaml` igual que `json` pero en formato YAML<br/>`JSONString` String JSON que contiene el JSON completo<br/>`Acepta.Normal` todos los DTE menos boletas ni exportación<br/>`Acepta.Boleta` para generar boletas<br/>`FacturacionCL.XML` |
| `gzip` | int | `0` | `0`: Sin comprimir<br/>`1`: Comprime la respuesta |
| `retry` | int | `1` | Número de reintentos si falla |

### URL Típica de Uso

```
https://legacy.apigateway.cl/api/v1/libredte/dte/documentos/generar?normalizar=1&formato=json
```

---

## Estructura del Request


El formato del objeto JSON del DTE corresponde a los mismos nombres que
el XML del DTE que se desea emitir, con los mismos tipos de datos y
restricciones. Puede encontrar más información sobre estos campos en la
documentación del SII en:


- Documentos tributarios electrónicos (no boletas):

    - [Descripción del formato de DTE](https://www.sii.cl/factura_electronica/factura_mercado/formato_dte_202602.pdf)

    - [Diagrama del XML de DTE](https://www.sii.cl/factura_electronica/factura_mercado/diagrama_dte.zip)

- Boletas:

    - [Descripción del formato de boletas](https://www.sii.cl/factura_electronica/factura_mercado/boletas_elec_0720_3.pdf)

    - [Diagrama del XML de boletas](https://www.sii.cl/factura_electronica/factura_mercado/diag_boleta_0920.zip)


La documentación completa, y actualizada, está en la [web del
SII](https://www.sii.cl/factura_electronica/factura_mercado/instructivo.htm).


Es necesario y **obligatorio** que quien desee consumir este recurso
**conozca los campos que debe enviar** y los posibles valores de dichos
campos. Es responsabilidad de quien consume los recursos de la API que
los datos sean los que el SII espera. Por ejemplo, se deben considerar
formatos (K con mayúscula en RUT) o largos (dirección receptor máximo 70
caracteres).


Tenemos algunos [ejemplos de archivos
YAML](https://github.com/LibreDTE/libredte-lib-core/tree/master/tests/fixtures/yaml/documentos_ok)
con los casos más comunes de documentos tributarios electrónicos. Otros
casos deben ser construídos utilizando la documentación oficial del SII
previamente mencionada.


Adicionalmente al formato JSON, existen otros formatos que se pueden
utilizar como entrada de datos para emitir el DTE. Los formatos XML y
YAML siguen la misma regla que el formato JSON. Si necesitas ayuda con
alguno de los otros formatos [abre un ticket de
soporte](https://www.apigateway.cl/help).


**Formatos diferentes a JSON**: si el formato es diferente a `json` se
deben enviar codificados en base64 los datos del documento.
Adicionalmente, el string base64 debe ser enviado como un string JSON.


Ejemplo de los datos a enviar para un DTE con formato JSONString:


```

ewogICAgIkVuY2FiZXphZG8iOiB7CiAgICAgICAgIklkRG9jIjogewogICAgICAgICAgICAiVGlwb0RURSI6IDM5CiAgICAgICAgfSwKICAgICAgICAiRW1pc29yIjogewogICAgICAgICAgICAiUlVURW1pc29yIjogIjc2MTkyMDgzLTkiCiAgICAgICAgfSwKICAgICAgICAiUmVjZXB0b3IiOiB7CiAgICAgICAgICAgICJSVVRSZWNlcCI6ICI2NjY2NjY2Ni02IgogICAgICAgIH0KICAgIH0sCiAgICAiRGV0YWxsZSI6IFsKICAgICAgICB7CiAgICAgICAgICAgICJObWJJdGVtIjogIkNvbmVjdG9yZXMgUko0NSIsCiAgICAgICAgICAgICJRdHlJdGVtIjogNDUwLAogICAgICAgICAgICAiUHJjSXRlbSI6IDcwCiAgICAgICAgfQogICAgXQp9Cg==

```

El ambiente al que se envía el XML al SII estará determinado por el
ambiente del CAF que se está usando para timbrar el DTE.


El CAF se envía en el campo `caf` del cuerpo y es el XML del CAF
autorizado por el SII codificado en base64.


### Estructura Base

Todo request debe incluir:

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "dte": {
        // Contenido del documento
    },
    "resolucion": {
        "fecha": "YYYY-MM-DD",
        "numero": 0
    },
    "caf": "contenido_caf_base64"
}
```

### Componentes Principales

| Campo | Requerido | Descripción |
|-------|-----------|-------------|
| `auth` | ✅ | Autenticación con certificado |
| `dte` | ✅ | Datos del documento a generar |
| `resolucion` | ✅ | Resolución de autorización SII |
| `caf` | ✅ | Código de Autorización de Folios |

---

## Ejemplos por Tipo de Documento

### Ejemplo 1: Boleta Electrónica (39)

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "dte": {
        "Encabezado": {
            "IdDoc": {
                "TipoDTE": 39,
                "FchEmis": "2024-03-15"
            },
            "Emisor": {
                "RUTEmisor": "76192083-9"
            },
            "Receptor": {
                "RUTRecep": "66666666-6",
                "RznSocRecep": "Consumidor Final"
            }
        },
        "Detalle": [
            {
                "NmbItem": "Producto de ejemplo",
                "QtyItem": 2,
                "PrcItem": 5000  // Precio con IVA incluido
            }
        ]
    },
    "resolucion": {
        "fecha": "2019-12-23",
        "numero": 0
    },
    "caf": "PD94bWwgdmVyc2..."
}
```

### Ejemplo 2: Factura Electrónica (33)

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "dte": {
        "Encabezado": {
            "IdDoc": {
                "TipoDTE": 33,
                "FchEmis": "2024-03-15"
            },
            "Emisor": {
                "RUTEmisor": "76192083-9",
                "RznSoc": "Mi Empresa SpA",
                "GiroEmis": "Servicios Informáticos",
                "Acteco": 620100,
                "DirOrigen": "Av. Principal 123",
                "CmnaOrigen": "Providencia"
            },
            "Receptor": {
                "RUTRecep": "11111111-1",
                "RznSocRecep": "Cliente Empresa SA",
                "GiroRecep": "Comercio",
                "DirRecep": "Calle Comercio 456",
                "CmnaRecep": "Santiago"
            }
        },
        "Detalle": [
            {
                "NmbItem": "Servicio de Desarrollo",
                "DscItem": "Desarrollo de módulo facturación",
                "QtyItem": 1,
                "UnmdItem": "Unidad",
                "PrcItem": 1000000  // Precio neto (sin IVA)
            },
            {
                "NmbItem": "Soporte Técnico",
                "QtyItem": 3,
                "UnmdItem": "Horas",
                "PrcItem": 50000
            }
        ]
    },
    "resolucion": {
        "fecha": "2019-12-23",
        "numero": 0
    },
    "caf": "..."
}
```

### Ejemplo 3: Nota de Crédito (61)

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "dte": {
        "Encabezado": {
            "IdDoc": {
                "TipoDTE": 61,
                "FchEmis": "2024-03-15"
            },
            "Emisor": {
                "RUTEmisor": "76192083-9"
            },
            "Receptor": {
                "RUTRecep": "11111111-1",
                "RznSocRecep": "Cliente Empresa SA"
            },
            "Totales": {
                "MntNeto": 100000,
                "IVA": 19000,
                "MntTotal": 119000
            }
        },
        "Detalle": [
            {
                "NmbItem": "Anulación de servicio",
                "QtyItem": 1,
                "PrcItem": 100000
            }
        ],
        "Referencia": [
            {
                "NroLinRef": 1,
                "TpoDocRef": "33",
                "FolioRef": "123",
                "FchRef": "2024-03-10",
                "RazonRef": "Anula factura por error en monto"
            }
        ]
    },
    "resolucion": {
        "fecha": "2019-12-23",
        "numero": 0
    },
    "caf": "..."
}
```

---

## Normalización Automática

### ¿Qué hace la normalización?

Cuando `normalizar=1`, API Gateway automáticamente:

1. **Calcula totales**: IVA, montos netos, totales
2. **Numera líneas**: Asigna NroLinDet si no existe
3. **Completa campos**: Agrega campos opcionales útiles
4. **Valida coherencia**: Verifica que los montos cuadren

### Ejemplo: Con y Sin Normalización

#### Con Normalización (`normalizar=1`)
```json
{
    "Detalle": [
        {
            "NmbItem": "Producto",
            "QtyItem": 2,
            "PrcItem": 1000
        }
    ]
}
```

#### Sin Normalización (`normalizar=0`)
```json
{
    "Detalle": [
        {
            "NroLinDet": 1,
            "NmbItem": "Producto",
            "QtyItem": 2,
            "PrcItem": 1000,
            "MontoItem": 2000
        }
    ],
    "Encabezado": {
        "Totales": {
            "MntNeto": 2000,
            "IVA": 380,
            "MntTotal": 2380
        }
    }
}
```

---

## Estructura de la Respuesta

### Respuesta Exitosa

La respuesta incluye 3 XMLs diferentes en Base64:

```json
{
    "dte": "PD94bWwgdmVyc2lvbj0iMS4w...",     // XML del DTE individual
    "sii": "PD94bWwgdmVyc2lvbj0iMS4w...",     // XML para enviar al SII
    "receptor": "PD94bWwgdmVyc2lvbj0iMS4w..." // XML para el receptor
}
```
---

## Errores Comunes y Soluciones

### Error: RUT Inválido

```json
{
    "error": {
        "code": "xxx",
        "message": "RUT del receptor no es válido"
    }
}
```

**Solución**: Verificar formato correcto: `11111111-1` (sin puntos, con guión)

### Error: CAF Faltante

```json
{
    "error": {
        "code": "xxx",
        "message": "CAF requerido para el tipo de documento"
    }
}
```

**Solución**: Incluir el CAF en base64 en el campo `caf`

### Error: Fecha Fuera de Rango

```json
{
    "error": {
        "code": "xxx",
        "message": "Fecha de emisión fuera del rango permitido"
    }
}
```

**Solución**: La fecha debe ser del día actual o hasta 2 meses atrás


    
---

### Enviar XML al SII

Aprende cómo enviar el XML generado al Servicio de Impuestos Internos

# Enviar XML al SII

Una vez generado el XML del DTE, el siguiente paso crítico es enviarlo al SII. Este proceso valida tu documento y, si es correcto, lo incorpora al sistema tributario oficial. El SII responde con un Track ID que permite dar seguimiento al estado del documento.

Para enviar un XML al SII se debe enviar la firma electrónica al servicio web y será el RUT asociado a la firma electrónica el que se usará para identificar el envío ante el SII ("rut envío"), ya que es el RUT de la persona que envía el XML, no el RUT de la empresa emisora del XML.

---

## Endpoint y Parámetros

### URL del Servicio

```http
[POST] https://legacy.apigateway.cl/api/v1/libredte/dte/envios/enviar
```

### Parámetros de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `certificacion` | int | `0` | `1`: Ambiente de certificación<br>`0`: Ambiente de producción |
| `gzip` | int | `0` | `1`: Enviar comprimido<br>`0`: Enviar sin comprimir |
| `retry` | int | `1` | Cantidad de intentos de envío |

### URL Típica de Uso

```
https://legacy.apigateway.cl/api/v1/libredte/dte/envios/enviar?certificacion=0&retry=3
```

---

## Estructura del Request

- El XML a enviar debe estar codificado en base64.
- Permite enviar al SII cualquier tipo de DTE (incluyendo boletas).

### Body de la Solicitud

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "emisor": "76192083-9",
    "xml": "PD94bWwgdmVyc2lvbj0iMS4w..."
}
```

### Campos Requeridos

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `auth` | object | Autenticación con certificado digital |
| `emisor` | string | RUT del emisor (con guión) |
| `xml` | string | XML del campo `sii` de la respuesta anterior |

> [!INFO] Importante
>
> El campo `xml` debe contener el contenido del campo `sii` obtenido en el paso anterior, NO el campo `dte`.

---

## Estructura de la Respuesta

### Respuesta Exitosa

```json
{
    "track_id": 4753411374,
    "certificacion": 0
}
```

### Componentes de la Respuesta

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `track_id` | integer | Identificador único del envío |
| `certificacion` | integer | Ambiente donde se procesó |

---

## Conceptos Clave

### ¿Qué es el Track ID?

El Track ID es un número único que:
- Identifica tu envío en el sistema del SII
- Permite consultar el estado del procesamiento
- Es indispensable para el seguimiento
- Debe ser almacenado en tu sistema

---

## Tiempos y Estrategias

### Estrategia de Reintentos

El parámetro `retry` permite reintentos automáticos:

```
?retry=3  // Intentará hasta 3 veces si falla
```

**Cuándo es útil**:
- Problemas de conectividad temporales
- Alta carga en el SII
- Timeouts esporádicos

---

## Manejo de Errores

### Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| **Timeout** | SII no responde a tiempo | Aumentar timeout, reintentar |
| **XML inválido** | Estructura incorrecta | Verificar que se usa campo `sii` |
| **Certificado rechazado** | Certificado no autorizado | Verificar vigencia y permisos |
| **Emisor no coincide** | RUT emisor diferente | Verificar RUT en el XML |

### Respuesta de Error Típica

```json
{
    "code": 400,
    "message": "No fue posible enviar el XML al SII.",
    "logs": [
        {
            "code": 52,
            "msg": "Falló el envío automático al SII. Empty reply from server",
            "file": null,
            "line": null,
            "function": null,
            "class": null,
            "type": null,
            "args": null
        }
    ]
}
```

---

## Mejores Prácticas

### 1. Almacenar Track ID Inmediatamente

Siempre guarda el Track ID en tu base de datos junto con:
- Tipo de documento
- Folio
- Fecha de envío
- RUT emisor
- RUT receptor

### 2. Logs de Envío

Registra cada intento de envío con:
- Timestamp
- Track ID (si se obtiene)
- Código de respuesta
- Mensajes de error
- Número de intento

### 3. Manejo de Contingencias

Si el SII no está disponible:
1. Guardar el XML localmente
2. Intentar envío cada 30 minutos
3. Notificar al administrador
4. Mantener registro de pendientes

---

## Pruebas en Certificación

### Usar Ambiente de Certificación

Para pruebas, agrega `certificacion=1`:

```
https://legacy.apigateway.cl/api/v1/libredte/dte/envios/enviar?certificacion=1
```

### Ventajas del Ambiente de Certificación

- Sin consecuencias tributarias
- Respuestas más rápidas
- Ideal para pruebas de integración
- Misma estructura que producción


    
---

### Consultar Estado del Envío

Aprende a consultar el estado de tus documentos enviados al SII

# Consultar Estado del Envío

Después de enviar un documento al SII y recibir un Track ID, es fundamental consultar el estado del procesamiento. El SII no procesa los documentos instantáneamente, por lo que debes implementar un mecanismo de consulta para conocer el resultado final.

---

## Endpoint y Estructura

### URL del Servicio

```http
[POST] https://legacy.apigateway.cl/api/v1/libredte/dte/envios/estado
```

### Parámetro de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `certificacion` | int | `0` | `1`: Ambiente de certificación<br>`0`: Ambiente de producción |

---

## Estructura del Request

### Para Documentos NO Boletas

Para facturas, guías de despacho, notas de crédito/débito:

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "emisor": "76192083-9",
    "track_id": "82484882"
}
```

### Para Boletas Electrónicas

Las boletas requieren información adicional:

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    },
    "emisor": "76192083-9",
    "track_id": 14112302429,
    "dte": 39,
    "folio": 112
}
```

### Diferencias Clave

| Tipo Documento | Campos Requeridos | Observación |
|----------------|-------------------|-------------|
| **Facturas y otros** | `emisor`, `track_id` | Consulta simple |
| **Boletas** | `emisor`, `track_id`, `dte`, `folio` | Requiere tipo y folio |

---

## Estructura de la Respuesta

### Respuesta Típica

```json
{
    "track_id": "82484882",
    "certificacion": 0,
    "revision_estado": "DOK - Documento Recibido",
    "revision_detalle": null
}
```

### Respuesta con Error

```json
{
    "track_id": "82484883",
    "certificacion": 0,
    "revision_estado": "RCT - Rechazado por Error en Caratula",
    "revision_detalle": "ERROR EN RUT RECEPTOR: DIGITO VERIFICADOR INCORRECTO"
}
```

---

## Estados Posibles

### Estados Principales (No Boletas)

| Estado | Código | Significado | Acción Requerida |
|--------|--------|-------------|------------------|
| **Aceptado** | DOK | Documento procesado correctamente | Generar PDF, notificar |
| **Aceptado con Reparos** | DNK | Válido pero con observaciones | Revisar reparos, continuar |
| **Rechazado** | RCH, RCT, RCF | Documento con errores | Corregir y reenviar |
| **En Proceso** | EPR | Aún procesando | Consultar nuevamente |

### Códigos de Rechazo Detallados

| Código | Descripción | Causa Común |
|--------|-------------|-------------|
| **RCH** | Rechazado por Error en Schema | Estructura XML incorrecta |
| **RCT** | Rechazado por Error en Carátula | Datos del envío incorrectos |
| **RCF** | Rechazado por Error en Firma | Problema con certificado digital |
| **SOK** | Schema Validado | Primera validación OK (temporal) |

---

## Estados de Boletas Electrónicas

### Consulta de Boletas

Para boletas, el campo `folio` tiene un comportamiento especial:

| Valor `folio` | Comportamiento | Uso Recomendado |
|---------------|----------------|-----------------|
| Número específico | Busca ese folio exacto | Consulta individual |
| `0` o no incluido | Estado general del envío | Consulta masiva |

### Particularidades de Boletas

- Pueden enviarse múltiples boletas en un solo envío
- El estado general puede diferir del estado individual
- Importante verificar cada folio si hay problemas

![Estados Boletas Electrónicas](https://www.apigateway.cl/img/content/academy/integracion-para-la-emision-de-dte/estados_boleta_electronica.jpg "Estados Generales para una boleta electrónica")


    
---

### Generar PDF del DTE

Aprende a generar la representación visual en PDF de tus documentos tributarios

# Generar PDF del DTE (Opcional)

Aunque el XML es el documento con validez legal, el PDF es fundamental para la experiencia del receptor. Es lo que el cliente ve, imprime y archiva. API Gateway ofrece múltiples opciones de personalización para que el PDF refleje tu imagen corporativa y cumpla con los requisitos legales.

---

## Endpoint del Servicio

### URL

```http
[POST] https://legacy.apigateway.cl/api/v1/libredte/dte/documentos/pdf
```

### Características

- El XML debe enviarse codificado en Base64
- Acepta XMLs individuales o múltiples
- Respuesta en formato PDF binario
- Sin parámetros en la URL

---

## Estructura Básica del Request

### Request Mínimo

```json
{
    "formato": "general",
    "xml": "PD94bWwgdmVyc2lvbj0iMS4w..."
}
```

### Request con Opciones

```json
{
    "formato": "general",
    "cedible": true,
    "copias_tributarias": 1,
    "copias_cedibles": 1,
    "webVerificacion": false,
    "xml": "PD94bWwgdmVyc2lvbj0iMS4w..."
}
```

---

## Formatos Disponibles

### Tipos de Formato

| Formato | Descripción | Ideal para | Características |
|---------|-------------|------------|-----------------|
| `estandar` | Formato LibreDTE | Uso general | Diseño limpio y funcional |
| `general` | Formato Empresarial | Empresas | Más opciones de personalización |
| `servicios_basicos` | Servicios básicos | Servicios | Incluye gráficos de consumo |

---

## Opciones de Configuración

### Parámetros Principales

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `formato` | string | `estandar` | Tipo de formato a usar |
| `cedible` | boolean | `false` | Incluir copia cedible |
| `copias_tributarias` | integer | `1` | Número de copias tributarias |
| `copias_cedibles` | integer | `0` | Número de copias cedibles |
| `webVerificacion` | boolean | `true` | Incluir URL de verificación |
| `compress` | boolean | `false` | Para múltiples DTEs en ZIP |

---

## Personalización Avanzada

### Estructura del Objeto `extra`

```json
{
    "extra": {
        "emisor": {
            "razonsocial": true,
            "giro": true,
            "direccion": true,
            "telefono": false,
            "web": false,
            "email": false
        },
        "detalle": {
            "posicion": 0,
            "fuente": 9,
            "ancho": {
                "CdgItem": 30,
                "QtyItem": 15,
                "PrcItem": 22,
                "DescuentoMonto": 22,
                "RecargoMonto": 22,
                "MontoItem": 22
            }
        }
    }
}
```

### Opciones del Emisor

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `razonsocial` | boolean | Mostrar razón social |
| `giro` | boolean | Mostrar giro comercial |
| `direccion` | boolean | Mostrar dirección |
| `telefono` | boolean | Incluir teléfono |
| `web` | boolean | Incluir sitio web |
| `email` | boolean | Incluir email |

---

## Imágenes y Logos

### Configuración de Imágenes

```json
{
    "extra": {
        "img": {
            "logo": "base64_del_logo",
            "cotizacion": "base64_imagen_cotizacion",
            "historial": "base64_grafico_historial",
            "pie": "base64_imagen_pie"
        }
    }
}
```
---

## Códigos de Barra

### Opciones Disponibles

```json
{
    "extra": {
        "codigo_barras": {
            "cotizacion": true,
            "dte": true,
            "incluirrut": false
        }
    }
}
```

| Opción | Descripción | Contenido |
|--------|-------------|-----------|
| `cotizacion` | Código para cotización | Número de cotización |
| `dte` | Código del documento | TED (Timbre Electrónico) |
| `incluirrut` | RUT en código | Agrega RUT receptor |

---

## Personalización de Colores

### Configuración

```json
{
    "extra": {
        "color": {
            "razonsocial": [14, 66, 170]
        }
    }
}
```

### Formato RGB

- Valores: Array de 3 números [R, G, B]
- Rango: 0-255 para cada componente
- Ejemplo: [14, 66, 170] = Azul corporativo

---

## Gráficos de Historial

### Para Servicios Básicos

```json
{
    "extra": {
        "historial": {
            "titulo": "Consumo de Agua Potable",
            "datos": {
                "Febrero": 12,
                "Marzo": 11,
                "Abril": 12,
                "Mayo": 10.5,
                "Junio": 4,
                "Julio": 5
            }
        }
    }
}
```

### Características del Gráfico

- Tipo: Barras verticales
- Máximo: 12 meses
- Unidades: Numéricas
- Colores: Automáticos

---

## Papel Continuo

### Configuración

Para puntos de venta con impresoras térmicas:

```json
{
    "formato": "estandar",
    "papelContinuo": 80
}
```

### Anchos Disponibles

| Ancho | Uso Típico | Impresora |
|-------|------------|-----------|
| `57` | Tickets pequeños | Móviles |
| `75` | Estándar | POS común |
| `80` | Más común | Mayoría POS |
| `110` | Documentos amplios | Especiales |

---

## Múltiples DTEs

### Generar ZIP con Varios PDFs

```json
{
    "compress": true,
    "xml": "XML_con_multiples_DTEs_base64"
}
```

### Consideraciones

- Retorna archivo ZIP
- Un PDF por cada DTE
- Nombres: `tipo_folio.pdf`


    
---

### Gestión de Códigos de Autorización de Folios (CAF)

Aprende a automatizar la gestión de CAF con API Gateway para emisión de documentos tributarios

# Gestión de Códigos de Autorización de Folios (CAF)

Los Códigos de Autorización de Folios (CAF) son archivos XML autorizados por el SII que contienen el rango de folios permitidos para emitir documentos tributarios electrónicos. API Gateway permite automatizar completamente la gestión de estos códigos, desde la solicitud hasta la consulta de estado.

> [!INFO] Importante
>
>La primera solicitud de CAF para cada tipo de documento debe realizarse manualmente en el portal del SII. Las solicitudes posteriores pueden automatizarse usando esta API.


---

## ¿Qué es un CAF?

Un CAF es un archivo XML que contiene:
- **Rango de folios autorizados**: Números de folio inicial y final
- **Tipo de documento**: El tipo de DTE al que aplica (33, 39, 61, etc.)
- **Fecha de autorización**: Cuándo fue emitido por el SII
- **Firma digital del SII**: Que valida su autenticidad

### Ejemplo de estructura CAF
```xml
<AUTORIZACION>
    <CAF version="1.0">
        <DA>
            <RE>76192083-9</RE>
            <RS>MI EMPRESA SPA</RS>
            <TD>33</TD>
            <RNG>
                <D>1000</D>
                <H>1999</H>
            </RNG>
            <FA>2024-03-15</FA>
        </DA>
        <FRMA>...</FRMA>
    </CAF>
</AUTORIZACION>
```

---

## 1. Solicitar un Nuevo CAF

Permite solicitar automáticamente un nuevo rango de folios al SII.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/solicitar/{emisor}/{dte}/{cantidad}
```

### Parámetros de Ruta

| Parámetro | Tipo | Descripción | Ejemplo |
|-----------|------|-------------|---------|
| `emisor` | string | RUT del emisor | `76192083-9` |
| `dte` | string | Tipo de documento | `33` |
| `cantidad` | string | Cantidad de folios | `100` |

### Parámetros de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `certificacion` | string | `0` | `0`: Producción<br/>`1`: Certificación |

### Ejemplo de Request

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    }
}
```

### Ejemplo de Uso

```bash
curl -X POST https://legacy.apigateway.cl/api/v1/sii/dte/caf/solicitar/76192083-9/33/100?certificacion=0 \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    }
}'
```

### Respuesta Exitosa

```xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<AUTORIZACION>
    <CAF version="1.0">
        <DA>
            <RE>76192083-9</RE>
            <RS>MI EMPRESA SPA</RS>
            <TD>33</TD>
            <RNG>
                <D>2000</D>
                <H>2099</H>
            </RNG>
            <FA>2024-03-15</FA>
            <RSAPK>...</RSAPK>
            <IDK>100</IDK>
        </DA>
        <FRMA algoritmo="SHA1withRSA">...</FRMA>
    </CAF>
    <RSASK>...</RSASK>
    <RSAPUBK>...</RSAPUBK>
</AUTORIZACION>
```

---

## 2. Descargar XML de CAF Existente

Permite descargar nuevamente un CAF ya autorizado por el SII.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/xml/{emisor}/{dte}/{folio_inicial}/{folio_final}/{fecha_autorizacion}
```

### Parámetros de Ruta

| Parámetro | Tipo | Descripción | Ejemplo |
|-----------|------|-------------|---------|
| `emisor` | string | RUT del emisor | `76192083-9` |
| `dte` | string | Tipo de documento | `33` |
| `folio_inicial` | string | Primer folio del rango | `669` |
| `folio_final` | string | Último folio del rango | `678` |
| `fecha_autorizacion` | string | Fecha de autorización | `2024-03-15` |

### Ejemplo de Request

```json
{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
        }
    }
}
```

### Caso de Uso

Este endpoint es útil cuando:
- Se perdió el archivo CAF original
- Se necesita recuperar un CAF histórico
- Se requiere validar información de un CAF

---

## 3. Consultar Estado de un Folio

Verifica el estado actual de un folio específico en el SII.

> **Limitación** Este servicio NO funciona con folios de boletas (tipos 39 o 41). Solo es compatible con otros tipos de DTE.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/estado/{emisor}/{dte}/{folio}
```

### Parámetros de Ruta

| Parámetro | Tipo | Descripción | Ejemplo |
|-----------|------|-------------|---------|
| `emisor` | string | RUT del emisor | `76192083-9` |
| `dte` | string | Tipo de documento | `33` |
| `folio` | string | Número de folio | `77` |

### Parámetros de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `certificacion` | string | `0` | `0`: Producción<br/>`1`: Certificación |
| `formato` | string | `json` | `json`: Respuesta en JSON<br/>`html`: Respuesta en HTML |

### Respuesta en JSON

```json
{
    "estado": "recibido",
    "estado_glosa": "Documento recibido por el SII",
    "track_id": "1234"
}
```

### Estados Posibles

| Estado | Descripción |
|--------|-------------|
| `recibido` | Documento recibido correctamente por el SII |
| `anulado` | Folio anulado |
| `pendiente` | Folio asignado pero no utilizado |
| `rechazado` | Documento rechazado por el SII |

---

## 4. Anular Folios

Permite anular un rango de folios no utilizados.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/anular/{emisor}/{dte}/{folio_inicial}/{folio_final}
```

### Parámetros de Ruta

| Parámetro | Tipo | Descripción | Ejemplo |
|-----------|------|-------------|---------|
| `emisor` | string | RUT del emisor | `76192083-9` |
| `dte` | string | Tipo de documento | `33` |
| `folio_inicial` | string | Primer folio a anular | `707` |
| `folio_final` | string | Último folio a anular | `710` |

### Consideraciones Importantes

- Solo se pueden anular folios **no utilizados**
- La anulación es **irreversible**
- Se puede anular un folio individual o un rango

### Ejemplo: Anular un Solo Folio

```bash
# Para anular solo el folio 707
POST .../anular/76192083-9/33/707/707
```

### Ejemplo: Anular un Rango

```bash
# Para anular del folio 707 al 720
POST .../anular/76192083-9/33/707/720
```

---

## 5. Listar Folios Solicitados

Obtiene el historial de todas las solicitudes de CAF realizadas.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/solicitudes/{emisor}/{dte}
```

### Parámetros de Query

| Parámetro | Tipo | Default | Descripción |
|-----------|------|---------|-------------|
| `certificacion` | string | `0` | `0`: Producción<br/>`1`: Certificación |
| `formato` | string | `json` | `json` o `html` |
| `pagina` | string | `0` | `0`: Todas las solicitudes<br/>`>0`: Página específica |

### Respuesta

```json
[
    {
        "cantidad": 601,
        "fecha": "2024-03-01",
        "inicial": 5618,
        "final": 6218,
        "mandatario": ""
    },
    {
        "cantidad": 100,
        "fecha": "2024-02-15",
        "inicial": 5518,
        "final": 5617,
        "mandatario": ""
    }
]
```

---

## 6. Listar Folios por Estado

Consulta folios dentro de un rango específico según su estado.

### Endpoint

```http
[POST] https://legacy.apigateway.cl/api/v1/sii/dte/caf/estados/{emisor}/{dte}/{folio_inicial}/{folio_final}/{estado}
```

### Parámetros de Ruta

| Parámetro | Tipo | Descripción | Ejemplo |
|-----------|------|-------------|---------|
| `emisor` | string | RUT del emisor | `76192083-9` |
| `dte` | string | Tipo de documento | `52` |
| `folio_inicial` | string | Folio inicial a consultar | `1` |
| `folio_final` | string | Folio final a consultar | `104` |
| `estado` | string | Estado a filtrar | `recibidos` |

### Estados Disponibles

- `recibidos`: Documentos recibidos por el SII
- `anulados`: Folios anulados
- `pendientes`: Folios asignados pero no utilizados

### Respuesta

```json
[
    {
        "cantidad": "9",
        "inicial": "1",
        "final": "9"
    },
    {
        "cantidad": "31",
        "inicial": "13",
        "final": "43"
    }
]
```


    
---

## ¡Ponte a prueba!



---

### Autoevaluación




## Test de Emisión de DTE con API Gateway

Autoevaluación técnica sobre el proceso de emisión de DTE usando API Gateway y su integración con el SII.

### 1. ¿Qué método de autenticación usa API Gateway?

- [ ] Token JWT
- [ ] API Key
- [x] OAuth2

> API Gateway utiliza OAuth2 como método de autenticación.

### 2. ¿En qué formato debe ir el token en la cabecera HTTP?

- [ ] Authorization: Token ACCESS-TOKEN
- [x] Authorization: Bearer ACCESS-TOKEN
- [ ] Bearer: ACCESS-TOKEN

> El token debe ir como Authorization: Bearer ACCESS-TOKEN.

### 3. ¿Qué formatos de entrada acepta el servicio de emisión de DTE?

- [ ] Solo JSON
- [x] JSON, XML, YAML
- [ ] XML y JSON solamente

> El servicio acepta JSON, XML y YAML; si no es JSON, debe codificarse en Base64.

### 4. ¿Cuál es el propósito del parámetro 'normalizar=1'?

- [ ] Enviar el DTE al SII
- [x] Simplificar la estructura y calcular valores automáticamente
- [ ] Validar que el DTE cumpla con el formato del SII

> Permite enviar menos campos y que se calculen automáticamente valores como el IVA.

### 5. ¿Qué campo contiene el XML que debe enviarse al SII después de generar el DTE?

- [ ] DTE
- [ ] Envío
- [x] SII

> El campo 'sii' contiene el XML que se debe enviar al SII para su validación.

### 6. ¿Qué respuesta entrega el SII tras recibir un DTE?

- [ ] PDF del documento
- [x] Track ID
- [ ] Token de validación

> El Track ID permite consultar el estado del DTE enviado al SII.

### 7. ¿Qué estados posibles puede tener un DTE enviado al SII?

- [x] Aceptado, Aceptado con reparos, Rechazado
- [ ] Emitido, Procesado, Aceptado
- [ ] Enviado, Validado, Aprobado

> Son los estados estándar que el SII puede devolver para un DTE: aceptado, con reparos, o rechazado.

### 8. ¿Cuál es el endpoint para consultar el estado de un DTE en el SII?

- [ ] POST /estado_dte
- [x] POST /envios/estado
- [ ] GET /consultar_estado

> POST /envios/estado permite consultar el estado de un envío usando el Track ID.

### 9. ¿Qué parámetros se requieren para usar un certificado digital como archivo?

- [ ] file-url y file-pass
- [x] file-data (base64) y file-pass
- [ ] cert-file y cert-key

> Se debe usar file-data con el contenido base64 del archivo .p12 y su contraseña en file-pass.

### 10. ¿Cuál es el propósito del endpoint /pdf/dte?

- [ ] Enviar el DTE al SII
- [x] Obtener una representación visual del DTE
- [ ] Validar el contenido XML

> Este endpoint permite generar un PDF desde el XML del DTE para su respaldo o envío al cliente.

### 11. ¿Qué parámetro se debe incluir para usar el ambiente de certificación?

- [ ] sii_mode=test
- [ ] demo=1
- [x] certificacion=1

> certificacion=1 activa el modo de pruebas del SII.

### 12. ¿Cuál es el formato de datos recomendado para integrarse con API Gateway?

- [ ] XML
- [ ] YAML
- [x] JSON

> JSON es el formato recomendado por defecto.


    

---

Last updated on 21/08/2026
#api-gateway-legacy