Skip to main content

​
Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:
  • PHP 8.2 o superior
  • Composer
  • Node.js 18+ y npm
  • MySQL 8.0+
  • Git

​
Instalación Rápida

1

Clonar el repositorio

git clone <url-del-repositorio>
cd facturacion-santo-domingo
2

Ejecutar setup automatizado

El proyecto incluye un script composer que automatiza toda la configuración inicial:
composer setup
Este comando ejecuta automáticamente:
  • composer install - Instala dependencias PHP
  • Copia .env.example a .env (si no existe)
  • php artisan key:generate - Genera la clave de aplicación
  • php artisan migrate --force - Ejecuta migraciones de base de datos
  • npm install - Instala dependencias JavaScript
  • npm run build - Compila assets frontend
Antes de ejecutar composer setup, asegúrate de configurar la conexión a la base de datos en el archivo .env
3

Configurar base de datos

Edita el archivo .env y configura tu conexión MySQL:
.env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=factura_santoD
DB_USERNAME=root
DB_PASSWORD=tu_password
El sistema usa MySQL por defecto. Asegúrate de crear la base de datos factura_santoD antes de ejecutar las migraciones.
4

Ejecutar migraciones y seeders

Si ya ejecutaste composer setup, las migraciones ya están aplicadas. Si necesitas ejecutarlas manualmente:
php artisan migrate
php artisan db:seed
Los seeders incluyen:
  • DenominacionesBilletesSeeder: Denominaciones de billetes peruanos (S/200, S/100, S/50, etc.)
  • UtilidadesSeeder: Datos de prueba para reportes de utilidades
5

Iniciar entorno de desarrollo

Para desarrollo, usa el comando que inicia todos los servicios necesarios:
composer dev
Este comando inicia simultáneamente:
  • Servidor Laravel (php artisan serve) en http://localhost:8000
  • Worker de cola (php artisan queue:listen) para operaciones asíncronas SUNAT
  • Laravel Pail (php artisan pail) para logs en tiempo real
  • Vite HMR (npm run dev) para recarga en caliente del frontend
El worker de cola es obligatorio para las operaciones SUNAT asíncronas como Resumen Diario, Comunicación de Baja y Guías de Remisión (GRE).

​
Primer Acceso

1

Acceder a la aplicación

Abre tu navegador en:
http://localhost:8000
2

Crear usuario administrador

Por defecto, el sistema no crea un usuario admin. Debes crearlo manualmente usando tinker o crear un seeder personalizado.
Usando Laravel Tinker:
php artisan tinker

$user = new App\Models\User();
$user->name = 'Administrador';
$user->email = '[email protected]';
$user->password = bcrypt('password');
$user->rol_id = 1; // Rol Admin
$user->id_empresa = 1; // Empresa Santo Domingo
$user->save();
3

Configurar empresa

Desde el panel de administración:
  1. Navega a Configuración → Empresas
  2. Configura los datos de tu empresa:
    • RUC
    • Razón Social
    • Dirección completa con Ubigeo
    • Credenciales SOL SUNAT (para producción)
    • Modo: beta para pruebas, production para operaciones reales
El sistema está configurado para empresa única (id_empresa = 1). Todos los usuarios deben tener id_empresa = 1.
4

Subir certificado digital

Sube tu certificado digital (.pem) en:
storage/app/sunat/certificados/{RUC}-cert.pem
Para pruebas en beta, puedes usar:
storage/app/sunat/certificados/cert.pem
Ver más detalles en Certificados SUNAT

​
Configuración Básica SUNAT

​
Credenciales GRE (Guías de Remisión Electrónica)

Edita el archivo .env:
.env
SUNAT_GRE_CLIENT_ID=tu_client_id
SUNAT_GRE_CLIENT_SECRET=tu_client_secret
Las guías de remisión usan la API REST GRE que requiere credenciales OAuth2 separadas de las credenciales SOL.

​
Modo Beta vs Producción

Para pruebas (modo beta), el sistema usa automáticamente: 
RUC: 20000000001
Usuario SOL: MODDATOS
Clave SOL: moddatos
Estos valores están configurados en config/sunat.php y no necesitas cambiarlos para pruebas.

​
Comandos de Desarrollo

# Inicia servidor + queue + logs + vite
composer dev

​
Build de Producción

1

Compilar assets

npm run build
2

Optimizar autoloader

composer install --optimize-autoloader --no-dev
3

Cachear configuración

php artisan config:cache
php artisan route:cache
php artisan view:cache
4

Configurar Queue Worker como servicio

En producción, usa Supervisor para mantener el queue worker corriendo:
/etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /ruta/a/tu/proyecto/artisan queue:work database --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/ruta/a/tu/proyecto/storage/logs/worker.log
stopwaitsecs=3600

​
Verificación de Instalación

1

Verificar servicios

Asegúrate que todos los servicios estén corriendo:✅ Servidor Laravel en http://localhost:8000
✅ Queue worker procesando jobs
✅ Vite HMR en http://localhost:5173
✅ Base de datos conectada
2

Probar facturación de prueba

  1. Crea un cliente de prueba
  2. Crea un producto
  3. Genera una factura en modo beta
  4. Verifica que se genere XML en storage/app/sunat/xml/20000000001/
  5. Envía a SUNAT y verifica CDR en storage/app/sunat/cdr/20000000001/

​
Próximos Pasos

Arquitectura

Comprende la arquitectura Laravel + React del sistema

Configuración

Configuración detallada de la aplicación

Base de Datos

Estructura de la base de datos y migraciones

Certificados SUNAT

Configurar certificados digitales y credenciales

​
Problemas Comunes

Asegúrate de tener el certificado en:
storage/app/sunat/certificados/cert.pem
O específico de tu empresa:
storage/app/sunat/certificados/{TU_RUC}-cert.pem
Verifica que el queue worker esté corriendo:
php artisan queue:listen database --tries=1
O usa composer dev que lo inicia automáticamente.
Este sistema es monempresa. Solo funciona con id_empresa = 1. El selector de empresas está deshabilitado.
Asegúrate que el servidor Vite esté corriendo:
npm run dev
Y que el archivo .env tenga:
APP_URL=http://localhost:8000

Build docs developers (and LLMs) love

Get started for freeTalk to us