Configurar Variables de Entorno de Comfaca Créditos

Esta página documenta todas las variables de entorno requeridas por la aplicación, tomadas directamente del archivo .env.template incluido en el repositorio. Copia ese archivo como .env en la raíz del proyecto y completa cada valor antes de ejecutar el servidor.

cp .env.template .env

Archivo `.env` de referencia

# Prisma no carga este archivo automáticamente.
# Agrega `import "dotenv/config"` en prisma.config.ts o usa la CLI de Prisma.

STAGE=dev
NUXT_PORT=4000
NUXT_HOST="localhost"

DATABASE_URL="mysql://"
NODE_ENV= #'development', 'test', 'production'
NUXT_SESSION_PASSWORD=
NITRO_PRESET = 'node'

API_SISU_ENV=pro
API_SISU_URL_PRO="http://"
API_SISU_URL_DEV="http://"
API_SISU_CLIENT_ID=""
API_SISU_PASSWORD=""
API_SISU_TYPE_AUTH="Basic"
API_SISU_BASIC_USER=""
API_SISU_BASIC_PASSWORD=""

API_FIRMA_ENV=dev
API_FIRMA_URL_PRO="https://firmaplus.co/Risk/api"
API_FIRMA_URL_DEV="https://firmaplus.co/FirmaPlusPruebas/api"
API_FIRMA_TYPE_AUTH="Basic"
API_FIRMA_BASIC_USER=""
API_FIRMA_BASIC_PASSWORD=""
API_FIRMA_CLIENT_ID=
API_FIRMA_PASSWORD=

API_FLASKPDF_ENV=dev
API_FLASKPDF_URL_PRO="http://"
API_FLASKPDF_URL_DEV="http://"
API_FLASKPDF_USER=""
API_FLASKPDF_PASSWORD=""

# Mail (SMTP) — Gmail: usar App Password de 16 caracteres
MAIL_ENV=dev
MAIL_HOST="smtp.gmail.com"
MAIL_PORT=465
MAIL_SECURE=true
MAIL_USER=""
MAIL_PASSWORD=""
MAIL_FROM_NAME="Comfaca Créditos"
MAIL_FROM_ADDRESS=""
# NUNCA poner en "false" en producción. Solo para diagnóstico local.
MAIL_REJECT_UNAUTHORIZED=true

# SFTP — transferencia de archivos sobre SSH
SFTP_ENV=dev
SFTP_HOST=""
SFTP_PORT=22
SFTP_USER=""
SFTP_PASSWORD=""
# Alternativa: clave privada en base64 (recomendado sobre password)
SFTP_PRIVATE_KEY_BASE64=""
SFTP_PASSPHRASE=""
SFTP_BASE_PATH="/"
SFTP_READY_TIMEOUT_MS=20000

NUXT_BACKEND_BASE_PORT=5001
NUXT_BACKEND_BASE_URL="http://localhost"

NUXT_JWT_SECRET=
STORAGE_DOCUMENTS_PATH=""
STORAGE_LOGS_PATH=""
STORAGE_UPLOADS_PATH=""

General

Variables que controlan el comportamiento global de la aplicación Nuxt.

string

required

Entorno de despliegue lógico. Valores habituales: dev, staging, pro. Distinto de NODE_ENV; lo usan algunos servicios internos para seleccionar configuración.

string

required

Entorno de Node.js. Valores válidos: development, test, production. Controla optimizaciones de Vite/Nitro y la generación de sourcemaps.

number

default:"3000"

Puerto en el que escucha el servidor de desarrollo (devServer.port en nuxt.config.ts). Ejemplo: 4000.

string

default:"localhost"

Host de enlace del servidor de desarrollo. Usa 0.0.0.0 para exponer en red local.

string

default:"node"

Preset de Nitro para la compilación del servidor. El valor node genera un servidor Node.js estándar compatible con PM2, nohup y despliegues VPS. Otros valores válidos incluyen node-server, bun o cloudflare. Normalmente no necesitas cambiarlo salvo que despliegues en una plataforma de hosting específica.

string

required

Clave de cifrado para las sesiones gestionadas por nuxt-auth-utils. La sesión expira a las 8 horas por defecto (maxAge: 60 * 60 * 8).

string

required

Secreto para firmar y verificar JSON Web Tokens emitidos por la API del servidor.

NUXT_SESSION_PASSWORD y NUXT_JWT_SECRET deben ser cadenas aleatorias largas y únicas en producción (mínimo 32 caracteres). Nunca reutilices el mismo valor en distintos entornos ni lo incluyas en control de versiones.

Base de Datos

string

required

Cadena de conexión MySQL/MariaDB en formato mysql://usuario:contraseña@host:puerto/nombre_db. Utilizada por Prisma cuando DATABASE_ENV no está definido o apunta a dev.

string

default:"dev"

Selector de URL activa para Prisma. Cuando vale pro, prisma.config.ts usa DATABASE_URL_PRO; en cualquier otro valor usa DATABASE_URL_DEV (o DATABASE_URL como fallback).

API SISU

Variables para la integración con SISUWEB, el sistema de validación de afiliados de COMFACA.

string

default:"pro"

Selector de URL activa. pro → API_SISU_URL_PRO; cualquier otro valor → API_SISU_URL_DEV.

string

required

URL base del endpoint de producción de SISUWEB. Ejemplo: http://192.168.1.10:8080/api.

string

required

URL base del endpoint de desarrollo/pruebas de SISUWEB.

string

Identificador de cliente OAuth2 para autenticación Bearer. Solo requerido cuando API_SISU_TYPE_AUTH=Bearer.

string

Contraseña OAuth2 para el flujo de obtención de token Bearer. Solo requerida cuando API_SISU_TYPE_AUTH=Bearer.

string

default:"Basic"

Modo de autenticación. Valores soportados: Basic (encabezado Authorization: Basic <base64>) o Bearer (token obtenido vía /token).

string

Usuario para autenticación Basic HTTP. Requerido cuando API_SISU_TYPE_AUTH=Basic.

string

Contraseña para autenticación Basic HTTP. Requerida cuando API_SISU_TYPE_AUTH=Basic.

API FirmaPlus

Variables para la integración con FirmaPlus, la plataforma de firma digital de documentos contractuales.

string

default:"dev"

Selector de entorno. pro → API_FIRMA_URL_PRO; cualquier otro valor → API_FIRMA_URL_DEV. En modo dev el servicio responde con respuestas mock sin llamar al servidor real.

string

default:"https://firmaplus.co/Risk/api"

URL base de producción de FirmaPlus.

string

default:"https://firmaplus.co/FirmaPlusPruebas/api"

URL base del sandbox de FirmaPlus para pruebas.

string

default:"Basic"

Modo de autenticación con FirmaPlus. Actualmente soportado: Basic.

string

required

Usuario para autenticación Basic con FirmaPlus.

string

required

Contraseña para autenticación Basic con FirmaPlus.

string

Client ID OAuth2 de FirmaPlus (reservado para flujo Bearer, si se habilita en el futuro).

string

Contraseña OAuth2 de FirmaPlus (reservado para flujo Bearer).

API FlaskPDF

Variables para el microservicio Python de generación de PDFs contractuales.

string

default:"dev"

Selector de entorno activo. pro → usa API_FLASKPDF_URL_PRO; cualquier otro valor → API_FLASKPDF_URL_DEV.

string

required

URL base del microservicio FlaskPDF en producción. Ejemplo: http://10.0.0.30:5000. Toda llamada se realiza contra el endpoint POST /creditos/generate-pdf.

string

required

URL base del microservicio FlaskPDF en desarrollo. Ejemplo: http://localhost:5000.

string

required

Usuario para autenticación Basic HTTP con FlaskPDF.

string

required

Contraseña para autenticación Basic HTTP con FlaskPDF.

Correo (SMTP)

Variables para el servicio de correo electrónico transaccional (notificaciones de registro, recuperación de contraseña, alertas de solicitud).

string

default:"dev"

Entorno del servicio de correo. En dev se puede redirigir a cuentas de prueba.

string

default:"smtp.gmail.com"

Servidor SMTP. Para Gmail usar smtp.gmail.com.

number

default:"465"

Puerto SMTP. 465 para SSL directo; 587 para STARTTLS.

boolean

default:"true"

true activa SSL/TLS directo (puerto 465). false usa STARTTLS (puerto 587), que se negocia después de la conexión inicial.

string

required

Dirección de correo o usuario SMTP. Para Gmail, la dirección completa: notificaciones@tudominio.com.

string

required

Contraseña SMTP. Para Gmail, una App Password de 16 caracteres (ver consejo abajo).

string

default:"Comfaca Créditos"

Nombre visible del remitente en los correos enviados.

string

Dirección From de los correos. Si se omite, se usa el valor de MAIL_USER.

boolean

default:"true"

Controla la verificación del certificado TLS del servidor SMTP (tls.rejectUnauthorized en nodemailer). En producción siempre debe ser true.

Nunca establezcas MAIL_REJECT_UNAUTHORIZED=false en producción. Desactivar la verificación TLS expone las credenciales SMTP a ataques de intermediario. Usa este valor únicamente para diagnóstico en entornos locales sin certificado válido.

Gmail — App Password de 16 caracteresPara usar Gmail como servidor SMTP sin desactivar la seguridad de la cuenta:

Activa la verificación en dos pasos en tu cuenta Google.
Ve a myaccount.google.com/apppasswords.
Crea una nueva App Password con nombre Comfaca Créditos.
Copia la clave de 16 caracteres generada y pégala en MAIL_PASSWORD.

Esta clave es independiente de la contraseña principal de la cuenta y puede revocarse en cualquier momento.

SFTP

Variables para la transferencia segura de documentos a un servidor remoto vía SSH File Transfer Protocol.

string

default:"dev"

Entorno del servicio SFTP. No cambia la URL pero puede condicionar validaciones internas.

string

required

Hostname o IP del servidor SFTP.

number

default:"22"

Puerto SSH del servidor SFTP.

string

required

Nombre de usuario para la sesión SSH.

string

Contraseña para autenticación por contraseña. Se usa como fallback si SFTP_PRIVATE_KEY_BASE64 no está configurada.

string

Contenido de la clave privada RSA o ED25519 codificado en Base64. Método de autenticación preferido sobre contraseña. Para convertir una clave: base64 -w 0 ~/.ssh/id_rsa.

string

Frase de paso de la clave privada, si la tiene.

string

default:"/"

Directorio base en el servidor remoto. Todas las rutas relativas pasadas a los métodos del servicio se resuelven desde aquí.

number

default:"20000"

Tiempo máximo en milisegundos para completar el handshake SSH inicial y las operaciones de transferencia.

Storage y Backend

string

Ruta local (absoluta o relativa al proyecto) donde se almacenan los documentos generados. Si se omite, se usa el directorio storage/ en la raíz del proyecto.

string

Ruta local para los archivos de log de la aplicación. Valor por defecto: storage/.

string

Ruta local para archivos subidos por los usuarios. Valor por defecto: storage/.

number

default:"5001"

Puerto del backend auxiliar (microservicio o proceso separado). Se combina con NUXT_BACKEND_BASE_URL para construir la URL completa: http://localhost:5001.

string

default:"http://localhost"

URL base del backend auxiliar sin puerto final. El sistema la concatena con NUXT_BACKEND_BASE_PORT en runtimeConfig.backendBaseUrl.

Introducción

Configuración

Arquitectura

Funcionalidades

Pruebas y Despliegue

Configurar Variables de Entorno de Comfaca Créditos

Archivo `.env` de referencia

General

Base de Datos

API SISU

API FirmaPlus

API FlaskPDF

Correo (SMTP)

SFTP

Storage y Backend

​Archivo .env de referencia

​General

​Base de Datos

​API SISU

​API FirmaPlus

​API FlaskPDF

​Correo (SMTP)

​SFTP

​Storage y Backend

Archivo `.env` de referencia

General

Base de Datos

API SISU

API FirmaPlus

API FlaskPDF

Correo (SMTP)

SFTP

Storage y Backend