---
title: "Buenas prácticas"
description: "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."
type: "academy"
category: "lesson"
tags: []
authors: [Anonymous]
date: "2026-11-05"
last_update: "2026-11-05"
time_minutes: 6
draft: false
unlisted: false
url: "https://www.apigateway.cl/academy/emision-de-dte/produccion/buenas-practicas"
---

# 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