Análisis técnico · SMAC Control

Endpoint público para subida automática de documentos

Para: Gonzalo (ASAP Uruguay) · Pedido de: Agustín (ITNOVA) · 15 de mayo de 2026
Desarrollo: ASAP Uruguay Cliente final: SMAC (usuario del sistema SMAC Control) Proveedor / integrador: ITNOVA (quien solicita habilitar la integración)

Resumen ejecutivo

El endpoint para subir documentos existe y funciona, pero hoy está protegido con login de usuario (JWT) y solo es accesible desde la red interna. No existe una variante pública pensada para integraciones externas.

Habilitar uno es técnicamente viable y de esfuerzo acotado porque toda la lógica de negocio (validación, guardado, registro en DB) ya está implementada. Lo que falta es: un mecanismo de autenticación apto para servicios (API key), exponer la URL al exterior y agregar validaciones de seguridad. Estimación MVP: 3 a 5 días de desarrollo (≈ 24 a 40 horas), sin contar la coordinación de infraestructura/red.

1. ¿Existe hoy un endpoint público?

NO
No existe ningún endpoint accesible desde fuera sin login de usuario humano. Todos los endpoints que manipulan operaciones requieren un token JWT generado por /api/auth/signin, válido por 24 horas, y emitido a usuarios reales con rol ROLE_USER o ROLE_ADMIN.
SÍ
Existe el endpoint REST POST /api/archivos/operaciones/{operacionId} que ya implementa toda la lógica: recibe el archivo, lo guarda en disco, crea el registro asociado a la operación. Es el mismo que usa la UI hoy. La lógica de negocio está hecha; lo que falta es exponerla de forma segura a un consumidor automatizado.

2. ¿Cómo funciona hoy la subida?

AspectoDetalle
Endpoint POST /api/archivos/operaciones/{operacionId}
OperacionItemsController.java:78
Autenticación JWT en header Authorization: Bearer <token>
Token emitido por POST /api/auth/signin (usuario + password)
WebSecurityConfig.java:55-67
Parámetros multipart/form-data con: file, tiposItems, realname, descripcion, pago, y opcionales: nroDocumento, fechaDocumento, moneda, monto, iva, montoIva, pais
Identificador de operación operacionId tipo Long (numérico). El sistema externo necesita conocerlo para apuntar la subida.
Almacenamiento del archivo A nivel de código, el backend escribe al filesystem (POSIX) usando FileOutputStream. No hay cliente S3 ni dependencia AWS en el código (búsqueda exhaustiva: 0 matches).
Ruta configurada: /usr/src/files/{operacionId}/{fileName}
DocumentDao.java:38, 236-265 · application-prod.properties:1
Caveat: esa ruta dentro del contenedor de producción podría estar montada como volumen Docker, EFS, EBS o incluso un bucket S3 vía s3fs. A confirmar con quien administre la infra.
Metadata Se persiste en MySQL, tabla de items de operación, vinculada al operacionId.

Corrección a un supuesto inicial: el código del backend no usa S3. Escribe al filesystem vía FileOutputStream. Lo que no podemos confirmar sin acceder a la infra es si ese filesystem está respaldado por disco local, EFS, EBS o un bucket S3 montado. Para el diseño del endpoint público es indistinto, pero conviene preguntárselo a quien administre el deploy antes de prometer SLAs de disponibilidad o tamaños máximos.

3. Qué hace falta para exponer un endpoint público (MVP)

TareaDetalleEsfuerzo
Endpoint nuevo separado Crear, p.ej., POST /api/integrations/archivos/operaciones/{operacionId} que reutilice el service existente (DocumentService.save + OperacionItemsService.save). Mantener el endpoint actual intacto. Bajo
Autenticación por API key Filtro Spring que valide un header X-API-Key contra una lista de claves emitidas por integrador. Permite revocación y trazabilidad por origen. Bajo
Whitelist en WebSecurityConfig Permitir el path nuevo sin JWT, pero exigiendo el filtro de API key. Bajo
Validaciones extra Existencia y vigencia del operacionId, tamaño máximo, tipo MIME, sanitización de nombre de archivo. Bajo
Auditoría Registrar en log/DB qué integrador subió qué archivo a qué operación y cuándo (importante para trazabilidad aduanal). Bajo
Exposición de red Hoy el sistema está detrás de VPN. Para que ITNOVA/Aduana llegue al endpoint hace falta: o bien exponer una URL pública (con TLS, firewall, idealmente WAF), o bien que el integrador entre por VPN. Decisión y ejecución de infraestructura, no de desarrollo. Medio
Documentación para el integrador Spec corta del endpoint (curl de ejemplo, parámetros, códigos de error). Bajo

Total estimado para el MVP de desarrollo: 3 a 5 días (≈ 24 a 40 horas). El bloqueante práctico suele ser la coordinación de infraestructura, no el código.

4. Decisiones que necesitamos de Agustín

1. ¿Quién resuelve la exposición de red?
¿ITNOVA se conecta por VPN al entorno actual, o se expone la URL al exterior? Si es lo segundo, hace falta involucrar al equipo de infra para abrir el firewall, montar TLS y definir un dominio.
2. ¿Cómo conoce ITNOVA el operacionId?
El sistema externo tiene que saber a qué operación apuntar cada archivo. Opciones: (a) ITNOVA lo recibe del flujo de Aduana, (b) le agregamos un endpoint de lookup por algún identificador externo (ej. numeroRef de cliente + folio/DUA), (c) algún otro acuerdo.
3. ¿Cuántos integradores se prevén?
Si es solo ITNOVA, una API key única hardcodeada en config alcanza. Si se prevén varios organismos, conviene un mini-CRUD de keys por integrador desde el inicio (suma poco esfuerzo).
4. ¿Hay requisitos de auditoría/compliance aduanal?
Esto puede cambiar qué tan estrictos sean los logs y la retención.

5. Sobre la alternativa de scraping

La opción que ITNOVA barajaba —automatizar clics sobre la UI— resuelve el problema sin tocar el sistema, pero a un costo alto a mediano plazo:

Un endpoint dedicado, con el esfuerzo estimado, evita todo esto y deja la integración mantenible.

6. Recomendación

PROPUESTA
Confirmarle a Agustín que se puede, con una primera fase MVP enfocada en lo mínimo viable: endpoint REST autenticado por API key, sobre la lógica existente. Antes de cotizar en detalle, necesitamos las decisiones de la sección 4 — sobre todo la de infraestructura, porque condiciona el alcance y los tiempos.