---
title: "Paso a producción"
description: ""
type: "academy"
category: "module"
tags: []
authors: [Anonymous]
date: "2026-11-05"
last_update: "2026-11-05"
time_minutes: 13
draft: false
unlisted: false
url: "https://www.apigateway.cl/academy/emision-de-dte/produccion"
---

# Paso a producción




---

## Errores frecuentes

Los errores más comunes al integrar la emisión de DTE, ordenados por etapa, con su causa y su solución.

# Errores frecuentes

Esta es una guía de diagnóstico. Busca el síntoma que ves y la etapa en que ocurre.

## Errores de la API (antes de llegar al SII)

| Síntoma | Causa | Solución |
|---------|-------|----------|
| `401` | Token ausente o mal escrito. | Usa la cabecera `Authorization: Token <token>`, con la palabra `Token` y un espacio. |
| `402` | La conexión no tiene créditos o tiene un problema de pago. | Revisa tu conexión en [app.apigateway.cl](https://app.apigateway.cl). |
| `404` | La URL de la operación no existe. | Revisa las cuatro partes de la URL y que el método sea `POST`. |
| `400` | Falta un parámetro o tiene otro nombre. | Todos los parámetros van dentro de `parameters`, con el nombre exacto de la documentación (`bag`, `source`, `request`, `doc`, `company`, `trackId`). |
| `422` con `No se encontró un deserializador capaz de construir una instancia de ... requiere datos codificados en base64 válido.` | Un XML (del DTE, del sobre o del CAF) o un `.p12` no viene en base64. | Codifica en base64, en una sola línea, sin saltos. |
| `422` con `Se requieren los datos del certificado ...` | Certificado incompleto. | Envía `certificate` + `privateKey` (PEM), o `data` + `password` (`.p12`). |
| `503` | El servicio de LibreDTE no está disponible en ese momento. | Reintenta en unos minutos. |

## Errores al construir el documento o el sobre

| Mensaje (`detail`) | Causa | Solución |
|--------------------|-------|----------|
| `El XPath "//Encabezado/IdDoc/Folio" ... es obligatorio: no coincidió con ningún nodo.` | Falta `IdDoc.Folio`. | Asigna el folio desde tu control de folios. |
| `El folio N ... no está disponible en el rango del CAF ...` | El folio no está en el CAF enviado. | Revisa el rango del CAF y que sea el CAF del tipo de documento correcto. |
| `El CAF ... fue autorizado al emisor ..., pero el documento ... es del emisor ...` | El CAF es de otra empresa: su RUT no coincide con `RUTEmisor`. | Usa un CAF solicitado por la misma empresa que emite el documento. |
| `El CAF ... es del tipo de documento ..., pero el documento ... es del tipo ...` | El CAF es de otro tipo de documento. | Usa el CAF del mismo tipo que el documento: de facturas para una factura, de boletas para una boleta. |
| `The verification digit of the RUT ... is incorrect.` | RUT con dígito verificador incorrecto. | Valida los RUT al registrarlos en tu sistema. |
| `Falta incluir documento de referencia.` | Nota de crédito o débito sin `Referencia`. | Agrega la referencia al documento que corrige. |
| `La carátula del sobre no está definida.` | Al armar el sobre falta `emisor.autorizacion_dte` (la resolución) o el certificado. | Envía la resolución del emisor y el certificado en `dispatcher/create`. |
| Totales distintos a los esperados | En una factura enviaste precios con IVA, o en una boleta precios sin IVA. | Factura: `PrcItem` neto. Boleta: `PrcItem` con IVA. |

## Rechazos del SII

| Estado | Causa común | Solución |
|--------|-------------|----------|
| `RSC` Rechazado por error en el esquema | Un campo supera su largo máximo, tiene un formato inválido o falta. | Valida con `validator/validateSchema` antes de enviar. Revisa los largos máximos (por ejemplo, `GiroRecep` 40 caracteres). |
| `RFR` Rechazado por error en la firma | El XML se modificó después de firmarlo (por ejemplo, al cambiar su codificación). | Guarda y envía el base64 tal como lo entregó la API. No conviertas el XML a UTF-8. |
| `RCT` Rechazado por error en la carátula | La resolución (número o fecha) no corresponde, o no corresponde al ambiente. | En certificación usa número `0` y la fecha de certificación; en producción, la resolución real. |
| `EPR` con facturas, notas o guías rechazadas | Un dato del documento no es válido para el SII: folio no autorizado, CAF de otro ambiente, receptor inexistente, referencia a un documento que no existe. | Pide el detalle con `requestXmlDocumentSentStatusByEmail` (ver [Consultar el estado](https://www.apigateway.cl/academy/emision-de-dte/emision/paso-5-consultar-el-estado)). |
| `EPR` con reparos | El documento es válido, pero tiene observaciones menores. | Revisa las observaciones para corregir los documentos siguientes. |

## Errores con boletas

| Síntoma | Causa | Solución |
|---------|-------|----------|
| `El tipo de documento Factura electrónica no se puede agregar a un sobre de tipo ENVIO_BOLETA.` | Juntaste una boleta y otro DTE en el mismo sobre. | Arma un sobre para las boletas y otro para los demás documentos. |
| `El XML es un EnvioBOLETA y no se puede enviar con el worker de DTE, las boletas se envían con el worker de boletas.` | Enviaste un sobre de boletas con `sii_dte`: el SII recibe las boletas por otro servicio. | Las boletas se envían con `sii_boleta/sendXmlDocument` y su estado se consulta con `sii_boleta/checkXmlDocumentSentStatus`. |
| `rate_limit.remaining` en `0` | Usaste todas las solicitudes que permite el servicio de boletas del SII. | Espera los segundos de `rate_limit.reset` antes de la siguiente llamada. |
| Totales distintos a los esperados | Enviaste precios sin IVA. | En una boleta, `PrcItem` va con IVA incluido. |
| Boleta exenta con `MntExe` en `0` | Los ítems de la boleta `41` no tienen `IndExe`. | Marca cada ítem con `IndExe: 1`. |
| `RPT` Envío repetido rechazado | Enviaste de nuevo un sobre que el SII ya había recibido. | Consulta el estado con el Track ID del primer envío. |
| `details` con boletas rechazadas | Un dato de esas boletas no es válido para el SII. | Revisa `section`, `description` y `detail` de cada error (ver [Consultar el estado de boletas](https://www.apigateway.cl/academy/emision-de-dte/emision/paso-5-consultar-el-estado#52-boletas)). |

## Errores de autenticación en el SII

| Síntoma | Causa | Solución |
|---------|-------|----------|
| Falla la autenticación al enviar o consultar | Certificado vencido, revocado o autofirmado. | Usa un certificado vigente, emitido por una entidad autorizada. |
| Falla la autenticación con un certificado válido | La persona del certificado no está autorizada en el SII para la empresa. | En el SII, la empresa debe registrar a esa persona como usuario autorizado para DTE. |
| El documento se envió a producción por error | No se indicó `options.environment`. | Indica siempre el ambiente. El valor por defecto es producción. |

## Errores de diseño que aparecen más tarde

Estos errores no dan un mensaje inmediato, pero causan problemas en producción:

| Problema | Consecuencia | Prevención |
|----------|--------------|------------|
| Dos emisiones usan el mismo folio | El SII rechaza la segunda, o hay dos documentos distintos con el mismo número. | Reserva el folio con una transacción en tu base de datos. |
| No se guardó el Track ID | No puedes saber si el documento fue aceptado. | Guárdalo apenas lo recibes. |
| Se construyó de nuevo un documento ya enviado | Hay dos XML distintos para el mismo folio. | Si falla el envío, reintenta el **mismo** sobre. Solo se construye de nuevo cuando el SII lo rechazó. |
| Se volvió a emitir un documento rechazado con otro folio | El folio del documento rechazado queda sin usar en el CAF. | Emite el documento corregido con el mismo folio. |
| No se guardó el XML | Pierdes el respaldo legal del documento. | Guarda cada XML emitido por al menos 6 años. |
| Se agotaron los folios | No se puede emitir. | Solicita un nuevo CAF antes de que se agote el actual. |

> [!TIP] ¿No encuentras tu error?
>
> Revisa la [solución de problemas](https://www.apigateway.cl/docs/solucion-de-problemas) de la documentación. Si el problema sigue, [abre un ticket](https://www.apigateway.cl/help) indicando la operación, la hora de la llamada y el mensaje de `detail` (sin enviar tu certificado ni tu token).


    
---

## Buenas prácticas

Cómo diseñar tu integración para que sea segura, confiable y fácil de mantener, y la lista de verificación antes de emitir en producción.

# Buenas prácticas

## Guarda lo que necesitas, y nada más

Por cada documento emitido, guarda en tu base de datos:

| Dato | Por qué |
|------|---------|
| Emisor, tipo de documento y folio | Identifican el documento de forma única. |
| Ambiente (certificación o producción) | Para no mezclar documentos de prueba con documentos reales. |
| El XML del DTE (`document_xml`) | Es el documento con validez legal. |
| El XML del sobre enviado al SII | Para reintentar el envío o responder ante el SII. |
| Track ID y fecha de envío | Para consultar el estado. |
| Estado y fecha de la última consulta | Para saber qué falta. |
| Fecha de emisión (`FchEmis`) | Para referenciar el documento en una nota de crédito o débito (`FchRef`) y para verificarlo en el SII. |
| Totales (neto, IVA, exento, total) | Para tus reportes, sin tener que leer el XML. |

No guardes las respuestas completas de la API: incluyen datos del certificado y del CAF que no necesitas.

## Controla los folios con cuidado

- **Reserva** cada folio dentro de una transacción antes de construir el documento.
- **Nunca reutilices** el folio de un documento aceptado, aunque tenga reparos. El de un documento **rechazado** sí: emítelo corregido con el mismo folio.
- **Monitorea** los folios disponibles y solicita un CAF nuevo cuando queden cerca del 20%.
- **Revisa el vencimiento** de los CAF: un CAF vencido no sirve, aunque le queden folios.
- Si tienes folios que nunca usarás (por ejemplo, de un CAF que vence), **anúlalos** con el recurso `caf/anular`.

## Separa la emisión del seguimiento

Cuando el usuario confirma la venta, divide el trabajo en tres etapas:

| Etapa | Cuándo se ejecuta | Qué hace |
|-------|-------------------|----------|
| **1. Emisión** | En línea, al confirmar la venta | Reserva el folio, construye el DTE, arma el sobre, lo envía y guarda el Track ID. |
| **2. Seguimiento** | En segundo plano | Consulta los estados pendientes y los actualiza. |
| **3. Entrega** | Cuando el documento es aceptado | Genera el PDF y lo entrega al cliente. Si el receptor es una empresa que emite documentos electrónicos, le envía además el XML a su correo de intercambio. |

Así ningún usuario espera al SII, y cada parte se puede reintentar por separado.

## Diseña para los fallos

- Usa **tiempos de espera** generosos (60 a 120 segundos): el SII a veces responde lento.
- **Reintenta** los envíos y las consultas con esperas crecientes, no en un ciclo inmediato.
- Haz que cada paso sea **repetible** sin efectos duplicados: si vuelves a enviar un sobre que ya tiene Track ID, primero consulta su estado.
- Registra en tus logs la operación, el código HTTP y el `detail` de cada error.

## Protege los secretos

| Secreto | Recomendación |
|---------|---------------|
| Token de API Gateway | En variables de entorno o un almacén de secretos. Regenéralo si sospechas que se filtró. |
| Certificado digital y su contraseña | Cifrado, en un almacén de secretos. Nunca en el código ni en el navegador. |
| CAF | Contiene la llave para timbrar. Guárdalo con el mismo cuidado que el certificado. |

Todas las llamadas a la API deben salir de **tu servidor**, nunca desde una app web o móvil del usuario.

## Valida los datos en tu sistema

Muchos rechazos se evitan validando al registrar los datos, mucho antes de emitir:

- RUT con dígito verificador correcto.
- Largos máximos (razón social 100, giro del receptor 40, dirección 70, comuna 20, nombre del ítem 80).
- Precios y cantidades mayores que cero.
- Para facturas: giro, dirección y comuna del receptor.

## Mantén separados los ambientes

- Usa configuraciones distintas para certificación y producción (CAF, resolución y ambiente).
- Marca los documentos de certificación en tu base de datos para que nunca aparezcan en reportes reales.
- Antes de cambiar a producción, revisa la [lista de verificación](#lista-de-verificación-para-producción).

## Respalda

La ley exige conservar los documentos tributarios por al menos **6 años**. Incluye los XML en tus respaldos y prueba de vez en cuando que puedes recuperarlos. API Gateway no guarda una copia por ti.

## Lista de verificación para producción

Antes de emitir el primer documento con validez tributaria, revisa cada punto.

### La empresa emisora

- La empresa terminó la certificación y el SII la autorizó a emitir con software de mercado.
- Tienes el **número y la fecha de la resolución** de producción.
- La persona del certificado digital está autorizada en el SII para la empresa.
- El certificado digital está vigente y sabes cuándo vence.
- Tienes **CAF de producción** para cada tipo de documento que vas a emitir.

### Tu configuración

- `options.environment` es `0` en todas las llamadas al SII de producción.
- La resolución del sobre (`autorizacion_dte`) es la de producción, no la de certificación.
- Los CAF de producción están cargados y separados de los de certificación.
- La conexión tiene créditos y los productos necesarios activos.
- Las boletas se envían y se consultan con `sii_boleta`; las facturas, notas y guías, con `sii_dte`.

### Tu sistema

- Aplica las prácticas de esta página: folios reservados con una transacción, lo que se guarda de cada documento, seguimiento en segundo plano, reintentos con esperas crecientes, secretos protegidos, ambientes separados y respaldos.
- Hay una alerta cuando quedan pocos folios o el certificado está por vencer.

### Entrega y correcciones

- El PDF se genera y se entrega al cliente.
- A los receptores que son empresas que emiten documentos electrónicos, tu sistema les envía el XML a su correo de intercambio.
- Sabes cómo emitir una nota de crédito para corregir un documento.

### La primera emisión real

1. Emite **un solo documento** de bajo monto y con datos que conozcas bien.
2. Consulta su estado hasta que sea aceptado.
3. Revisa el PDF y verifica el documento: las facturas, notas y guías con `sii/dte/emitidos/verificar`, y las boletas con `sii_boleta/validateDocument`.
4. Si todo está bien, habilita la emisión para el resto.

> [!WARNING] En producción no hay vuelta atrás
>
> Un documento aceptado en producción tiene validez tributaria: no se borra, solo se corrige con notas de crédito o débito. Haz tus pruebas en certificación.

> [!TIP] ¿Terminaste el curso?
>
> Pon a prueba lo que aprendiste con la [autoevaluación](https://www.apigateway.cl/academy/emision-de-dte/ponte-a-prueba/autoevaluacion).


    

---
Última actualización el 05/11/2026