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.

STAGE

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.

NODE_ENV

string

required

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

NUXT_PORT

number

default:"3000"

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

NUXT_HOST

string

default:"localhost"

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

NITRO_PRESET

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.

NUXT_SESSION_PASSWORD

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).

NUXT_JWT_SECRET

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

DATABASE_URL

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.

DATABASE_ENV

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.

API_SISU_ENV

string

default:"pro"

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

API_SISU_URL_PRO

string

required

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

API_SISU_URL_DEV

string

required

URL base del endpoint de desarrollo/pruebas de SISUWEB.

API_SISU_CLIENT_ID

string

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

API_SISU_PASSWORD

string

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

API_SISU_TYPE_AUTH

string

default:"Basic"

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

API_SISU_BASIC_USER

string

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

API_SISU_BASIC_PASSWORD

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.

API_FIRMA_ENV

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.

API_FIRMA_URL_PRO

string

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

URL base de producción de FirmaPlus.

API_FIRMA_URL_DEV

string

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

URL base del sandbox de FirmaPlus para pruebas.

API_FIRMA_TYPE_AUTH

string

default:"Basic"

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

API_FIRMA_BASIC_USER

string

required

Usuario para autenticación Basic con FirmaPlus.

API_FIRMA_BASIC_PASSWORD

string

required

Contraseña para autenticación Basic con FirmaPlus.

API_FIRMA_CLIENT_ID

string

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

API_FIRMA_PASSWORD

string

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

API FlaskPDF

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

API_FLASKPDF_ENV

string

default:"dev"

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

API_FLASKPDF_URL_PRO

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.

API_FLASKPDF_URL_DEV

string

required

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

API_FLASKPDF_USER

string

required

Usuario para autenticación Basic HTTP con FlaskPDF.

API_FLASKPDF_PASSWORD

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).

MAIL_ENV

string

default:"dev"

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

MAIL_HOST

string

default:"smtp.gmail.com"

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

MAIL_PORT

number

default:"465"

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

MAIL_SECURE

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.

MAIL_USER

string

required

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

MAIL_PASSWORD

string

required

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

MAIL_FROM_NAME

string

default:"Comfaca Créditos"

Nombre visible del remitente en los correos enviados.

MAIL_FROM_ADDRESS

string

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

MAIL_REJECT_UNAUTHORIZED

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.

SFTP_ENV

string

default:"dev"

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

SFTP_HOST

string

required

Hostname o IP del servidor SFTP.

SFTP_PORT

number

default:"22"

Puerto SSH del servidor SFTP.

SFTP_USER

string

required

Nombre de usuario para la sesión SSH.

SFTP_PASSWORD

string

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

SFTP_PRIVATE_KEY_BASE64

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.

SFTP_PASSPHRASE

string

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

SFTP_BASE_PATH

string

default:"/"

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

SFTP_READY_TIMEOUT_MS

number

default:"20000"

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

Storage y Backend

STORAGE_DOCUMENTS_PATH

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.

STORAGE_LOGS_PATH

string

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

STORAGE_UPLOADS_PATH

string

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

NUXT_BACKEND_BASE_PORT

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.

NUXT_BACKEND_BASE_URL

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

Build docs developers (and LLMs) love

Introducción

Configuración

Arquitectura

Funcionalidades

Pruebas y Despliegue

Documentation Index

​Archivo .env de referencia

​General

​Base de Datos

​API SISU

​API FirmaPlus

​API FlaskPDF

​Correo (SMTP)

​SFTP

​Storage y Backend

Build docs developers (and LLMs) love

Archivo `.env` de referencia

General

Base de Datos

API SISU

API FirmaPlus

API FlaskPDF

Correo (SMTP)

SFTP

Storage y Backend