Cómo funciona el facturador por dentro
Una página para entender qué piezas tiene una instalación del facturador y dónde está cada cosa. Sirve de mapa antes de seguir cualquier otra guía de este manual.
Piezas de una instalación con Docker
Internet (HTTP / HTTPS)
│
┌─────────▼─────────┐
│ proxy (Nginx + │ /root/proxy · red "proxynet"
│ certificados SSL)│ Un solo proxy para todos los facturadores del servidor
└─────────┬─────────┘
│
┌──────────────────────┼─────────────────────── carpeta del facturador ──┐
│ ┌─────────▼─────────┐ │
│ │ nginx │ Recibe las peticiones del dominio │
│ └─────────┬─────────┘ │
│ ┌─────────▼─────────┐ │
│ │ fpm │ PHP 8.2 + Laravel: la aplicación │
│ └──┬──────────────┬─┘ │
│ ┌─────────▼───┐ ┌────▼────┐ ┌────────────┐ ┌───────────┐ │
│ │ mariadb │ │ redis │ │ supervisor │ │scheduling │ │
│ │ bases de │ │ caché │ │ colas │ │ tareas │ │
│ │ datos │ │ │ │ │ │ programad.│ │
│ └─────────────┘ └─────────┘ └────────────┘ └───────────┘ │
└────────────────────────────────────────────────────────────────────────┘
| Contenedor | Qué hace | Si se detiene… |
|---|---|---|
| proxy | Recibe todo el tráfico del servidor, aplica el SSL y lo reparte a cada facturador según el dominio. Vive aparte, en /root/proxy. |
Ningún facturador del servidor responde. |
| nginx | Servidor web del facturador. | Ese facturador deja de responder. |
| fpm | Ejecuta la aplicación (PHP 8.2 y Laravel 9). Aquí se corren los comandos php artisan, composer y git. |
El sitio muestra error 502. |
| mariadb | Base de datos. | Error de conexión a la base de datos en todas las pantallas. |
| redis | Caché del sistema y conexión de BuhoPrinter. | El sistema se pone muy lento o da errores por tiempo de espera. |
| supervisor | Procesa las colas: trabajos que se ejecutan en segundo plano, como los reportes que se descargan desde la bandeja. | Los reportes en cola no terminan nunca. Ver Descargas de reportes en cola. |
| scheduling | Ejecuta las tareas programadas cada minuto. | No se envían los resúmenes ni las tareas automáticas, no se limpian archivos y no se miden los límites del reseller. |
Para ver el estado de todos: docker ps. Para entrar a uno: docker exec -it [nombre_contenedor] bash. Ver Iniciar los servicios Docker.
Una base central y una base por empresa
El facturador es multiempresa: un solo sistema atiende a muchas empresas, cada una en su subdominio (empresa1.tudominio.com).
| Base de datos | Qué guarda |
|---|---|
Central (DB_DATABASE del .env) |
El panel del administrador: clientes (empresas), sus dominios, planes, pagos y configuración general. |
Una por empresa (tenancy_...) |
Todo lo de esa empresa: comprobantes, productos, clientes, caja, usuarios. Cada una tiene su propio usuario de base de datos. |
Por eso cada actualización tiene dos comandos de migración:
php artisan migrate # base central
php artisan tenancy:migrate # bases de todas las empresas
Para saber qué base corresponde a cada empresa, ejecute esta consulta en la base central (Acceso a la base de datos):
SELECT c.name AS empresa, h.fqdn AS dominio, w.uuid AS base_de_datos
FROM clients c
JOIN hostnames h ON h.id = c.hostname_id
JOIN websites w ON w.id = h.website_id;
Tareas programadas
El contenedor scheduling ejecuta php artisan schedule:run cada minuto. Ese comando decide qué tareas tocan en ese momento. Las principales:
| Tarea | Frecuencia | Qué hace |
|---|---|---|
tenant:run |
Cada minuto | Ejecuta las tareas que cada empresa programó (envíos, resúmenes) a la hora indicada. |
tenant-schedules:dispatch |
Cada minuto | Suscripciones, campañas de descuento y órdenes de impresión de las empresas que las usan. |
storage:clean |
Cada 15 minutos | Limpieza de archivos que configuró cada empresa. |
reseller:storage-measure |
Cada 10 minutos | Mide el espacio usado para el límite de almacenamiento. |
order:payments |
Cada hora | Órdenes de pago del panel del administrador. |
backup:prune |
Diario, 05:00 | Borra los respaldos vencidos de la bandeja del administrador. |
No agregue `tenancy:run schedule:run` al cron
Cada tarea ya recorre las empresas por su cuenta. Ese comando repite todo el agendamiento una vez por empresa y satura la CPU del servidor.
Más detalle en Tareas programadas (cron).
Dónde están los archivos
Las rutas son relativas a la carpeta del facturador.
| Ruta | Qué contiene |
|---|---|
.env |
Configuración de la instalación. Ver Parámetros del archivo .env. |
storage/app/tenancy/tenants/[empresa]/ |
Archivos de cada empresa: signed/ (XML firmados), cdr/ (constancias de SUNAT), pdf/, unsigned/ y otros. |
storage/app/public/ |
Logos e imágenes subidas. |
storage/logs/ |
Logs de la aplicación: laravel-[fecha].log y uno por cada tarea programada. |
app/CoreFacturalo/Templates/pdf/ |
Plantillas PDF. Ver Plantilla PDF personalizada. |
modules/ |
Módulos del sistema (restaurante, hotel, tienda virtual, WhatsApp, etc.). |
Lo que nunca se borra
signed/ y cdr/ son el respaldo legal de cada comprobante ante SUNAT y no se pueden volver a generar. Inclúyalos siempre en los respaldos.
Cómo se emite un comprobante
- El usuario emite la boleta o factura: fpm la guarda en la base de la empresa con estado Registrado.
- El sistema genera el XML, lo firma con el certificado digital y lo guarda en
signed/. - Lo envía a SUNAT, al OSE o al PSE, según el tipo de conexión de la empresa.
- La respuesta (CDR) se guarda en
cdr/y el comprobante pasa a Aceptado, Observado o Rechazado. - El PDF se genera en
pdf/. Si falta, se vuelve a generar cuando alguien lo descarga.
Las boletas se pueden enviar después, agrupadas en un resumen diario, con las tareas programadas de cada empresa.