Manual del Sistema DTEM

1. Introducción

1.1. Propósito y Alcance

Este documento proporciona una descripción técnica detallada del sistema DTEM, una plataforma para la emisión, recepción y gestión de Documentos Tributarios Electrónicos (DTE). Su propósito es servir como una referencia central para el personal técnico responsable del desarrollo, mantenimiento, despliegue y auditoría del sistema.

El manual cubre la arquitectura técnica, los componentes de software, los flujos de datos, los procedimientos de configuración, despliegue y las pautas de mantenimiento. No cubre la funcionalidad desde la perspectiva del usuario final, la cual se detalla en el Manual de Usuario.

1.2. Audiencia

Este manual está dirigido a:

Ingenieros de Software y Desarrolladores: Para comprender la estructura del código, las interacciones entre componentes y cómo extender la funcionalidad.
Administradores de Sistemas y DevOps: Para desplegar, configurar, monitorear y mantener la infraestructura del sistema.
Arquitectos de Software: Para tener una visión global del diseño del sistema y tomar decisiones estratégicas.
Auditores Técnicos: Para evaluar la seguridad, el rendimiento y el cumplimiento de la plataforma.

2. Arquitectura del Sistema

2.1. Visión General

El sistema DTEM está diseñado siguiendo un enfoque de microservicios. Esta arquitectura fue elegida para facilitar la escalabilidad independiente de los componentes, mejorar la resiliencia y permitir un desarrollo y despliegue más ágil.

Los servicios se comunican entre sí a través de APIs REST síncronas y, para procesos asíncronos como la generación de PDFs o el envío al SII, se utiliza una cola de mensajes (RabbitMQ) para desacoplar los componentes.

2.2. Diagrama de Arquitectura

El siguiente diagrama ilustra los componentes principales del sistema y sus interacciones:

graph TD
    subgraph "Clientes"
        A[Usuario Web / App]
        B[Sistema ERP Externo]
    end

    subgraph "Plataforma DTEM"
        C[API Gateway]
        D[Servicio de Autenticación]
        E[Servicio de Procesamiento de DTE]
        F[Servicio de Generación de PDF]
        G[Servicio Conector SII]
        H[Base de Datos Principal - PostgreSQL]
        I[Cola de Mensajes - RabbitMQ]
        J[Almacenamiento de Archivos - S3/MinIO]
    end

    subgraph "Sistemas Externos"
        K[Servicio de Impuestos Internos - SII]
    end

    A --> C
    B --> C

    C --> D{Autenticación}
    C --> E{Procesamiento DTE}

    E --> H
    E --> I
    E --> J

    I --> F
    I --> G

    F --> J
    G --> K

3. Componentes Principales

3.1. API Gateway

Responsabilidad: Punto de entrada único para todas las solicitudes de clientes. Enruta las peticiones al microservicio correspondiente, gestiona el balanceo de carga, la autenticación (junto al Servicio de Autenticación) y el logging centralizado.
Tecnologías: Nginx con OpenResty / Spring Cloud Gateway.

3.2. Servicio de Autenticación

Responsabilidad: Gestiona el registro, inicio de sesión y la generación/validación de tokens de acceso (JWT).
Tecnologías: Node.js, Express, JWT.

3.3. Servicio de Procesamiento de DTE

Responsabilidad: Lógica de negocio principal. Valida, crea, almacena y gestiona el ciclo de vida de los DTE. Publica eventos en la cola de mensajes para tareas asíncronas.
Tecnologías: Java, Spring Boot, Hibernate.

3.4. Servicio de Generación de PDF

Responsabilidad: Escucha eventos de la cola de mensajes para generar las representaciones gráficas (PDF) de los DTE. Almacena los archivos generados en el sistema de almacenamiento.
Tecnologías: Go, wkhtmltopdf.

3.5. Servicio Conector SII

Responsabilidad: Gestiona toda la comunicación con el Servicio de Impuestos Internos (SII), incluyendo el envío de DTE, la consulta de estados y la obtención del Folio (CAF).
Tecnologías: .NET Core, SOAP/REST.

3.6. Base de Datos Principal

Responsabilidad: Almacenamiento persistente de toda la información de negocio: usuarios, empresas, DTEs, folios, etc.
Tecnologías: PostgreSQL.

3.7. Cola de Mensajes

Responsabilidad: Facilita la comunicación asíncrona y desacoplada entre los servicios. Garantiza la entrega de tareas como la generación de PDFs y el envío al SII.
Tecnologías: RabbitMQ.

3.8. Almacenamiento de Archivos

Responsabilidad: Almacena los archivos XML de los DTE y sus representaciones PDF.
Tecnologías: Compatible con AWS S3 o MinIO (auto-hospedado).

4. Flujos de Datos Clave

4.1. Flujo de Emisión de un DTE

Este flujo describe el proceso desde que un cliente solicita la creación de un DTE hasta que es enviado al SII.

sequenceDiagram
    participant C as Cliente
    participant GW as API Gateway
    participant Auth as Serv. Autenticación
    participant Proc as Serv. Procesamiento
    participant MQ as Cola de Mensajes
    participant PDF as Serv. PDF
    participant SII as Serv. Conector SII

    C->>GW: POST /api/v1/dte (con datos del DTE y Token)
    GW->>Auth: Validar Token JWT
    Auth-->>GW: Token Válido
    GW->>Proc: Reenviar POST /dte
    Proc->>Proc: Validar datos y folios (CAF)
    Proc->>DB: Guardar DTE en estado "Generado"
    Proc-->>C: 201 Created (con ID del DTE)
    Proc->>MQ: Publicar evento "dte_creado"
    MQ-->>PDF: Consumir evento "dte_creado"
    PDF->>PDF: Generar PDF del DTE
    PDF->>FS: Guardar PDF en Almacenamiento
    MQ-->>SII: Consumir evento "dte_creado"
    SII->>SII: Preparar y firmar XML
    SII->>Ext: Enviar DTE al SII
    SII->>DB: Actualizar estado del DTE a "Enviado"

5. Integraciones con Sistemas Externos

5.1. Servicio de Impuestos Internos (SII)

Protocolo: Se utiliza principalmente SOAP para los servicios de autenticación y envío de DTE, y REST para consultas de estado más modernas.
Autenticación: Se utiliza un certificado digital (token) obtenido del servicio de autenticación del SII. Este token tiene una duración limitada y debe ser renovado periódicamente.
Endpoints Principales:
- https://palena.sii.cl/DTEWS/CrSeed.jws: Para obtener la semilla de autenticación.
- https://palena.sii.cl/DTEWS/GetTokenFromSeed.jws: Para obtener el token de sesión.
- https://palena.sii.cl/cgi_dte/UPL/DTEUpload: Endpoint para el envío de DTE.
Manejo de Errores: El Conector SII debe ser capaz de interpretar los códigos de error del SII y reintentar envíos en caso de fallos transitorios.

5.2. Sistemas ERP

El sistema DTEM ofrece dos mecanismos para la integración con sistemas de planificación de recursos empresariales (ERP):

API REST: El ERP puede consumir la API REST de DTEM (documentada en el manual correspondiente) para emitir documentos, consultar estados y descargar PDFs.
Webhooks: DTEM puede configurarse para notificar a un endpoint del ERP sobre eventos importantes, como la aceptación o rechazo de un DTE por parte del SII.

6. Requisitos Técnicos

6.1. Requisitos de Hardware (Recomendado)

Servidor de Aplicaciones: 4 vCPU, 16 GB RAM, 100 GB Disco SSD.
Base de Datos: 2 vCPU, 8 GB RAM, 200 GB Disco SSD (con backups configurados).

6.2. Requisitos de Software

Sistema Operativo: Linux (Ubuntu 20.04 LTS o superior, CentOS 8 o superior).
Orquestación: Docker y Docker Compose.
Base de Datos: PostgreSQL 14+.
Cola de Mensajes: RabbitMQ 3.9+.
Runtimes: Java 17 (OpenJDK), Node.js 18.x, .NET 6.

7. Configuración del Entorno

El sistema se configura principalmente a través de variables de entorno. A continuación, se listan las más importantes.

Variable	Descripción	Ejemplo
`DATABASE_URL`	URL de conexión a la base de datos PostgreSQL.	`postgres://user:pass@host:5432/dtem_db`
`RABBITMQ_URL`	URL de conexión a RabbitMQ.	`amqp://user:pass@host:5672`
`JWT_SECRET`	Clave secreta para firmar los tokens JWT.	`una-clave-muy-secreta-y-larga`
`SII_CERT_PATH`	Ruta al archivo del certificado digital (.pfx) para el SII.	`/etc/dtem/certs/certificado.pfx`
`SII_CERT_PASS`	Contraseña del certificado digital.	`password_del_certificado`
`STORAGE_TYPE`	Tipo de almacenamiento de archivos (`s3` o `minio`).	`minio`
`STORAGE_ENDPOINT`	Endpoint del servicio de almacenamiento.	`http://minio:9000`
`STORAGE_ACCESS_KEY`	Access Key para el almacenamiento.	`access_key`
`STORAGE_SECRET_KEY`	Secret Key para el almacenamiento.	`secret_key`
`STORAGE_BUCKET`	Nombre del bucket donde se guardarán los archivos.	`dtem-files`

8. Despliegue y Mantenimiento

8.1. Proceso de Despliegue con Docker

Clonar el Repositorio:

git clone <url-del-repositorio>
cd dtem

Configurar el Entorno:
- Crear un archivo .env en la raíz del proyecto.
- Añadir y configurar todas las variables de entorno listadas en la sección 7.
Levantar los Servicios:
```
docker-compose up -d
```
Este comando construirá las imágenes de los microservicios (si no existen) y levantará todos los contenedores en segundo plano.
Verificar el Estado:
```
docker-compose ps
```
Todos los servicios deberían aparecer con el estado Up.

8.2. Procedimientos de Mantenimiento

Backup de la Base de Datos: Se recomienda realizar backups diarios de la base de datos PostgreSQL utilizando pg_dump.
```
pg_dump -U <user> -h <host> <db_name> > backup_$(date +%F).sql
```
Logs: Los logs de los contenedores pueden ser inspeccionados con docker-compose logs -f <nombre_del_servicio>. Para producción, se recomienda centralizar los logs en una plataforma como ELK (Elasticsearch, Logstash, Kibana) o Grafana Loki.
Monitoreo: Cada microservicio expone un endpoint /actuator/health que puede ser utilizado por herramientas de monitoreo (como Prometheus) para verificar el estado de salud del servicio.

9. Seguridad

9.1. Autenticación y Autorización

El acceso a la API está protegido por Tokens JWT. Los clientes deben obtener un token a través del Servicio de Autenticación y enviarlo en la cabecera Authorization: Bearer <token> en cada solicitud.
El sistema maneja roles y permisos para restringir el acceso a ciertas operaciones.

9.2. Seguridad de Datos

En Tránsito: Toda la comunicación entre el cliente y el API Gateway, así como la comunicación con el SII, debe estar protegida con TLS (HTTPS).
En Reposo: La información sensible en la base de datos, como las credenciales del SII, debe estar encriptada.

10. Apéndices

10.1. Glosario

DTE: Documento Tributario Electrónico.
SII: Servicio de Impuestos Internos de Chile.
CAF: Código de Autorización de Folios. Archivo que contiene los folios autorizados por el SII para emitir DTEs.
JWT: JSON Web Token.

10.2. Troubleshooting

Error 502 Bad Gateway: Generalmente indica que el API Gateway no puede comunicarse con un microservicio interno. Verificar que todos los contenedores estén activos y revisando los logs del Gateway.
Error de Autenticación con el SII: Verificar que el certificado digital sea válido, no esté expirado y que la contraseña sea correcta. Asegurarse de que el servidor tenga la hora sincronizada correctamente.
La generación de PDF falla: Revisar los logs del Servicio de Generación de PDF. Puede ser un problema con la plantilla del DTE o con la disponibilidad del servicio wkhtmltopdf.