Skip to main content

​
Variables de Entorno

Todas las configuraciones del sistema se gestionan a través del archivo .env en la raíz del proyecto. Este archivo contiene las credenciales y configuraciones sensibles que no deben ser versionadas.

​
Configuración de la Aplicación

​
Configuración Básica

Configura los valores básicos de tu aplicación: 
APP_NAME="Facturación Electrónica"
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost:8000
Parámetros:
  • APP_NAME - Nombre de la aplicación (aparece en correos y notificaciones)
  • APP_ENV - Entorno de ejecución (local, staging, production)
  • APP_KEY - Clave de encriptación (generada con php artisan key:generate)
  • APP_DEBUG - Activar modo debug (usar false en producción)
  • APP_URL - URL base de la aplicación
En producción, establece APP_ENV=production y APP_DEBUG=false para mejorar la seguridad y el rendimiento.

​
Configuración de Logs

LOG_CHANNEL=stack
LOG_STACK=single
LOG_LEVEL=debug
En producción, considera cambiar LOG_LEVEL=info o LOG_LEVEL=error para reducir el tamaño de los logs.

​
Configuración de Base de Datos

​
Opción 1: SQLite (Por Defecto)

La configuración por defecto usa SQLite, ideal para desarrollo y despliegues pequeños: 
DB_CONNECTION=sqlite
Asegúrate de que el archivo de base de datos existe: 
touch database/database.sqlite
Ventajas de SQLite:
  • Sin servidor de base de datos requerido
  • Configuración cero
  • Ideal para desarrollo y testing
  • Perfecto para instalaciones de un solo servidor

​
Opción 2: MySQL (Recomendado para Producción)

Para producción o instalaciones multi-usuario, se recomienda MySQL: 
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=facturacion_electronica
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_contraseña_segura
Parámetros:
  • DB_HOST - Host del servidor MySQL
  • DB_PORT - Puerto del servidor (por defecto 3306)
  • DB_DATABASE - Nombre de la base de datos
  • DB_USERNAME - Usuario de la base de datos
  • DB_PASSWORD - Contraseña del usuario
1
Crear Base de Datos MySQL
2
Conéctate a MySQL y crea la base de datos:
3
CREATE DATABASE facturacion_electronica 
  CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;
4
Crear Usuario y Otorgar Permisos
5
CREATE USER 'facturacion'@'localhost' IDENTIFIED BY 'contraseña_segura';
GRANT ALL PRIVILEGES ON facturacion_electronica.* TO 'facturacion'@'localhost';
FLUSH PRIVILEGES;
6
Ejecutar Migraciones
7
php artisan migrate

​
Configuración de SUNAT

El sistema se integra con SUNAT para la emisión de comprobantes electrónicos. Debes configurar las credenciales y certificados digitales.

​
Variables SUNAT Básicas

# Tasa IGV (por defecto 18%)
SUNAT_IGV=0.18

# Entorno (beta para pruebas, production para producción)
SUNAT_ENVIRONMENT=beta

​
Credenciales SOL de SUNAT

Para cada empresa, necesitarás configurar las credenciales SOL (Clave SOL) de SUNAT: Ambiente de Pruebas (Beta): SUNAT proporciona credenciales de prueba predeterminadas: 
# Credenciales de prueba SUNAT
RUC: 20000000001
Usuario SOL: MODDATOS
Clave SOL: moddatos
Estas credenciales se usan automáticamente cuando SUNAT_ENVIRONMENT=beta. Ambiente de Producción: Las credenciales SOL reales se configuran por empresa dentro del sistema (ver sección Primeros Pasos). Cada empresa registrada debe tener:
  • RUC de la empresa
  • Usuario SOL (proporcionado por SUNAT)
  • Clave SOL (proporcionado por SUNAT)
  • Certificado digital (.pem)

​
Configuración de Guías de Remisión Electrónicas (GRE)

Para emitir guías de remisión electrónicas a través de la API REST de SUNAT, necesitas credenciales OAuth: 
SUNAT_GRE_CLIENT_ID=tu_client_id
SUNAT_GRE_CLIENT_SECRET=tu_client_secret
1
Obtener Credenciales GRE
2
  • Ingresa a SUNAT Operaciones en Línea con tu Clave SOL
  • Ve a Sistema de Emisión Electrónica > Guías de Remisión Electrónica
  • Solicita las credenciales del API REST (Client ID y Client Secret)
  • SUNAT te proporcionará las credenciales por correo electrónico
    • Las credenciales GRE son necesarias solo si planeas emitir guías de remisión electrónicas. Para facturas y boletas no son requeridas.

    ​
    Configuración de Certificados Digitales

    Los comprobantes electrónicos deben ser firmados digitalmente con un certificado válido.

    ​
    Certificado de Prueba

    Para el ambiente de pruebas (beta), puedes usar un certificado de prueba. Coloca el archivo en: 
    storage/app/sunat/certificados/cert.pem

    ​
    Certificado de Producción

    Para producción, cada empresa debe tener su certificado digital:
    1
    Obtener Certificado Digital
    2
  • Adquiere un certificado digital de una entidad certificadora autorizada por SUNAT (ej: RENIEC, VerifySign, etc.)
  • Convierte el certificado a formato PEM si está en otro formato:
    • 3
    openssl pkcs12 -in certificado.pfx -out certificado.pem -nodes
    4
    Subir Certificado al Sistema
    5
  • Coloca el certificado en storage/app/sunat/certificados/
  • Renombra el archivo con el RUC de la empresa: {RUC}.pem
  • Ejemplo: 20612706702.pem
    • 6
    Configurar Permisos
    7
    chmod 600 storage/app/sunat/certificados/*.pem
chown www-data:www-data storage/app/sunat/certificados/*.pem

    ​
    Configuración de Almacenamiento

    El sistema almacena archivos XML, CDR y certificados en el sistema de archivos local.

    ​
    Configuración por Defecto

    FILESYSTEM_DISK=local
    Los archivos se almacenan en:
    • XML generados: storage/app/sunat/xml/{ruc}/
    • CDR de SUNAT: storage/app/sunat/cdr/{ruc}/
    • Certificados: storage/app/sunat/certificados/

    ​
    Crear Directorios de Almacenamiento

    mkdir -p storage/app/sunat/xml
mkdir -p storage/app/sunat/cdr
mkdir -p storage/app/sunat/certificados
chmod -R 775 storage/app/sunat

    ​
    Almacenamiento en S3 (Opcional)

    Para almacenar archivos en AWS S3: 
    FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=tu_access_key
AWS_SECRET_ACCESS_KEY=tu_secret_key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=tu_bucket_sunat
AWS_USE_PATH_STYLE_ENDPOINT=false

    ​
    Configuración de Colas

    El sistema usa colas para operaciones asíncronas con SUNAT (Resumen Diario, Comunicación de Baja, etc.). 
    QUEUE_CONNECTION=database
    Opciones disponibles:
    • database - Usa la base de datos (recomendado para empezar)
    • redis - Usa Redis (mejor rendimiento en producción)
    • sync - Procesamiento síncrono (solo para testing)

    ​
    Configurar Worker de Colas

    En producción, configura un servicio systemd para ejecutar el worker permanentemente: 
    php artisan queue:work --tries=3 --timeout=90
    O usa el comando de desarrollo que incluye el worker: 
    composer dev
    El worker de colas es obligatorio para que funcionen correctamente:
    • Resumen Diario de Boletas
    • Comunicación de Baja (anulaciones)
    • Consulta de tickets de Guías de Remisión

    ​
    Configuración de Sesiones

    SESSION_DRIVER=database
SESSION_LIFETIME=120
    • SESSION_DRIVER - Dónde se almacenan las sesiones (database, file, redis)
    • SESSION_LIFETIME - Duración de la sesión en minutos

    ​
    Configuración de Cache

    CACHE_STORE=database
    En producción con tráfico alto, considera usar Redis: 
    CACHE_STORE=redis
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

    ​
    Configuración de Correo Electrónico

    Para enviar comprobantes por correo: 
    MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=tu_contraseña_app
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="${APP_NAME}"

    ​
    Verificar Configuración

    Después de configurar el archivo .env, limpia y cachea la configuración: 
    php artisan config:clear
php artisan config:cache
php artisan route:cache
    Para desarrollo, mantén la configuración sin cachear para ver cambios inmediatamente: 
    php artisan config:clear

    ​
    Configuración de Producción

    Checklist para configuración de producción:
    1
    Seguridad
    2
    APP_ENV=production
APP_DEBUG=false
APP_URL=https://tudominio.com
    3
    Base de Datos
    4
  • Usa MySQL en lugar de SQLite
  • Configura backups automáticos
  • Usa contraseñas seguras
    • 5
    SUNAT Producción
    6
    SUNAT_ENVIRONMENT=production
    7
  • Configura credenciales SOL reales
  • Instala certificados digitales válidos
  • Prueba en ambiente beta primero
    • 8
    Optimización
    9
    php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --optimize-autoloader --no-dev
    10
    Worker de Colas
    11
  • Configura supervisor o systemd para el worker
  • Monitorea el estado del worker
  • Configura reinicio automático en caso de fallos
    • 12
    SSL/HTTPS
    13
  • Instala certificado SSL válido
  • Fuerza HTTPS en la configuración del servidor
  • Actualiza APP_URL con https://

    • ​
    Próximos Pasos

    Ahora que has configurado el sistema, continúa con:
    • Primeros Pasos - Crea tu primera empresa y emite tu primer comprobante

    Build docs developers (and LLMs) love

    Get started for freeTalk to us