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

[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 `1`: Aplica normalización automática
`formato`	string	`json`	`json` formato por defecto en JSON `xml` igual que `json` pero en formato XML `yaml` igual que `json` pero en formato YAML `JSONString` String JSON que contiene el JSON completo `Acepta.Normal` todos los DTE menos boletas ni exportación `Acepta.Boleta` para generar boletas `FacturacionCL.XML`
`enviar_sii`	int	`0`	`0`: Solo genera XML `1`: Envía automáticamente al SII
`gzip`	int	`0`	`0`: Sin comprimir `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&enviar_sii=0

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
- Diagrama del XML de DTE
Boletas:
- Descripción del formato de boletas
- Diagrama del XML de boletas

La documentación completa, y actualizada, está en la web del SII.

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 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.

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:

{
    "auth": {
        "cert": {
            "cert-data": "certificado_en_base64",
            "pkey-data": "llave_privada_en_base64"
        }
    },
    "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)

{
    "auth": {
        "cert": {
            "cert-data": "MIIGZjCCBE6gAwIBAgIIf...",
            "pkey-data": "MIIEvQIBADANBgkqhkiG..."
        }
    },
    "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)

{
    "auth": {
        "cert": {
            "cert-data": "...",
            "pkey-data": "..."
        }
    },
    "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)

{
    "auth": {
        "cert": {
            "cert-data": "...",
            "pkey-data": "..."
        }
    },
    "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:

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

Ejemplo: Con y Sin Normalización

Con Normalización (`normalizar=1`)

{
    "Detalle": [
        {
            "NmbItem": "Producto",
            "QtyItem": 2,
            "PrcItem": 1000
        }
    ]
}

Sin Normalización (`normalizar=0`)

{
    "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:

{
    "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

{
    "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

{
    "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

{
    "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

Integración para la emisión de DTE