Buenas prácticas

Guarda lo que necesitas, y nada más

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

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:

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

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.

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.