Skip to main content

​
Requisitos del Sistema

Antes de comenzar con la instalación, asegúrate de tener los siguientes requisitos:

​
Requisitos de Software

  • PHP: 8.2 o superior
  • Composer: Gestor de dependencias de PHP
  • Node.js: 18.x o superior
  • npm: Gestor de paquetes de Node.js
  • Base de datos: SQLite (por defecto) o MySQL 8.0+
  • Extensiones PHP requeridas:
    • OpenSSL
    • PDO
    • Mbstring
    • Tokenizer
    • XML
    • Ctype
    • JSON
    • BCMath
    • Fileinfo
    • GD o Imagick (para generación de QR)

​
Requisitos de Hardware

  • RAM: Mínimo 2GB (4GB recomendado)
  • Disco: Mínimo 1GB de espacio libre
  • CPU: 2 cores o más recomendado

​
Instalación

1
Clonar el Repositorio
2
Clona el repositorio del proyecto en tu máquina local:
3
git clone [URL_DEL_REPOSITORIO]
cd facturacion-electronica
4
Instalar Dependencias Backend
5
Instala las dependencias de PHP usando Composer:
6
composer install
7
Esto instalará todos los paquetes necesarios incluyendo:
8
  • Laravel Framework 12.x
  • Greenter (biblioteca para integración SUNAT)
  • Laravel Sanctum (autenticación API)
  • mPDF (generación de PDFs)
  • PhpSpreadsheet (exportación Excel)
  • Chillerlan QR Code (códigos QR para comprobantes)
    • 9
    Configurar Variables de Entorno
    10
    Copia el archivo de ejemplo de configuración:
    11
    cp .env.example .env
    12
    Genera la clave de aplicación de Laravel:
    13
    php artisan key:generate
    14
    Crear la Base de Datos
    15
    Para SQLite (configuración por defecto):
    16
    touch database/database.sqlite
    17
    Para MySQL:
    18
    Crea una base de datos vacía en tu servidor MySQL:
    19
    CREATE DATABASE facturacion_electronica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    20
    Luego actualiza tu archivo .env con las credenciales de MySQL (ver sección de Configuración).
    21
    Ejecutar Migraciones
    22
    Ejecuta las migraciones para crear las tablas de la base de datos:
    23
    php artisan migrate --force
    24
    Instalar Dependencias Frontend
    25
    Instala las dependencias de Node.js:
    26
    npm install
    27
    Esto instalará:
    28
  • React 19.x
  • Vite (bundler)
  • TailwindCSS 4.x
  • Radix UI (componentes)
  • TanStack Table (tablas de datos)
  • Zustand (gestión de estado)
    • 29
    Compilar Assets Frontend
    30
    Compila los assets de React para producción:
    31
    npm run build
    32
    Para desarrollo, usa:
    33
    npm run dev
    34
    Configurar Permisos de Almacenamiento
    35
    Asegúrate de que Laravel tenga permisos de escritura en los directorios de almacenamiento:
    36
    chmod -R 775 storage bootstrap/cache
    37
    Crea los directorios necesarios para archivos SUNAT:
    38
    mkdir -p storage/app/sunat/xml
mkdir -p storage/app/sunat/cdr
mkdir -p storage/app/sunat/certificados
    39
    Verificar la Instalación
    40
    Inicia el servidor de desarrollo:
    41
    php artisan serve
    42
    Abre tu navegador en http://localhost:8000 para verificar que la aplicación esté funcionando correctamente.

    ​
    Instalación Rápida con Composer

    Alternativamente, puedes usar el comando de configuración automatizada que ejecuta todos los pasos necesarios: 
    composer setup
    Este comando ejecuta automáticamente:
    1. composer install - Instala dependencias PHP
    2. Copia .env.example a .env (si no existe)
    3. php artisan key:generate - Genera clave de aplicación
    4. php artisan migrate --force - Ejecuta migraciones
    5. npm install - Instala dependencias Node.js
    6. npm run build - Compila assets frontend

    ​
    Modo Desarrollo

    Para iniciar el entorno completo de desarrollo (servidor Laravel + worker de colas + logs + Vite HMR): 
    composer dev
    Este comando inicia automáticamente:
    • Servidor Laravel (php artisan serve) en http://localhost:8000
    • Worker de colas (php artisan queue:listen) para operaciones asíncronas SUNAT
    • Monitor de logs (php artisan pail) para visualización de logs en tiempo real
    • Vite dev server (npm run dev) para Hot Module Replacement
    El worker de colas es requerido para operaciones SUNAT asíncronas como Resumen Diario de Boletas y Comunicación de Baja.

    ​
    Verificación de Requisitos

    Verifica que tu servidor cumple con todos los requisitos de Laravel: 
    php artisan about
    Este comando mostrará información sobre tu entorno, incluyendo versiones de PHP, base de datos y extensiones instaladas.

    ​
    Solución de Problemas Comunes

    ​
    Error: “Class ‘XMLWriter’ not found”

    Instala la extensión XML de PHP: 
    # Ubuntu/Debian
sudo apt-get install php8.2-xml

# macOS (Homebrew)
brew install [email protected]

    ​
    Error: “Failed to open stream: Permission denied”

    Verifica los permisos de los directorios de almacenamiento: 
    sudo chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

    ​
    Error de Memoria en Composer

    Si encuentras errores de memoria durante composer install: 
    php -d memory_limit=-1 /usr/local/bin/composer install

    ​
    Node.js Version Mismatch

    Si tienes problemas con la versión de Node.js, considera usar nvm: 
    nvm install 20
nvm use 20
npm install

    ​
    Próximos Pasos

    Ahora que has instalado el sistema, continúa con:
    • Configuración - Configura variables de entorno y credenciales SUNAT
    • Primeros Pasos - Crea tu primera empresa y emite tu primer comprobante

    Build docs developers (and LLMs) love

    Get started for freeTalk to us