Guía definitiva para integrar un ERP multi-tenant con SII Chile y emitir DTE
Una guía simple y completa para pasar de una POC en Postman a una integración segura entre Neges, un adapter DTE y los servicios del SII: semilla, token, firma, envío, TRACKID, estados y operación por tenant.
Esta guía explica la arquitectura y el flujo usando como base el repositorio público Neges SII DTE Postman POC. La idea central: integrar facturación electrónica con el SII no es sólo llamar un endpoint; un ERP multi-tenant debe generar XML, firmar documentos, cuidar certificados, administrar CAF y folios, guardar respuestas, mostrar estados claros y separar estrictamente los datos de cada empresa.
Resumen ejecutivo
La forma sana de integrar Neges con el SII es separar responsabilidades: el usuario opera desde el ERP, el backend valida la venta y un adapter DTE se encarga de XML, firma, autenticación, envío y consulta de estados.
El repositorio público de esta guía trae una colección Postman, ambientes con variables placeholder, una guía técnica y diagramas para probar el flujo completo en forma controlada. Es el laboratorio del artículo, no sólo una referencia al final.
Postman sirve para esa POC. Ayuda a entender la secuencia real: pedir semilla, firmarla, pedir token, subir el EnvioDTE firmado, recibir TRACKID y consultar el estado. Pero Postman no debe ser el runtime productivo ni guardar certificados reales.
En producción, el flujo debe vivir en backend. El certificado digital, la contraseña, los CAF, los folios y los XML firmados son materiales sensibles. Si viajan al frontend o quedan como variables Postman, la integración queda frágil desde el primer día.
Repositorio base de la guía
El punto de partida práctico es el repositorio público Neges SII DTE Postman POC. Ahí están la colección Postman, los ambientes de certificación y producción con valores de ejemplo, la propuesta de adapter multi-tenant, la guía técnica y los diagramas Mermaid.
Úsalo para probar el recorrido técnico antes de automatizarlo dentro del ERP. La colección permite observar qué se envía, qué responde el SII y qué datos debe guardar Neges para transformar una prueba manual en una integración backend segura.
Arquitectura base
La arquitectura recomendada tiene cinco piezas: frontend ERP, backend ERP/API, adapter DTE, almacenamiento seguro por tenant y servicios del SII. La venta nace en Neges, pero la emisión tributaria se resuelve en una capa especializada.
Quién hace qué
| Actor | Responsabilidad simple | Qué no debería hacer |
|---|---|---|
| Usuario u operador | Crea la venta, revisa datos del cliente y solicita emitir el documento. | No firma XML ni manipula certificados. |
| Frontend ERP | Muestra acciones, estados y errores entendibles para el usuario. | No guarda tokens SII, CAF, claves ni certificados. |
| Backend ERP/API | Valida permisos, tenant, venta, totales, cliente y reglas internas. | No mezcla datos tributarios entre empresas. |
| Adapter DTE | Genera XML, firma, pide token, sube el envío, consulta estados y registra auditoría. | No expone secretos ni deja operaciones sin trazabilidad. |
| Storage por tenant | Guarda certificado cifrado, CAF, XML, PDF, TRACKID, estado y logs. | No comparte archivos ni rangos de folio entre tenants. |
| SII Chile | Entrega semilla, valida token, recibe el EnvioDTE y responde estados. | No corrige datos de negocio del ERP. |
Flujo de emisión paso a paso
El usuario crea una venta
Neges valida cliente, productos, impuestos, totales y tenant activo antes de intentar emitir.
El backend arma la solicitud de emisión
La venta se transforma en una orden interna para el adapter DTE. Aquí ya debe venir claro el tipo de documento, folio, receptor y montos.
El adapter obtiene datos tributarios del tenant
Busca razón social, RUT, giro, certificado digital, CAF, rango de folios y ambiente SII: certificación o producción.
Se genera el XML DTE
El adapter construye el XML con el formato que espera el SII y lo deja trazado como versión preliminar.
Se firma el XML
La firma ocurre en backend usando el certificado del tenant. Ese certificado no debe salir al navegador.
Se solicita semilla al SII
El adapter llama a CrSeed para obtener una semilla temporal.
Tip: La semilla dura poco. El flujo debe firmarla y pedir token inmediatamente.Se firma la semilla
El adapter firma la semilla con el certificado del tenant para demostrar identidad ante el SII.
Se solicita token
El adapter envía la semilla firmada a GetTokenFromSeed y recibe un token para las siguientes llamadas.
Se sube el EnvioDTE firmado
El XML firmado se envía al endpoint de upload del SII. Si el SII lo recibe, responde un TRACKID.
Se guarda la respuesta
Neges registra XML, respuesta, TRACKID, estado inicial y evento de auditoría.
Se consulta el estado
El adapter consulta QueryEstUp y, cuando corresponde, QueryEstDte o QueryEstDteAv para conocer el resultado tributario.
Se entrega el documento al cliente
Cuando el estado lo permite, Neges genera o vincula el PDF, actualiza la venta y deja el documento disponible para el cliente.
Autenticación SII explicada simple
El SII usa una autenticación en dos pasos: primero entrega una semilla y luego valida que esa semilla vuelva firmada con un certificado digital válido. Si la firma pasa, el SII devuelve un token.
En simple: la semilla es el desafío, la firma es la prueba de identidad y el token es el permiso temporal para enviar o consultar documentos.
Servicios SII que aparecen en la POC
| Uso | Servicio o endpoint | Para qué sirve |
|---|---|---|
| Semilla | CrSeed.getSeed | Obtiene el desafío que luego debe firmarse. |
| Token | GetTokenFromSeed.getToken | Envía la semilla firmada y obtiene un token temporal. |
| Upload | DTEUpload | Sube el archivo EnvioDTE ya generado y firmado. |
| Estado de envío | QueryEstUp | Consulta el resultado del envío usando el TRACKID. |
| Estado del DTE | QueryEstDte | Consulta un documento específico por emisor, receptor, tipo, folio, fecha y monto. |
| Estado avanzado | QueryEstDteAv | Consulta avanzada cuando el flujo requiere más datos del timbre o TED. |
Qué debe guardar Neges por empresa
| Dato | Por qué importa | Cuidado operativo |
|---|---|---|
| RUT, razón social, giro y dirección | Identifican al emisor del DTE. | Deben coincidir con la información tributaria habilitada. |
| Certificado digital | Permite firmar semilla y documentos. | Debe cifrarse y tener control de vencimiento. |
| CAF y rangos de folios | Autorizan la numeración de documentos. | Requieren locking para no duplicar folios. |
| Ambiente SII | Separa certificación de producción. | No mezclar pruebas con emisión real. |
| XML sin firmar y XML firmado | Permiten auditoría y diagnóstico. | Guardar referencias seguras, no archivos sueltos sin control. |
| TRACKID y respuestas SII | Conectan el documento interno con el estado tributario. | Guardar respuesta cruda y estado normalizado. |
| PDF o representación impresa | Es lo que ve el cliente final. | Debe reflejar el documento emitido, no una venta preliminar. |
API interna recomendada para el adapter DTE
| Endpoint interno | Uso | Quién debería llamarlo |
|---|---|---|
| /api/dte/health | Verifica que el adapter esté activo. | Monitoreo o backend. |
| /api/dte/tenants/:tenantSlug/config | Configura datos DTE del tenant. | Admin autorizado. |
| /api/dte/sii/seed | Obtiene semilla desde SII. | Backend o flujo técnico. |
| /api/dte/sii/sign-seed | Firma semilla en backend. | Sólo adapter. |
| /api/dte/sii/token | Obtiene token SII. | Sólo adapter. |
| /api/dte/documents/preview | Genera XML preliminar sin enviar. | Backend ERP para validación. |
| /api/dte/documents/emit | Ejecuta emisión completa. | Backend ERP después de validar la venta. |
| /api/dte/documents/:internalDteId | Consulta documento interno y estado. | Backend ERP o UI privada. |
| /api/dte/documents/:internalDteId/refresh-status | Consulta SII y actualiza estado local. | Job, cola o acción de soporte. |
Estados internos sugeridos
Cómo mostrar estados sin confundir al usuario
El usuario no necesita ver todos los detalles SOAP. Necesita entender si el documento está listo, esperando respuesta, rechazado o requiere una acción.
- Borrador: la venta existe, pero aún no se intentó emitir.
- Firmado: el XML ya está preparado, pero todavía no se confirma recepción SII.
- Enviado: el SII recibió el archivo y entregó TRACKID.
- En revisión: falta consultar o recibir estado final.
- Aceptado: el documento puede entregarse al cliente.
- Rechazado: hay que corregir datos, folio, firma, formato o condición tributaria.
- Anulado o referenciado: el documento quedó ligado a una nota de crédito, débito u otro flujo posterior.
Cómo usar el repositorio POC en Postman
Abre o clona el repositorio
Trabaja desde github.com/tannynogales/neges-sii-dte-postman-poc para tener la colección, ambientes, guía técnica y diagramas en el mismo lugar.
Importa la colección
Carga postman/Neges-SII-DTE-POC.postman_collection.json en Postman.
Importa un ambiente
Parte con postman/SII-Certificacion.postman_environment.json. Producción debe quedar para una etapa posterior.
Completa variables demo
Revisa RUT empresa, RUT firmante, receptor, tipo DTE, folio, fecha, monto y tenant_slug.
Pide semilla
Ejecuta CrSeed.getSeed y guarda seed_unsigned_xml.
Firma fuera de Postman
Usa un script controlado o el adapter local. Postman puede orquestar, pero no debe custodiar certificados reales.
Pide token
Ejecuta GetTokenFromSeed.getToken con la semilla firmada.
Sube un EnvioDTE firmado
Selecciona el XML final firmado y ejecuta DTEUpload.
Consulta estados
Usa QueryEstUp con el TRACKID y luego QueryEstDte si necesitas validar el documento específico.
Seguridad mínima antes de producción
La integración DTE tiene riesgo técnico y tributario. Un error puede exponer certificados, duplicar folios, emitir documentos inválidos o mostrar información de una empresa a otra.
- Validar tenant y permisos en cada emisión, consulta y descarga.
- Cifrar certificados en reposo y evitar logs con claves o XML sensibles.
- Usar locks o transacciones al asignar folios.
- Separar storage por tenant y por ambiente.
- Guardar request, response y estado normalizado para auditoría.
- Implementar colas y reintentos para caídas temporales del SII.
- Alertar certificados vencidos, CAF agotados y rechazos repetidos.
- Probar primero en certificación y completar el proceso formal antes de producción.
Roadmap recomendado
Fase 0: entender el flujo
Leer documentación SII, revisar WSDL, preparar datos de prueba y confirmar tipos DTE iniciales.
Fase 1: POC Postman
Probar semilla, firma, token, upload, TRACKID y consultas sin tocar ventas reales.
Fase 2: adapter mínimo
Implementar firma segura, generación XML, upload, persistencia de respuestas y estado interno.
Fase 3: integración ERP
Conectar ventas reales, folios, clientes, PDF, notificaciones y estado visible en la UI.
Fase 4: certificación y producción
Completar certificación SII, habilitar empresas, monitorear rechazos y preparar soporte operativo.
Checklist antes de decir que la integración está lista
- Cada tenant tiene configuración tributaria propia.
- El certificado nunca sale del backend seguro.
- El CAF y los folios se asignan con control transaccional.
- El XML se genera, firma y guarda con trazabilidad.
- El token SII se obtiene desde semilla firmada, no desde valores pegados a mano.
- El upload guarda TRACKID y respuesta original.
- Los estados SII se traducen a estados simples para la UI.
- Los errores quedan accionables para soporte y no sólo como XML crudo.
- Postman queda como herramienta de diagnóstico, no como dependencia productiva.
- El repositorio público no contiene certificados, claves, tokens ni XML reales.
Recursos relacionados
¿Te fue útil este contenido?
Tu feedback nos ayuda a mejorar la documentación de Neges.
¿No encuentras lo que buscas?
Conversa con nuestro equipo de soporte en español. Respondemos por WhatsApp, correo o ticket en menos de 24 horas hábiles.