Archivo .env El archivo .env contiene todas las variables de configuración de la aplicación.
Copiar archivo de ejemplo
El comando composer setup hace esto automáticamente si el archivo no existe.
Generar clave de aplicación
Esto genera una clave segura en APP_KEY usada para encriptar datos.
Configurar variables
Edita el archivo .env con tus valores específicos.
Configuración de Aplicación Variables Básicas APP_NAME = "Santo Domingo Facturación" APP_ENV = local APP_KEY = base64:GENERADO_POR_ARTISAN APP_DEBUG = true APP_URL = http://localhost:8000
APP_NAME
APP_ENV
APP_DEBUG
APP_URL
Nombre de la aplicación que aparece en:
Título del navegador
Emails del sistema
Notificaciones
Entorno de ejecución:
local - Desarrollo localstaging - Ambiente de pruebasproduction - Producción En producción, SIEMPRE configura APP_DEBUG=false para no exponer información sensible en errores.
true - Muestra errores detallados (desarrollo)false - Oculta detalles de errores (producción) URL base de la aplicación:
Desarrollo: http://localhost:8000
Producción: https://facturacion.tudominio.com
Usa HTTPS en producción. Los certificados digitales SUNAT requieren conexiones seguras.
Localización APP_LOCALE = es APP_FALLBACK_LOCALE = es APP_FAKER_LOCALE = es_PE
El sistema está diseñado para Perú (es_PE). Usa códigos de moneda PEN, formato de RUC/DNI, y ubigeos peruanos.
Seguridad Número de rondas para hashing de contraseñas. Mayor número = más seguro pero más lento.
Configuración de Base de Datos MySQL (Recomendado) DB_CONNECTION = mysql DB_HOST = 127.0.0.1 DB_PORT = 3306 DB_DATABASE = factura_santoD DB_USERNAME = root DB_PASSWORD = tu_password_seguro
Importante : El sistema usa MySQL por defecto. No uses SQLite en producción (solo para testing).
Crear la base de datos: CREATE DATABASE factura_santoD CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER ' factura_user '@ 'localhost' IDENTIFIED BY 'password_seguro' ; GRANT ALL PRIVILEGES ON factura_santoD. * TO 'factura_user' @ 'localhost' ; FLUSH PRIVILEGES;
SQLite (Solo Testing) DB_CONNECTION = sqlite # DB_HOST, DB_PORT, etc. se ignoran en SQLite
El archivo de base de datos se crea automáticamente en database/database.sqlite.
Los tests PHPUnit usan SQLite in-memory automáticamente (configurado en phpunit.xml).
Configuración de Cache y Sesiones Cache CACHE_STORE = database CACHE_PREFIX =
Opciones disponibles: Usa la tabla cache en MySQL. php artisan cache:table php artisan migrate
Recomendado para producción con alto tráfico. CACHE_STORE = redis REDIS_HOST = 127.0.0.1 REDIS_PASSWORD = null REDIS_PORT = 6379 REDIS_CLIENT = phpredis
Almacena cache en storage/framework/cache/data/. Sesiones SESSION_DRIVER = database SESSION_LIFETIME = 120 SESSION_ENCRYPT = false
SESSION_LIFETIME : Tiempo en minutos antes de expirar sesión (120 = 2 horas)SESSION_ENCRYPT : true para encriptar datos de sesión
Crear tabla de sesiones: php artisan session:table php artisan migrate
Configuración de Cola (Queue) QUEUE_CONNECTION = database
La cola de trabajos es obligatoria para operaciones SUNAT asíncronas:
Resumen Diario (boletas)
Comunicación de Baja (anulaciones)
Guías de Remisión GRE (consulta de tickets)
Crear tabla de jobs: php artisan queue:table php artisan migrate
Ejecutar worker: # Desarrollo php artisan queue:listen --tries=1 # Producción (con Supervisor) php artisan queue:work database --sleep=3 --tries=3 --max-time=3600
El comando composer dev inicia el queue worker automáticamente.
Configuración de Logs LOG_CHANNEL = stack LOG_STACK = single LOG_DEPRECATIONS_CHANNEL = null LOG_LEVEL = debug
Niveles de log:
debug - Todos los mensajes (desarrollo)info - Información generalwarning - Advertenciaserror - Errores (producción)
Ver logs en tiempo real: php artisan pail --timeout=0
Archivos de log: storage/logs/ ├── laravel.log # Log principal ├── laravel-2024-03-06.log # Log diario └── worker.log # Log del queue worker
Configuración de Mail MAIL_MAILER = log MAIL_HOST = 127.0.0.1 MAIL_PORT = 2525 MAIL_USERNAME = null MAIL_PASSWORD = null MAIL_FROM_ADDRESS = "[email protected] " MAIL_FROM_NAME = "${ APP_NAME }"
log (Desarrollo)
smtp (Producción)
ses (AWS)
Guarda emails en storage/logs/laravel.log sin enviarlos. Envía emails reales via SMTP. MAIL_MAILER = smtp MAIL_HOST = smtp.gmail.com MAIL_PORT = 587 MAIL_USERNAME = [email protected] MAIL_PASSWORD = tu-app-password MAIL_ENCRYPTION = tls
Usa Amazon SES para envío masivo. MAIL_MAILER = ses AWS_ACCESS_KEY_ID = AWS_SECRET_ACCESS_KEY = AWS_DEFAULT_REGION = us-east-1
Configuración de Almacenamiento Estructura de almacenamiento: storage/app/ ├── sunat/ │ ├── xml/{ruc}/ # XMLs generados │ ├── cdr/{ruc}/ # CDRs de SUNAT │ └── certificados/ # Certificados digitales ├── public/ # Archivos públicos └── private/ # Archivos privados
Importante : Los directorios en storage/app/sunat/ deben tener permisos de escritura:chmod -R 775 storage/app/sunat chown -R www-data:www-data storage/app/sunat
Configuración SUNAT Variables de Entorno # Credenciales GRE (Guías de Remisión Electrónica) SUNAT_GRE_CLIENT_ID = tu_client_id_aqui SUNAT_GRE_CLIENT_SECRET = tu_client_secret_aqui # Tasa IGV (opcional, default 0.18) SUNAT_IGV = 0.18
Configuración de Empresa La configuración específica de la empresa se almacena en la base de datos:
Tabla empresas: id_empresa: 1 ruc: 20612706702 razon_social: Santo Domingo SAC direccion: Av. Principal 123 , Lima ubigeo: 150101 -- Credenciales SOL user_sol: 20612706702ADMINPE clave_sol: [encriptada] -- Modo de operación modo: beta -- o 'production'
Sistema monempresa : Este fork solo usa id_empresa = 1. Todos los usuarios deben tener id_empresa = 1.
Modos de Operación beta (Testing)
production
Usa el ambiente de pruebas de SUNAT:
RUC : 20000000001 (automático)Usuario SOL : MODDATOS (automático)Clave SOL : moddatos (automático)Endpoints : e-beta.sunat.gob.pe No necesitas configurar credenciales SOL para pruebas. El sistema usa valores de config/sunat.php.
Usa tus credenciales reales y endpoints de producción:
RUC : Tu RUC realUsuario SOL : Configurado en BDClave SOL : Configurada en BD (encriptada)Endpoints : e-factura.sunat.gob.pe Los documentos emitidos en producción tienen validez legal ante SUNAT.
Configuración de Frontend (Vite) VITE_APP_NAME = "${ APP_NAME }" VITE_BASE_URL =
VITE_BASE_URL Permite instalar la aplicación en un subdirectorio.
Ejemplos: Raíz del dominio
Subdirectorio
# https://facturacion.com/ VITE_BASE_URL =
Uso en código: import { baseUrl } from '@/lib/baseUrl' ; // Navegación window . location . href = baseUrl ( '/ventas' ); // Links < a href = { baseUrl ( '/productos' ) } > Productos </ a > // API calls fetch ( baseUrl ( '/api/clientes' ));
Configuración de PHP Ajusta estos valores en php.ini para el sistema:
# Memoria para procesar archivos grandes memory_limit = 256M # Tamaño máximo de subida (certificados) upload_max_filesize = 10M post_max_size = 10M # Timeout para requests SUNAT max_execution_time = 120 max_input_time = 120 # Timezone Perú date.timezone = America/Lima # Extensiones requeridas extension =soap extension =xml extension =zip extension =curl extension =openssl
Variables de Mantenimiento APP_MAINTENANCE_DRIVER = file # APP_MAINTENANCE_STORE=database
Activar modo mantenimiento: # Con mensaje personalizado php artisan down --message= "Mantenimiento programado" --retry=60 # Permitir IPs específicas php artisan down --allow=192.168.1.100 --allow=192.168.1.101 # Desactivar php artisan up
Archivo de Configuración Completo
Ver .env.example completo
APP_NAME = "Santo Domingo Facturación" APP_ENV = local APP_KEY = APP_DEBUG = true APP_URL = http://localhost:8000 APP_LOCALE = es APP_FALLBACK_LOCALE = es APP_FAKER_LOCALE = es_PE APP_MAINTENANCE_DRIVER = file BCRYPT_ROUNDS = 12 LOG_CHANNEL = stack LOG_STACK = single LOG_DEPRECATIONS_CHANNEL = null LOG_LEVEL = debug DB_CONNECTION = mysql DB_HOST = 127.0.0.1 DB_PORT = 3306 DB_DATABASE = factura_santoD DB_USERNAME = root DB_PASSWORD = SESSION_DRIVER = database SESSION_LIFETIME = 120 SESSION_ENCRYPT = false SESSION_PATH = / SESSION_DOMAIN = null BROADCAST_CONNECTION = log FILESYSTEM_DISK = local QUEUE_CONNECTION = database CACHE_STORE = database MAIL_MAILER = log MAIL_HOST = 127.0.0.1 MAIL_PORT = 2525 MAIL_USERNAME = null MAIL_PASSWORD = null MAIL_FROM_ADDRESS = "[email protected] " MAIL_FROM_NAME = "${ APP_NAME }" VITE_APP_NAME = "${ APP_NAME }" VITE_BASE_URL = SUNAT_GRE_CLIENT_ID = TU_ID_DE_PRUEBA SUNAT_GRE_CLIENT_SECRET = TU_SECRET_DE_PRUEBA SUNAT_IGV = 0.18
Validar Configuración Script para validar configuración:
php artisan config:clear php artisan config:cache php artisan optimize
Verificar variables: >>> config ( 'app.name' ) => "Santo Domingo Facturación" >>> config ( 'database.connections.mysql.database' ) => "factura_santoD" >>> config ( 'sunat.endpoints.facturacion.beta' ) => "https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService"
Próximos Pasos
Base de Datos Configurar migraciones y seeders
Certificados SUNAT Setup de certificados digitales
Arquitectura Comprender la arquitectura del sistema
Inicio Rápido Guía de instalación rápida
