Futura100 1.5 Multiempresa

¿Qué es Futura100?

Futura100 es una plataforma de facturación electrónica y administración de documentos electrónicos (DE) diseñada para el marco tributario paraguayo. Genera, firma y transmite documentos al SIFEN (Sistema Integrado de Facturación Electrónica Nacional) de la Subsecretaría de Estado de Tributación, y produce el KUDE (representación gráfica del documento electrónico) para su entrega al receptor.

La edición 1.5 Multiempresa permite operar varias empresas emisoras desde una misma instalación, con aislamiento de datos por empresa.

Módulos funcionales

• Emisión de documentos electrónicos — factura electrónica, notas de crédito y débito, nota de remisión y autofactura.
• Controlador de DE — orquesta el envío al SIFEN, el manejo de lotes y la conciliación de estados y eventos.
• Servicio KUDE — generación del PDF de representación gráfica y gestión de logotipos.
• Editor de KUDE autogestionado — personalización visual de la plantilla del KUDE por parte del cliente.
• Servicio de envío por correo — distribución del documento y del KUDE a los receptores mediante una cuenta SMTP que provee cada empresa (ver Envío de correo).
• Firmador de PDF de recibos — firma de comprobantes de cobro.
• Panel de administración — gestión de empresas, usuarios, certificados, timbrados, parámetros y monitoreo.
• Portal — front-end público de consulta y acceso de usuarios.
• Integraciones — Web Service (REST y SOAP) para conectar sistemas del cliente (ERP, core bancario, POS). Ver Integración (Web Service).

Arquitectura de la plataforma

Futura100 1.5 es una aplicación distribuida compuesta por un conjunto de microservicios Node.js detrás de un balanceador / proxy inverso, con PostgreSQL como base de datos y Redis como cola de trabajos y caché. En una instalación On-Premise todos estos componentes conviven en un único servidor Linux; en el despliegue Cloud sobre AWS el mismo esquema se distribuye en servicios gestionados de Amazon (ECS, Aurora/RDS, S3, ALB), sin cambios en la lógica de la aplicación.

Modelo de datos multiempresa

La instalación mantiene tres tipos de base de datos en PostgreSQL:

• Base core — configuración y operación transversal del motor de documentos electrónicos.
• Base panel — usuarios, empresas, parámetros y datos de administración.
• Base por empresa — una base de datos independiente por cada empresa emisora, identificada por su RUC.

Las bases se crean vacías y se cargan con una plantilla de datos inicial durante la instalación. Dar de alta empresas adicionales luego de la puesta en marcha se coordina con CODE100.

Colas y procesamiento asíncrono

El envío al SIFEN, la generación de KUDE, el envío de correos y los reintentos se ejecutan como trabajos en cola (sobre Redis), con reintentos automáticos ante fallos temporales.

Modalidades de despliegue

Futura100 se ofrece en dos modalidades sobre la misma base de código. Esta documentación cubre ambas:

• On-Premise — la plataforma corre en un servidor Linux provisto y operado por el cliente. Instalación mediante un script automatizado.
• Cloud (AWS) — CODE100 opera la plataforma como servicio sobre Amazon Web Services, con infraestructura aprovisionada por Terraform y componentes gestionados (ECS, Aurora/RDS PostgreSQL, S3, ALB). El mismo esquema de la arquitectura, con servicios de AWS en lugar de procesos locales.

Reparto de responsabilidades — On-Premise

El cliente provee: el servidor (físico o virtual) con el sistema operativo soportado, acceso administrativo, salida a Internet, publicación de los puertos 80/443, los registros DNS, y acceso SSH para el equipo de soporte autorizando su llave pública.

CODE100 provee: el instalador, el archivo de configuración con los parámetros del despliegue, las credenciales de acceso a los componentes, y el acompañamiento durante la instalación y las actualizaciones.

Reparto de responsabilidades — Cloud (AWS)

CODE100 provee y opera: la cuenta de AWS, el código Terraform, la red (VPC), el clúster ECS, la base Aurora/RDS, los buckets S3, el balanceador, los certificados, el monitoreo y los respaldos.

El cliente provee: los datos de su empresa (RUC, certificado digital, timbrado, usuarios) y las reglas de acceso desde sus propios sistemas hacia las integraciones. El dominio y el DNS los gestiona CODE100.

Sistemas operativos soportados

Aplica a la modalidad On-Premise. El instalador está validado sobre Ubuntu Server LTS en arquitectura 64-bit x86-64.

Requisitos del sistema operativo

• Instalación limpia del SO, sin paneles de control ni servicios web preinstalados que ocupen los puertos 80/443.
• Acceso root o usuario con sudo sin restricciones.
• Gestor de servicios estándar de la distribución.
• Locale UTF-8.
• Zona horaria del servidor: America/Asuncion (el instalador la ajusta).
• Reloj sincronizado por NTP.

Hardware / recursos de la máquina

Aplica a la modalidad On-Premise. Todos los componentes (proxy inverso, los microservicios de la aplicación, la base de datos y la caché/colas) corren en un mismo servidor. Los valores mínimos permiten operar cargas pequeñas; para producción se recomienda la columna «Recomendado» o superior según volumen de documentos. En la modalidad Cloud el dimensionamiento lo resuelven los servicios gestionados de AWS (ver Cómputo: ECS).

Consideraciones

• RAM: el subsistema de caché/colas reserva una porción de la memoria total. Las compilaciones que se ejecutan durante la instalación y las actualizaciones tienen picos de consumo; con menos de 8 GB pueden fallar.
• Disco: considerar el crecimiento de la base de datos, los KUDE y logos almacenados, y los logs. Prever espacio adicional para los respaldos si se guardan en la misma máquina.
• CPU: la firma y el armado de PDF son intensivos en CPU en picos de emisión.
• Virtualización: se recomienda una VM dedicada (VMware, Hyper-V, Proxmox, KVM). No compartir el servidor con otras aplicaciones que expongan 80/443.
• Disco de sistema: preferentemente SSD; la base de datos y la caché son sensibles a la latencia de E/S.

Software base y dependencias

El instalador aprovisiona automáticamente todo el stack necesario; no hace falta instalar nada a mano.

• Proxy inverso con terminación TLS y renovación automática de certificados (Let's Encrypt).
• Runtime de aplicación (Node.js LTS) para los microservicios.
• Base de datos relacional (PostgreSQL) y caché / colas de trabajos en memoria (Redis).
• Librerías de render para generar el KUDE y los PDF, y las herramientas de compilación que requieren las dependencias nativas.

Los servicios arrancan automáticamente con el sistema y se reinician solos ante fallos. El detalle de componentes y versiones exactas se entrega en la documentación técnica de cada proyecto.

Red, puertos y firewall

Tráfico entrante (desde Internet)

• TCP 443 (HTTPS) — acceso a todos los componentes web. Único puerto de servicio expuesto.
• TCP 80 (HTTP) — sólo para la validación ACME de los certificados y la redirección permanente a HTTPS.

Ambos puertos deben estar publicados (NAT / port forwarding o IP pública directa) hacia el servidor antes de emitir los certificados.

Tráfico saliente (requerido)

• HTTPS a los servicios del SIFEN — ambientes de prueba y producción de la SET.
• HTTPS a los servicios de actualización de CODE100 y a los repositorios de paquetes del sistema operativo.
• SMTP saliente — hacia el servidor de correo de la cuenta provista por el cliente, en el puerto 587 (STARTTLS) o 465 (TLS implícito). Ver Envío de correo.

Acceso administrativo

• SSH (TCP 22) — acceso del equipo de soporte con autenticación por llave pública (sin contraseña). Restringido a direcciones IP autorizadas y sin exponer a Internet abierto.

Envío de correo

Común a ambas modalidades. Futura100 no incluye ni opera un servidor de correo propio. El servicio de envío se conecta únicamente al servidor SMTP que provee el cliente, autenticándose (login) con una cuenta de correo que la empresa habilita para su instancia de Futura100. Desde esa cuenta se envían a los receptores los documentos electrónicos aprobados y su KUDE.

Datos de la cuenta de correo que provee el cliente (por empresa)

• Host del servidor SMTP (el de su proveedor de correo o el de su dominio corporativo).
• Puerto: 587 con STARTTLS (recomendado) o 465 con TLS implícito.
• Usuario y contraseña de la cuenta, para el login SMTP (o contraseña de aplicación, si el proveedor la exige).
• Dirección remitente (From), que normalmente debe coincidir con la cuenta autenticada.
• La cuenta debe estar habilitada por la empresa para el envío autorizado desde su instancia de Futura100 (envío por SMTP autenticado permitido, sin bloqueos del proveedor).

Estos datos se cargan por empresa desde el Panel de administración. En Cloud se guardan cifrados en AWS Secrets Manager; en On-Premise, en la configuración del servicio de envío.

Requisitos y recomendaciones

• Salida de red hacia el host SMTP en el puerto elegido (587 o 465). Algunos proveedores restringen el envío por IP: puede requerirse autorizar la IP de salida del despliegue.
• Configurar SPF, DKIM y DMARC en el dominio del remitente para que los correos no caigan en spam.
• Considerar los límites de envío de la cuenta (mensajes por hora/día) según el volumen de documentos.
• Los envíos se procesan en cola con reintentos automáticos ante fallos temporales del SMTP.

DNS y dominios

• La plataforma se publica bajo un dominio base definido para cada despliegue, y cada componente en su propio subdominio de ese dominio base.
• CODE100 provee, por proyecto, la lista exacta de registros DNS a crear (nombres y valores) junto con la documentación técnica.
• El dominio base puede ser un dominio propio del cliente o un subdominio delegado a CODE100.
• La propagación DNS debe estar verificada antes de emitir los certificados TLS.

Certificados y versiones de TLS

• El TLS se termina en el proxy inverso. Los certificados se emiten con Let's Encrypt y se renuevan automáticamente.
• Se emite un único certificado multi-SAN que cubre el dominio base y todos los subdominios en una sola operación.
• Validación por HTTP-01 (requiere el puerto 80 accesible) o, si la política de red lo exige, por DNS-01.

Versiones de protocolo

• Habilitados: TLS 1.2 y TLS 1.3, con una lista de cifrados moderna y forward secrecy.
• Deshabilitados: SSL 2.0, SSL 3.0, TLS 1.0 y TLS 1.1.
• Cabecera HSTS (Strict-Transport-Security) activada. Objetivo de calificación en pruebas SSL: A / A+.

Checklist previo a la instalación

Antes de agendar la instalación, confirmar que todos estos puntos están resueltos:

• Servidor / VM aprovisionado con Ubuntu Server LTS soportado (26.04 recomendado; 24.04 soportado), 64-bit, instalación limpia.
• Recursos según la tabla de hardware (mínimo 4 vCPU / 8 GB RAM / 80 GB SSD).
• Acceso root o sudo disponible para el equipo de instalación.
• Salida a Internet por HTTPS sin proxy que rompa TLS (a SIFEN, GitHub y repositorios APT).
• Puertos 80 y 443 publicados desde Internet hacia la IP del servidor.
• Dominio base definido y registros DNS (base + subdominios) creados y propagados.
• Acceso SSH para el equipo de soporte de CODE100 con su llave pública ya autorizada en el servidor y probado.
• RUC de la empresa (o empresas) emisora(s).
• Certificado digital de firma y timbrado de la SET disponibles para la carga posterior.
• Cuenta de correo SMTP de la empresa (host, puerto 587 o 465, usuario y contraseña, dirección remitente), habilitada para el envío autorizado desde su instancia de Futura100.
• Ventana de mantenimiento acordada (la instalación completa puede tardar según ancho de banda y CPU).

Proceso de instalación

La instalación se realiza con un script único e idempotente provisto por CODE100. Si se interrumpe, puede volver a ejecutarse por completo sin efectos adversos: detecta lo ya hecho y continúa.

Verificación post-instalación

• Todos los servicios de la plataforma activos y en ejecución.
• Cada nombre de host responde por HTTPS con certificado válido y sin advertencias.
• El acceso al Portal y al Panel carga correctamente.
• Base de datos y caché/colas operativas.
• Prueba de emisión de un documento electrónico contra el ambiente de test del SIFEN y recepción del KUDE por correo.
• Prueba de renovación del certificado TLS sin errores.

Arquitectura en AWS

Aplica a la modalidad Cloud. El despliegue Cloud reproduce el mismo esquema de la arquitectura de Futura100, sustituyendo cada pieza local por su equivalente gestionado de Amazon Web Services. La lógica de los microservicios no cambia: cambian el empaquetado (contenedores), la base de datos (gestionada), el almacenamiento (objeto) y el borde (balanceador).

• Borde: un Application Load Balancer (ALB) con certificado de AWS Certificate Manager terminando TLS. El DNS es autoritativo de CODE100 (servidores DNS propios), no se usa Route 53.
• Cómputo: un clúster de Amazon ECS donde cada microservicio corre como un servicio/tarea (habitualmente sobre AWS Fargate), en subredes privadas.
• Datos: Amazon Aurora PostgreSQL o Amazon RDS for PostgreSQL (compatible con PostgreSQL), y Redis gestionado (Amazon ElastiCache) para las colas de trabajos.
• Archivos: Amazon S3 para KUDE, logotipos y artefactos.
• Imágenes y secretos: Amazon ECR para las imágenes de contenedor y AWS Secrets Manager / SSM Parameter Store para credenciales y parámetros.
• Observabilidad: Amazon CloudWatch (logs, métricas y alarmas).
• Aprovisionamiento: toda la infraestructura en AWS se define y se crea con Terraform. El DNS se mantiene aparte, en los servidores propios de CODE100.

Mapa de servicios AWS

Equivalencia entre cada pieza de la instalación On-Premise y el servicio de AWS que cumple su función en la modalidad Cloud.

Red y VPC

• El despliegue vive en una VPC dedicada con subredes públicas (sólo el ALB y los NAT Gateway) y privadas (tareas ECS, Aurora/RDS y ElastiCache).
• Distribución en al menos dos zonas de disponibilidad (AZ) para tolerancia a fallos.
• Security Groups con acceso mínimo: el ALB acepta 80/443 desde Internet; las tareas ECS sólo aceptan tráfico del ALB; la base de datos y Redis sólo aceptan tráfico de las tareas ECS.
• Salida a Internet de las subredes privadas a través de NAT Gateway (para llegar al SIFEN, al servidor SMTP del cliente en 587/465, a ECR y a las APIs de AWS) o mediante VPC endpoints donde aplique.
• Sin acceso administrativo por SSH a instancias: la operación se hace por las APIs de AWS y ECS Exec cuando es necesario.

Datos: Aurora / RDS PostgreSQL

• Motor compatible con PostgreSQL, en Amazon Aurora PostgreSQL (clúster con instancia de escritura y réplicas de lectura) o Amazon RDS for PostgreSQL con Multi-AZ, según el tamaño del despliegue.
• Se mantiene el modelo multiempresa: bases core, panel y una base por empresa, dentro del mismo clúster.
• Credenciales administradas en AWS Secrets Manager e inyectadas a las tareas ECS; sin contraseñas en archivos.
• Cifrado en reposo (KMS) y en tránsito (TLS) habilitado.
• Backups automáticos con point-in-time recovery y snapshots manuales antes de cada cambio mayor.
• Acceso únicamente desde las subredes privadas; sin exposición pública.

Cómputo: Amazon ECS

• Un clúster de ECS aloja todos los microservicios. Cada componente es un servicio de ECS con su propia task definition (imagen, CPU/memoria, variables y secretos).
• Modo de ejecución habitual: AWS Fargate (sin servidores que administrar); es posible usar capacidad EC2 para cargas específicas.
• Cada servicio corre con varias réplicas repartidas entre AZ, detrás de su target group en el ALB, con health checks HTTP.
• Autoscaling por servicio según uso de CPU/memoria o número de peticiones.
• Las colas y trabajos (envío a SIFEN, KUDE, correo, reintentos) se procesan en los servicios correspondientes usando ElastiCache for Redis como backend de colas.
• Los logs de cada tarea van a CloudWatch Logs; las métricas de ECS y ALB, a CloudWatch Metrics.

Almacenamiento: Amazon S3

• Los archivos que On-Premise se guardan en disco (KUDE generados, logotipos de empresas, artefactos) se almacenan en buckets de S3.
• Acceso desde las tareas ECS mediante roles de IAM (sin llaves estáticas), con permisos mínimos por bucket y prefijo.
• Cifrado en reposo (SSE-S3 o SSE-KMS), versionado activado y bloqueo de acceso público.
• Políticas de ciclo de vida para archivar o expirar objetos según su antigüedad.
• El estado de Terraform se guarda en un bucket S3 dedicado con versionado y bloqueo (por ejemplo con DynamoDB).

DNS y certificados

• El dominio es propiedad de CODE100 y lo resuelve su DNS autoritativo propio, no Amazon Route 53. El cliente no crea ni delega registros DNS.
• El DNS autoritativo lo opera CODE100 en su propia infraestructura, con redundancia (varios servidores en ubicaciones separadas).
• El mismo esquema de subdominios del despliegue On-Premise (ver DNS y dominios) se publica en esa zona, con registros CNAME de cada subdominio apuntando al nombre DNS del ALB.
• Un certificado de ACM cubre el dominio base y todos los subdominios (múltiples SAN). La validación se hace añadiendo los registros CNAME de verificación a la zona DNS de CODE100; una vez emitido, la renovación es automática.
• El ALB redirige HTTP → HTTPS y enruta por host header hacia el servicio ECS correspondiente.
• Versiones de TLS: el listener HTTPS usa una política de seguridad que exige TLS 1.2 como mínimo y habilita TLS 1.3; SSL 3.0, TLS 1.0 y TLS 1.1 quedan deshabilitados. Cabecera HSTS activada.

Entrega con Terraform

Toda la infraestructura del despliegue Cloud se describe como código Terraform versionado. No hay recursos creados a mano en la consola de AWS.

Operación en AWS

• Monitoreo: paneles y alarmas de CloudWatch sobre CPU/memoria de ECS, errores 5xx y latencia del ALB, conexiones y almacenamiento de Aurora/RDS, y memoria de ElastiCache. Notificaciones por SNS.
• Escalado: políticas de autoscaling por servicio ECS; el clúster Aurora admite réplicas de lectura y cambio de tamaño de instancia con impacto mínimo.
• Actualizaciones: mismo flujo de Terraform + despliegue gradual de ECS; sin ventana de corte para cambios sin migración disruptiva.
• Respaldos: automáticos de Aurora/RDS con point-in-time recovery, snapshots previos a cambios mayores y versionado en S3 (ver Respaldo y recuperación).
• Diagnóstico: logs por servicio en CloudWatch Logs; acceso puntual a un contenedor con ECS Exec cuando es necesario.
• Costos: etiquetado de recursos y seguimiento por Cost Explorer.

Introducción a la integración

Común a ambas modalidades de despliegue. Futura100 expone un Web Service para que los sistemas del cliente (ERP, core bancario, POS, e-commerce) generen documentos electrónicos sin implementar la lógica del SIFEN. El sistema del cliente envía los datos del comprobante; Futura100 valida, arma y firma el XML, lo transmite al SIFEN, guarda el resultado y notifica al receptor.

Modalidades del Web Service

Las tres comparten el modelo de datos, los tipos de documento y los estados. Se elige una por integración; CODE100 habilita la que corresponda.

Flujo general

Autenticación

• Endpoint: POST http://dominio/api/login (en la modalidad Middleware: /api/autenticate).
• Cuerpo JSON con las credenciales del servicio: ruc (identificador de la empresa) y password. CODE100 entrega ambos valores y el formato exacto para cada instancia.
• Devuelve un token (JWT) que se envía en cada llamada siguiente como cabecera Authorization: Bearer <token>, junto con Content-Type: application/json.
• El token tiene una vigencia de 2 horas; al expirar se vuelve a autenticar.
• Credenciales inválidas → respuesta con error.

POST /api/login
Content-Type: application/json

{
  "ruc": "<RUC sin dígito verificador>",
  "password": "<contraseña>"
}

// Respuesta
{ "token": "<JWT>" }

Tipos de documento y numeración

Tipos de documento electrónico (iTiDE)

Códigos cortos (tipoDoc)

Usados en consultas, eventos y descargas: FE Factura Electrónica · NCR Nota de Crédito · NDE Nota de Débito · REM Nota de Remisión · AUT Autofactura.

Identificación de un documento

• dEst — establecimiento (3 dígitos, p. ej. 001).
• dPunExp — punto de expedición (3 dígitos).
• dNumDoc — número correlativo del documento (7 dígitos).
• dSerieNum — serie (puede ir vacío).

La terna dEst + dPunExp + dNumDoc identifica de forma única al comprobante dentro de la empresa y se usa para consultar estado, descargar XML/KUDE y registrar eventos.

API REST — Recepción de DE

Modalidad REST con un endpoint por operación. Todas las llamadas (salvo login) llevan la cabecera Authorization: Bearer <token> y Content-Type: application/json.

Alta de documento — /api/recepcion_de

El cuerpo es un JSON con la cabecera del comprobante y los arreglos Detalles, Subtotales y, si corresponde, DocumentosAsociados y FormaPago. La lista completa de campos por tipo de documento se entrega en los diccionarios de campos (ver Catálogos y códigos referenciales).

POST /api/recepcion_de
Authorization: Bearer <token>
Content-Type: application/json

{
  "iTiDE": 1,                 // 1=Factura 4=Autofactura 5=NC 6=ND 7=Remisión
  "dEst": "001",
  "dPunExp": "001",
  "dNumDoc": "0000123",
  "dFeEmiDE": "2026-09-02 10:15:00",
  "cMoneOpe": "PYG",
  "iCondOpe": 1,              // 1=Contado 2=Crédito
  "dRucRec": "<RUC receptor>",
  "dDVRec": "<DV>",
  "dNomRec": "<Razón social del receptor>",
  "Detalles": [
    {
      "dCodInt": "1001",
      "dDesProSer": "Producto de ejemplo",
      "cUniMed": "77",
      "dCantProSer": 1,
      "dPUniProSer": 100000,
      "iAfecIVA": 1,
      "dTasaIVA": 10
    }
  ],
  "Subtotales": [ { "dSub10": 100000 } ]
}

// Respuesta OK
{ "status": "success", "message": "Documento registrado exitosamente" }

// Respuesta con validación de campos
{ "iTiDE": "Es obligatorio informar el Tipo de documento" }

API REST — Middleware

Misma funcionalidad que la API de Recepción de DE, pero con un único endpoint —POST http://dominio/api/operation— y un campo tipOpe que indica la operación. Autenticación en POST /api/autenticate.

POST /api/operation
Authorization: Bearer <token>
Content-Type: application/json

{ "tipOpe": 2, "dEst": "001", "dPunExp": "001",
  "dNumDoc": "0000123", "dSerieNum": "", "tipoDoc": "FE" }

API SOAP

• Endpoint / WSDL: POST http://dominio/soap-ws?wsdl.
• Operación principal: guardarFactura. Las credenciales (user, password) y la identificación del documento van dentro del cuerpo del sobre SOAP.
• Respuesta con Message (texto) y Status (booleano).
• Pensada para sistemas que sólo soportan SOAP; para integraciones nuevas se recomienda REST.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="ws_factura">
  <soapenv:Body>
    <ws:guardarFactura>
      <name xsi:type="ws:Factura">
        <user>usuario</user>
        <password>********</password>
        <dEst>001</dEst>
        <dPunExp>001</dPunExp>
        <dNumDoc>0000123</dNumDoc>
      </name>
    </ws:guardarFactura>
  </soapenv:Body>
</soapenv:Envelope>

<!-- Respuesta -->
<Message>Documento registrado correctamente</Message>
<Status>true</Status>

Estados y respuesta del SIFEN

Respuesta de las operaciones

• status: success o error.
• message: confirmación o motivo del error.
• Validaciones de campos: objeto {"campo": "mensaje"} — p. ej. {"dEst": "El número de establecimiento debe ser informado"}.

Consulta de estado

Devuelve el estado del documento y la traza del envío al SIFEN:

{
  "status": "success",
  "response": {
    "Estado": "Aprobado",
    "FechaRegistro": "02-09-2026 10:15:20",
    "DE": {
      "CDC": "<CDC — 44 dígitos>",
      "FechaFirma": "02-09-2026 10:15:52",
      "FechaEnvio": "2026-09-02 10:15:58",
      "Retorno": {
        "FechaRetorno": "02-09-2026 10:18:54",
        "CodRespuesta": "0260",
        "Mensaje": "Aprobado"
      }
    }
  }
}

Eventos

Sobre un documento ya aprobado se pueden registrar eventos ante el SIFEN:

El paquete de integración incluye además ejemplos de estructura de los eventos del receptor (conformidad, disconformidad, desconocimiento, notificación) y de las respuestas de lote y de eventos del SIFEN.

Catálogos y códigos referenciales

Los valores codificados de los campos siguen las tablas del SIFEN. CODE100 entrega, junto con el manual de integración:

• Diccionarios de campos por tipo de documento (factura, crédito, débito, remisión, autofactura): nombre del campo, tipo, obligatoriedad y descripción.
• Ejemplos de estructura JSON por tipo de documento y casos especiales (contado, crédito, anticipo por ítem y global, descuento global, documento asociado electrónico, varias formas de pago).
• Planillas de códigos referenciales: código de divisa (ISO 4217), código de referencia geográfica (departamentos, distritos, ciudades), unidades de medida y la Tabla 10 de condiciones de negociación (INCOTERMS).
• Esquemas XSD del SIFEN (DE_v150.xsd, DE_Types_v150.xsd) para la variante SOAP.
• Ejemplos de representación gráfica (KUDE estándar).

Notificación, XML y KUDE

• Cuando un documento queda Aprobado, Futura100 envía un correo al receptor con el KUDE (PDF) y el XML firmado, usando la cuenta SMTP de la empresa (ver Envío de correo).
• El sistema del cliente también puede obtenerlos por su cuenta:
  • XML firmado — GET /api/xml o tipOpe 3. Devuelve CDC y xml en base64.
  • KUDE — GET /api/kude o tipOpe 4. Devuelve CDC y kude (PDF) en base64.
• Ambos se piden con la identificación del documento (dEst, dPunExp, dNumDoc, tipoDoc).

Buenas prácticas de integración

• Probá primero en el ambiente de test del SIFEN antes de pasar a producción.
• Guardá el CDC de cada documento aprobado: es la referencia única ante el SIFEN y para eventos, notas asociadas y descargas.
• Numeración sin huecos ni duplicados: controlá dEst/dPunExp/dNumDoc desde tu sistema; reenviar la misma terna produce un documento duplicado.
• No asumas la aprobación por el success del alta: consultá el estado hasta Aprobado o Rechazado y registrá CodRespuesta y Mensaje.
• Reintentos: ante error de red, reintentá con espera creciente; ante error de validación, corregí los campos que indica la respuesta.
• Token: cacheá el token y renovalo al acercarse a las 2 horas o ante un rechazo por autenticación.
• Fechas en la zona horaria de Paraguay (America/Asuncion).

Componentes de la plataforma

Común a ambas modalidades. La plataforma está compuesta por un conjunto de servicios independientes, cada uno con una responsabilidad acotada. En On-Premise corren como procesos en el servidor, sólo alcanzables a través del proxy inverso; en Cloud, como servicios de ECS detrás del balanceador. Los puertos y parámetros internos se detallan en la documentación técnica.

Mantenimiento y actualización

On-Premise · Gestión de servicios

• Estado y reinicio de servicios con las herramientas estándar del sistema operativo.
• Logs por servicio disponibles en el sistema.
• Todos los servicios arrancan automáticamente con el servidor.

On-Premise · Actualización de versión

Las actualizaciones se aplican de forma coordinada con CODE100. El procedimiento estándar vuelve a ejecutar el instalador, que actualiza el código de cada componente a la rama de producción, reinstala dependencias, recompila los front-end y reinicia los servicios. Se recomienda:

• Realizar un respaldo completo de las bases de datos antes de actualizar.
• Ejecutar en una ventana de mantenimiento.
• Validar con la checklist de verificación al finalizar.

On-Premise · Sistema operativo

• Aplicar actualizaciones de seguridad del SO con regularidad (unattended-upgrades para parches críticos).
• Planificar la migración de versión LTS antes del fin de soporte de la instalada.

Cloud (AWS)

• Cambios de infraestructura y de versión mediante Terraform + despliegue gradual de ECS, sin corte de servicio para cambios no disruptivos.
• Parcheo del sistema operativo base a cargo de AWS (Fargate); actualización de la versión del motor de Aurora/RDS en ventana coordinada.
• Estado y salud vía CloudWatch; rollback volviendo a la task definition anterior.

Respaldo y recuperación

On-Premise

El respaldo de la instalación On-Premise es responsabilidad del cliente. Elementos a incluir en la política de backup:

• Bases PostgreSQL — las tres bases (core, panel y cada base por empresa). Respaldo lógico diario con pg_dump y/o respaldo físico con pg_basebackup. Verificar restauraciones periódicamente.
• Certificados digitales y de firma de las empresas y el certificado TLS (o dejar que se re-emita automáticamente).
• Archivos generados — KUDE y logotipos almacenados por los servicios.
• Archivos de configuración de cada componente y del proxy inverso.
• El contenido de la caché/colas es transitorio y no requiere respaldo formal.

Cloud (AWS)

En la modalidad Cloud el respaldo lo gestiona CODE100 con los mecanismos nativos de AWS:

• Aurora / RDS PostgreSQL — backups automáticos con point-in-time recovery y snapshots manuales antes de cambios mayores.
• Amazon S3 — versionado de objetos y, según el caso, replicación entre regiones.
• Infraestructura — reproducible desde el código Terraform y su estado remoto versionado.
• Redis (ElastiCache) — colas transitorias; sin respaldo formal.
• Procedimiento de recuperación (RTO/RPO) documentado y probado periódicamente.

Seguridad y buenas prácticas

On-Premise

• Superficie de exposición mínima: sólo 80/443 públicos. Firewall (ufw o nftables) con política de denegar por defecto en entrante.
• SSH: autenticación por llave pública únicamente (contraseñas deshabilitadas), acceso restringido a IPs de gestión autorizadas, login de root remoto deshabilitado.
• Rotación de secretos: cambiar las credenciales de base de datos y los secretos de aplicación tras la puesta en marcha, en coordinación con CODE100.
• Actualizaciones: parches de seguridad del SO al día; actualizaciones de la aplicación de forma coordinada.
• TLS: mantener la renovación automática monitoreada; revisar la configuración de cifrados del proxy inverso.
• Respaldo: copias cifradas y externas, con restauración probada.
• Monitoreo: health checks HTTP por nombre de host, uso de disco, memoria y estado de los servicios. Alertas de vencimiento de certificado.
• Accesos: usuarios nominales en el Panel, revisión periódica de permisos, baja inmediata de accesos que ya no correspondan.

Cloud (AWS)

• Aislamiento de red: cómputo y datos en subredes privadas; sólo el ALB expone 80/443. Security Groups con acceso mínimo entre capas.
• IAM de mínimo privilegio: roles por servicio ECS, sin llaves estáticas; acceso de personas con MFA y roles temporales.
• Secretos: en AWS Secrets Manager / SSM, cifrados con KMS e inyectados en tiempo de ejecución; rotación programada.
• Cifrado: en reposo (Aurora/RDS, S3, EBS con KMS) y en tránsito (TLS de extremo a extremo).
• TLS: certificado de ACM con renovación automática gestionada por AWS.
• Perímetro: AWS WAF sobre el ALB (opcional) y protección estándar de AWS Shield.
• Auditoría: AWS CloudTrail habilitado; alarmas de CloudWatch ante eventos anómalos.
• Sin acceso SSH: diagnóstico con ECS Exec y logs de CloudWatch.

Preguntas frecuentes

¿Se puede instalar en Windows Server?

No. El instalador y los servicios están diseñados para Ubuntu Server LTS de 64 bits.

¿Funciona sin conexión a Internet?

No. Se requiere salida a Internet permanente hacia el SIFEN para transmitir los documentos, y hacia los servicios de CODE100 para instalar y actualizar componentes.

¿Futura100 tiene servidor de correo propio?

No. Futura100 sólo se conecta al servidor SMTP que provee el cliente y se autentica (login) con una cuenta de correo que la empresa habilita para el envío autorizado desde su instancia (host, puerto 587 o 465, usuario y contraseña). Ver Envío de correo.

¿Cómo integro mi sistema (ERP) con Futura100?

A través del Web Service: tu sistema se autentica con las credenciales de servicio que te entrega CODE100, envía el JSON (o XML) del comprobante, y Futura100 lo valida, firma y transmite al SIFEN. Hay tres modalidades —REST por operación, REST con endpoint único (Middleware) y SOAP— y todas comparten el modelo de datos. Ver Integración (Web Service).

¿Puede usarse un solo subdominio para todo?

No. Cada componente se publica en su propio nombre de host; el certificado multi-SAN los cubre a todos.

¿Una instalación puede emitir por varias empresas?

Sí. La edición 1.5 Multiempresa mantiene una base de datos por empresa. El alta de empresas adicionales luego de la puesta en marcha se coordina con CODE100.

¿Quién emite y renueva el certificado TLS?

Se emite y renueva automáticamente en el propio servidor. El cliente sólo debe mantener accesibles los puertos 80/443.

¿Se puede usar un PostgreSQL gestionado o externo?

La instalación On-Premise estándar asume PostgreSQL local en el mismo servidor. En la modalidad Cloud la base es gestionada de fábrica: Amazon Aurora PostgreSQL o RDS for PostgreSQL. Un motor externo en On-Premise es posible pero debe evaluarse con CODE100.

¿Qué pasa si la instalación se interrumpe a la mitad?

El instalador On-Premise es idempotente: se vuelve a ejecutar completo y retoma desde donde quedó. En Cloud, terraform apply se puede volver a correr y converge al estado deseado.

¿Cuánto dura la instalación?

On-Premise: depende del ancho de banda y la CPU del servidor; contempla descarga de paquetes, de Node.js, del código de los componentes y varias compilaciones de front-end. Planificar una ventana de mantenimiento holgada.

¿En qué se diferencia el despliegue Cloud del On-Premise?

Es el mismo software y el mismo esquema de arquitectura. Cambia la infraestructura: en Cloud los microservicios corren en contenedores sobre Amazon ECS, la base de datos es Aurora/RDS, los archivos van a S3, el borde es un Application Load Balancer con certificado de ACM, y todo se aprovisiona con Terraform. Lo opera CODE100.

¿Quién opera el entorno Cloud?

CODE100, sobre su propia cuenta de AWS: infraestructura, actualizaciones, monitoreo, respaldos y seguridad. El dominio y el DNS también son de CODE100. El cliente sólo aporta los datos de su empresa.

¿Se puede desplegar en Azure o Google Cloud?

El despliegue Cloud estándar está definido para AWS con Terraform. Otro proveedor se evalúa caso a caso; los conceptos son equivalentes (contenedores gestionados, PostgreSQL gestionado, almacenamiento de objetos, balanceador, IaC) pero requiere trabajo de adaptación.

Glosario

• SIFEN — Sistema Integrado de Facturación Electrónica Nacional de la Subsecretaría de Estado de Tributación (SET) de Paraguay.
• DE — Documento Electrónico (factura, nota de crédito/débito, remisión, autofactura).
• CDC — Código de Control: identificador único de 44 dígitos que el SIFEN asigna a cada documento electrónico. Referencia para consultas, eventos y documentos asociados.
• KUDE — Representación gráfica (PDF) del Documento Electrónico, entregable al receptor.
• iTiDE / tipoDoc — Código numérico (iTiDE) y código corto (tipoDoc: FE, NCR, NDE, REM, AUT) del tipo de documento electrónico.
• REST / SOAP — Estilos del Web Service de integración: REST usa JSON sobre HTTP; SOAP usa sobres XML con WSDL.
• Multi-SAN — Certificado TLS con varios nombres de host (Subject Alternative Names) en un mismo certificado.
• SMTP — Protocolo de envío de correo. Futura100 se conecta como cliente a un servidor SMTP externo (puerto 587 con STARTTLS o 465 con TLS implícito) con la cuenta que provee cada empresa.
• SPF / DKIM / DMARC — Registros DNS del dominio del remitente que autentican el correo saliente y evitan que sea marcado como spam.
• Idempotente — Que puede ejecutarse varias veces produciendo el mismo resultado, sin duplicar ni romper lo ya hecho.
• Proxy inverso — Servidor (Apache) que recibe las peticiones de Internet y las reenvía al microservicio interno correspondiente.
• On-Premise — Modalidad en la que el software corre en infraestructura propia del cliente en lugar de la nube del proveedor.
• IaC — Infraestructura como código: la infraestructura se define en archivos versionados y se crea de forma automática y reproducible.
• Terraform — Herramienta de IaC usada para aprovisionar toda la infraestructura del despliegue Cloud en AWS.
• VPC — Virtual Private Cloud: red privada aislada dentro de AWS donde se despliegan los recursos.
• ECS — Elastic Container Service: servicio de AWS para ejecutar contenedores; aloja los microservicios en la modalidad Cloud.
• Fargate — Modo de ejecución de ECS sin servidores que administrar.
• ECR — Elastic Container Registry: registro de imágenes de contenedor de AWS.
• Aurora / RDS — Servicios de base de datos relacional gestionada de AWS; aquí, compatibles con PostgreSQL.
• ElastiCache — Redis gestionado por AWS; backend de las colas de trabajos en Cloud.
• S3 — Simple Storage Service: almacenamiento de objetos de AWS para KUDE, logotipos y artefactos.
• ALB — Application Load Balancer: balanceador HTTP/HTTPS de AWS; el borde del despliegue Cloud.
• ACM — AWS Certificate Manager: emite y renueva automáticamente el certificado TLS del ALB.
• DNS autoritativo — Los nombres del despliegue Cloud los resuelve CODE100 desde su propia infraestructura DNS con redundancia; no se usa Amazon Route 53.
• Primario / secundario (master / slave) — El servidor primario tiene la copia editable de la zona DNS; los secundarios reciben copias por transferencia de zona y responden consultas, dando redundancia geográfica.
• Secrets Manager — Servicio de AWS para guardar y rotar credenciales y secretos; reemplaza a los archivos .env.
• CloudWatch — Servicio de AWS para logs, métricas y alarmas.
• Multi-AZ — Distribución de los recursos en varias zonas de disponibilidad de una región para tolerancia a fallos.

Soporte

El soporte de despliegues On-Premise y Cloud se canaliza a través de la mesa de ayuda de CODE100 mediante el sistema de tickets. Cada despliegue tiene asignado un responsable técnico y un responsable funcional.

• Reportes de incidencias y solicitudes de cambio: por ticket, con detalle del componente afectado y los logs relevantes del componente afectado.
• Actualizaciones de versión: se agendan con anticipación en una ventana de mantenimiento acordada.
• Los datos de contacto, credenciales y parámetros del despliegue se entregan por los canales privados de cada proyecto.