Saltar al contenido
Facturador

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

  1. El usuario emite la boleta o factura: fpm la guarda en la base de la empresa con estado Registrado.
  2. El sistema genera el XML, lo firma con el certificado digital y lo guarda en signed/.
  3. Lo envía a SUNAT, al OSE o al PSE, según el tipo de conexión de la empresa.
  4. La respuesta (CDR) se guarda en cdr/ y el comprobante pasa a Aceptado, Observado o Rechazado.
  5. 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.