> For the complete documentation index, see [llms.txt](https://docs.realcity.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realcity.dev/script-docs/rc-billing/instalacion.md). # Instalación ## Guía de instalación Esta guía describe una instalación nueva, una actualización y las verificaciones mínimas antes de abrir el servidor a jugadores. ### 1. Requisitos #### Obligatorios | Componente | Uso | | ------------------ | -------------------------------------------- | | FiveM server | Ejecución del recurso Lua y de la NUI. | | ESX, QBCore o Qbox | Datos de personaje, trabajo y dinero. | | `ox_lib` | Localización y utilidades compartidas. | | `oxmysql` | Consultas y transacciones con MySQL/MariaDB. | | MySQL/MariaDB | Persistencia de facturas, pagos y auditoría. | #### Solo para facturas de empresa | Framework | Recurso esperado | | --------- | ------------------------------------------------------ | | ESX | `esx_addonaccount` | | QBCore | `qb-management` o `qb-banking` | | Qbox | Una capa compatible con `qb-management` o `qb-banking` | El terminal POS y las facturas personales pueden operar sin sociedad. Una factura empresarial requiere que el bridge pueda ingresar y, en caso de rollback, retirar fondos de la cuenta indicada. ### 2. Preparar la carpeta La carpeta debe llamarse exactamente `rc-billing`: ``` resources/ └── [realcitydev]/ └── rc-billing/ ├── fxmanifest.lua ├── config.lua ├── bridge/ ├── client/ ├── server/ ├── locales/ ├── sql/ └── web/public/ ``` Evita nombres como `rc-billing-main`, `rc-billing-v1` o una carpeta duplicada `rc-billing/rc-billing`. El nombre se utiliza en exports, callbacks NUI y ejemplos de integración. ### 3. Instalar la base de datos La base de datos se instala sola por defecto, pero en caso de que sea necesario puede instalarla ejecutando estos dos archivos: Haz una copia de seguridad antes de importar SQL en una base existente. Ejecuta los archivos en este orden: 1. `sql/invoices.sql` 2. `sql/payment_requests.sql` ### 4. Orden de inicio Las dependencias y el framework deben estar iniciados antes de `rc-billing`. #### QBCore ```cfg ensure oxmysql ensure ox_lib ensure qb-core ensure qb-management ensure rc-billing ``` Si utilizas `qb-banking`, reemplaza `qb-management` por el nombre correspondiente y confirma que expone `AddMoney` y `RemoveMoney`. #### ESX ```cfg ensure oxmysql ensure ox_lib ensure es_extended ensure esx_addonaccount ensure rc-billing ``` Las cuentas compartidas configuradas, por ejemplo `society_police`, deben existir antes del primer pago empresarial. #### Qbox ```cfg ensure oxmysql ensure ox_lib ensure qbx_core # Inicia aquí la capa bancaria compatible de tu servidor. ensure rc-billing ``` La detección utiliza el nombre oficial `qbx_core`. El bridge consume la capa de compatibilidad QB que Qbox publica mediante el export `qb-core`. ### 5. Configuración inicial Abre `config.lua` y revisa obligatoriamente: 1. `Config.Locale`. 2. `Config.AllowPersonalInvoices` y `Config.RequireAceForPersonalInvoices`. 3. `Config.CompanyJobs`. 4. `Config.PaymentAccount`. 5. `Config.MaxInvoiceAmount` y límites por empresa. 6. `Config.DefaultCommission` y comisiones específicas. 7. `Config.DiscordWebhook`. 8. Comandos y teclas predeterminadas. No publiques un webhook real dentro de un repositorio público o paquete de demostración. ### 6. Permisos ACE La creación personal puede quedar abierta o restringida: ```lua Config.AllowPersonalInvoices = true Config.RequireAceForPersonalInvoices = true Config.CreateInvoicePermission = 'rc-billing.create' ``` Ejemplo de permisos: ```cfg add_ace group.admin rc-billing.admin allow add_ace group.admin rc-billing.create allow add_ace group.moderator rc-billing.create allow ``` Si `RequireAceForPersonalInvoices` es `false`, el ACE de creación no se consulta. Si `AllowPersonalInvoices` es `false`, ninguna persona puede emitir facturas personales aunque tenga ACE. ### 7. Primera prueba Reinicia el recurso desde consola: ``` restart rc-billing ``` Conecta dos personajes y ejecuta esta prueba completa: 1. Abre `/openinvoice` con el emisor. 2. Crea una factura personal de importe pequeño. 3. Confirma que el receptor ve la solicitud. 4. Recházala y comprueba que queda cancelada. 5. Crea otra factura y acéptala. 6. Realiza un pago parcial. 7. Completa el importe y verifica el saldo de ambos. 8. Abre `/openpos`, crea una solicitud y acéptala. 9. Repite con una factura empresarial y verifica la comisión y la sociedad. 10. Revisa `invoice_payments` e `invoice_audit_logs`. ### 8. Actualizar una instalación 1. Detén `rc-billing`. 2. Copia `config.lua` y exporta las tablas del recurso. 3. Lee `CHANGELOG.md` y compara las nuevas opciones de configuración. 4. Sustituye los archivos del recurso. 5. Fusiona manualmente tu configuración anterior con la nueva. 6. Ejecuta ambos archivos SQL. Sus bloques de migración comprueban columnas e índices existentes. 7. Inicia el recurso. 8. Repite la prueba funcional básica. No elimines las tablas para actualizar: perderías historial, pagos y auditoría. ### 9. Desinstalación 1. Elimina o comenta `ensure rc-billing`. 2. Reinicia el servidor. 3. Conserva las tablas si necesitas histórico. 4. Si quieres borrar todos los datos de manera irreversible, hazlo manualmente después de una copia de seguridad. El recurso no elimina datos automáticamente al detenerse o desinstalarse. ### 10. Instalación validada La instalación está lista cuando se cumplen todos estos puntos: * No aparece `No supported framework detected`. * No hay errores de columnas o tablas en `oxmysql`. * `/openinvoice` y `/openpos` abren y cierran correctamente. * Un destinatario solo puede pagar sus propias facturas. * Una empresa recibe el importe esperado. * Una comisión llega al empleado configurado. * Los estados cambian en el orden documentado. * El build NUI servido coincide con el código de la versión. Continúa con Configuración y Solución de problemas.