Documentación oficial de UtilARA ERP: ERP multiempresa con contabilidad, facturación, cuentas por cobrar y por pagar, compras, inventario, banco, activos fijos, caja chica, punto de venta, proyectos, nómina y una plataforma de apps instalables (NCF/DGII, CRM, RRHH, Dental, Veterinaria).

Las siete secciones

Empieza por aquí

Cómo leer esta documentación

Todo lo que hay aquí está verificado contra el sistema real (código, endpoints, base de datos y ejecución). No se describe funcionalidad que el sistema no tenga: cuando algo no existe o está a medias, el artículo lo dice.

Cada artículo indica su estado:

Cinco cosas que conviene saber desde el principio

1. Guardar no es contabilizar. Un documento guardado es un borrador: no consume

comprobante fiscal, no descuenta inventario y no genera asiento. Eso ocurre al postear.

1. El NCF se emite al postear. Un borrador abandonado no gasta numeración fiscal, y un

posteo fallido tampoco.

1. Lo contabilizado no se edita: se revierte. Una factura posteada se corrige con una

anulación o una nota de crédito, nunca reescribiéndola. Es lo que mantiene la contabilidad auditable.

1. Empresa, sucursal, almacén y tienda son cuatro cosas distintas. Elegir mal al

implantar es el error más caro de deshacer. Consulta Empresas, sucursales, almacenes y tiendas en Administración.

1. Los permisos se validan en el servidor. Ocultar un botón es solo comodidad; el control

real está detrás.

Limitaciones conocidas

Para que nadie planifique sobre algo que no existe:

Documentación interna

Existe además documentación técnica, de referencia de API completa y comercial que no se publica en este centro de ayuda: está dirigida al equipo que opera la plataforma.

Esta guía te lleva desde un sistema recién entregado hasta emitir tu primera factura y registrar tu primer cobro. Son 10 pasos, en orden. Cada paso enlaza a su artículo con el detalle: la ruta exacta del menú, los campos obligatorios y qué queda registrado.

Tiempo estimado: entre 2 y 4 horas si ya tienes los datos a mano (RNC, catálogo de productos, listado de clientes y los NCF autorizados por la DGII).

Antes de empezar, ten a mano

Los 10 pasos

Al terminar, revisa el Checklist de puesta en marcha para confirmar que no quedó nada a medias antes de operar en serio.

Cómo leer esta documentación

Cada artículo indica su estado verificado contra el sistema real:

Cuando algo no existe, esta documentación lo dice. No se describe funcionalidad que el sistema no tenga.

---

section: primeros-pasos subsection: inicio-rapido order: 110 visibility: WEB status: PUBLISHED category: Inicio rápido tags: [checklist, puesta-en-marcha] excerpt: Verificación final antes de operar en producción: 25 puntos que se comprueban en pantalla.

---

Checklist de puesta en marcha

Recorre esta lista en el sistema, no de memoria. Cada punto se comprueba abriendo la pantalla indicada.

Empresa y contabilidad

• [ ] Contabilidad → Plan de Cuentas muestra el catálogo con cuentas.
• [ ] Contabilidad → Períodos Contables tiene los 12 meses del año, y el mes actual está abierto.
• [ ] Seguridad → Configuración → Configurar Compañía tiene RNC, razón social y dirección.
• [ ] Seguridad → Configuración → Configurar Contabilidad tiene asignadas las cuentas de

Cuentas por Cobrar, Ingresos, ITBIS por Pagar, Caja, Cuentas por Pagar, Inventarios y Costo de Ventas.

• [ ] Contabilidad → Configuración → Dimensiones tiene tus sucursales creadas.

Monedas

• [ ] Banco → Moneda lista DOP marcada como base.
• [ ] Si operas en dólares, USD está activa y tiene tasa de cambio cargada

(Banco → Cambio Tasa).

Usuarios y seguridad

• [ ] Seguridad → Configuración → Configurar Usuarios tiene una política de contraseña

razonable (mínimo ≥ 10, letras y números) y bloqueo por intentos activado.

• [ ] Existe más de un usuario con perfil Administrador.
• [ ] Cada persona tiene su propia cuenta — ninguna cuenta compartida.
• [ ] Los perfiles asignados corresponden a lo que cada quien realmente necesita.
• [ ] La verificación en dos pasos está activa al menos para los administradores.

Impuestos y comprobantes

• [ ] Impuestos → Reglas Fiscales tiene la regla de ITBIS con su vigencia.
• [ ] Impuestos → Serie Fiscal tiene al menos una secuencia activa y vigente (B01 y/o B02).
• [ ] Impuestos → Consulta NCF muestra disponibilidad suficiente y el umbral de alerta configurado.
• [ ] Si usas retenciones, están dadas de alta en Impuestos → Retenciones.

Catálogos comerciales

• [ ] Contabilidad → Tipos de Pago tiene los medios que realmente usas.
• [ ] Cuentas por Cobrar → Condición de Pago tiene al menos Contado y una de crédito,

y hay una marcada por defecto.

• [ ] Cuentas por Cobrar → Cliente tiene tus clientes, con RNC correcto.
• [ ] Inventario → Ítem tiene tu catálogo, con unidad y categoría.

Inventario

• [ ] Inventario → Almacén tiene tus almacenes.
• [ ] Inventario → Existencia en Almacén muestra cantidad y costo — no cero.
• [ ] Contabilidad → Balanza Comprobación muestra saldo en la cuenta Inventarios

coherente con la valuación.

Prueba de punta a punta

• [ ] Emitiste una factura de prueba y recibió NCF.
• [ ] El inventario del artículo bajó en la cantidad vendida.
• [ ] El asiento de venta y el de costo aparecen en Contabilidad → Diario y cuadran.
• [ ] Registraste el cobro y el saldo de la factura llegó a cero.
• [ ] La factura de prueba aparece en Impuestos → Reporte 607.
• [ ] Anulaste la factura de prueba y verificaste que el inventario se repuso, los asientos

quedaron en cero y el NCF pasó al 608.

Antes de dar acceso al equipo

• [ ] Definiste quién puede cerrar períodos (accounting:close-period) — no debería ser todo el mundo.
• [ ] Definiste quién puede ver costos de inventario (inventory:view-cost).
• [ ] Definiste quién puede anular documentos (permisos :delete).
• [ ] Sabes dónde consultar la bitácora de actividad para auditar cambios.

Si algún punto falla, corrígelo antes de empezar a operar. Arreglar datos después de facturar cuesta mucho más que configurarlos bien al principio.

---

section: primeros-pasos subsection: inicio-rapido order: 20 visibility: WEB status: PUBLISHED category: Inicio rápido tags: [sucursales, dimensiones, centros-de-costo] excerpt: Las sucursales son una dimensión contable: permiten ver resultados por local sin duplicar empresas.

---

Paso 2 — Crea tus sucursales

Estado: Operativo. Las sucursales se crean, se asignan a los asientos y a las líneas de presupuesto, y filtran los reportes contables. No tienen numeración de documento propia.

Qué es una sucursal aquí

Una sucursal es una dimensión contable dentro de una empresa: una etiqueta que viaja con los asientos y permite ver el Mayor, el Estado de Resultados y el presupuesto por local, sin crear una contabilidad separada.

Junto a las sucursales existen otras dos dimensiones del mismo tipo:

Si cada local tiene su propio RNC, no es una sucursal: es otra empresa (paso 1).

Permisos necesarios

Procedimiento

Contabilidad → Configuración (/accounting/config)

Baja hasta la sección Dimensiones. Verás tres tarjetas: Centros de Costo, Departamentos y Sucursales.

Paso 1. Escribir el código

Campo Código — corto y estable, p. ej. SD, STGO, ZONA-E. El sistema lo guarda en mayúsculas automáticamente.

Paso 2. Escribir el nombre

Campo Nombre — el nombre legible: Santo Domingo, Sucursal Santiago.

Paso 3. Pulsar +

La sucursal aparece en la lista de la tarjeta.

El código es único por empresa: no puedes tener dos sucursales con el mismo código dentro de la misma empresa.

Dónde se usa después

Lo que una sucursal no hace

Para separar existencias por local usa almacenes; para separar cajas usa tiendas. La sucursal es la dimensión contable que los cruza.

Cómo verificar

En Contabilidad → Mayor General, el filtro Sucursal debe listar las que creaste.

Siguiente

Paso 3 — Crea tus usuarios.

---

section: primeros-pasos subsection: inicio-rapido order: 90 visibility: WEB status: PUBLISHED category: Inicio rápido tags: [factura, ncf, venta, contabilidad] excerpt: De borrador a factura posteada: qué pide la pantalla, cuándo se emite el NCF y qué asiento genera.

---

Paso 9 — Emite tu primera factura

Estado: Listo. La factura selecciona artículos reales, valida existencias, descuenta inventario, genera el costo de venta, emite el NCF al postear y contabiliza.

Requisitos previos

Permisos

Se validan en el servidor: manipular la pantalla no salta el control.

Ruta

Facturación → Factura → Factura (/facturacion/factura/nuevo)
Facturación → Factura → Buscar Factura (/facturacion/factura/buscar)

Paso 1. Encabezado

Paso 2. Líneas

Columnas: Artículo · Descripción · Disp. · Cantidad · Precio · Desc% · ITBIS% · Total.

• Disp. muestra la existencia disponible en el almacén elegido.
• Al elegir el artículo se traen su descripción, precio e ITBIS; puedes ajustarlos.
• Al pie se calculan Subtotal, ITBIS y Total.

Paso 3. Cobro (según la condición)

Si la condición es contado, aparece el bloque Cobro de contado. Si es crédito, puedes marcar Registrar pago inicial.

Si ves "No hay cajas ni cuentas bancarias activas", crea la cuenta en el módulo Banco antes de cobrar de contado.

En crédito, si el cliente tiene límite de crédito, la pantalla lo muestra y avisa cuando la factura podría superarlo. El servidor bloquea el posteo si se excede.

Paso 4. Guardar y postear

Son dos acciones distintas:

Un posteo fallido no consume ningún número fiscal.

Qué queda registrado al postear

Paso 5. Entregar el comprobante

En una factura ya guardada aparecen las acciones del documento:

• Vista previa y descarga en PDF — con RNC y dirección del emisor, RNC del comprador,

vigencia del NCF y desglose de ITBIS.

• Imprimir, individual o en lote (Facturación → Factura → Imprimir Facturas en lote).
• Enviar por correo con el PDF adjunto; queda historial de envíos y se puede reintentar.

Si algo sale mal

Para corregir una factura ya emitida

• Anular — revierte el asiento y el inventario; el NCF pasa al reporte 608 y no se reutiliza.
• Nota de crédito — para devoluciones o ajustes parciales.

Ambos casos están documentados en la Base de conocimiento.

Siguiente

Paso 10 — Registra tu primer cobro.

Estado: Listo. La inicialización crea empresa, monedas, plan de cuentas, períodos fiscales, tipos de pago y conceptos contables en una sola operación.

Objetivo

Dejar creada la empresa sobre la que se registra todo (companyId) y completar los datos fiscales que aparecen impresos en cada factura.

Permisos necesarios

Los perfiles Administrador y Gerente los tienen por defecto.

Parte A — Inicializar (solo la primera vez)

Contabilidad → Configuración (/accounting/config)

Si el sistema todavía no tiene ninguna empresa, la pantalla muestra el botón Inicializar ahora. Al pulsarlo, el sistema crea de una vez:

La inicialización es segura de repetir: si ya existe una empresa, no la duplica ni sobrescribe el plan de cuentas.

Parte B — Completar los datos fiscales

Seguridad → Configuración → Configurar Compañía (/security/config/compania)

Selecciona la empresa arriba y completa:

Identidad

Contacto y dirección

Dirección, Dirección 2, Teléfono, Correo, Sitio web y Sucursal / Establecimiento. Todos se imprimen en el encabezado del comprobante.

Comprobante

Pulsa Guardar.

Parte C — Empresas adicionales (opcional)

Si operas varias razones sociales, cada una es una empresa distinta con su propio plan de cuentas, numeración y contabilidad. Se crean desde Contabilidad → Configuración, con Código (p. ej. SUC2) y Nombre.

Empresa ≠ Sucursal. Una empresa es una entidad legal con contabilidad propia. Una sucursal es una dimensión dentro de una empresa (paso 2). Si tus locales facturan bajo el mismo RNC, son sucursales, no empresas.

Cómo verificar que quedó bien

1. Contabilidad → Plan de Cuentas muestra el catálogo con cuentas.
2. Contabilidad → Períodos Contables muestra los 12 meses del año, abiertos.
3. Contabilidad → Tipos de Pago muestra Efectivo, Transferencia, Tarjeta y Cheque.
4. En Configurar Compañía, el campo RNC está lleno.

Problemas frecuentes

Siguiente

Paso 2 — Crea tus sucursales.

Estado: Listo. Alta con contraseña, invitación por enlace, asignación de perfiles y protección del último administrador, todo verificado en el backend.

Antes de crear usuarios

Define la política de contraseñas primero: se aplica en el momento del alta, así que si la endureces después, los usuarios ya creados conservan su contraseña anterior.

Seguridad → Configuración → Configurar Usuarios (/security/config/usuarios)

Para producción se recomienda al menos: mínimo 10, letras y números, y bloqueo tras 5 intentos.

Permisos necesarios

Opción A — Crear el usuario con contraseña

Seguridad → Usuarios → Usuario (/security/usuario/nuevo)

El usuario queda activo de inmediato y ya puede iniciar sesión.

Opción B — Invitar por correo

Al invitar, el sistema crea el usuario inactivo y devuelve un enlace de invitación válido por 7 días. Cuando la persona lo abre, define su propia contraseña y la cuenta se activa.

• El enlace tiene la forma https://<tu-dominio>/accept-invite?t=<empresa>&token=…
• Está limitado a 20 invitaciones por hora.
• La invitación incluye los perfiles que le asignes.

Asignar perfiles

Seguridad → Usuarios → Perfiles Usuario (/security/usuario/perfiles)

Vienen tres perfiles listos para usar:

Si necesitas algo distinto, crea un perfil propio (ver Roles y permisos en Administración).

Protección del último administrador

El sistema impide desactivar, eliminar o quitarle el perfil ADMIN al último administrador activo. Si lo intentas verás:

No se puede dejar el tenant sin al menos un administrador activo

Crea primero el nuevo administrador y después modifica el anterior.

Límite de usuarios

Cada plan tiene un tope de usuarios. Si lo alcanzas, el alta y la invitación fallan con un mensaje de límite. Consulta el plan contratado antes de dar de alta a todo el equipo.

Cómo verificar

Seguridad → Usuarios → Buscar Usuarios lista los usuarios con su estado y perfiles.

Problemas frecuentes

Siguiente

Paso 4 — Configura impuestos y comprobantes fiscales.

Estado: Listo. Reglas fiscales con vigencia, retenciones y secuencias de NCF con numeración sin saltos, verificadas de punta a punta.

Este paso tiene dos partes independientes: el impuesto (cuánto se cobra) y el comprobante (con qué número fiscal se emite). Necesitas las dos para facturar.

Parte A — Reglas fiscales (ITBIS)

Impuestos → Reglas y Retenciones → Reglas Fiscales (/impuestos/reglas-fiscales)

Una regla fiscal define la tasa que se aplica y desde cuándo. Las reglas tienen vigencia: cuando la tasa cambia, no se edita la regla anterior — se crea una nueva vigencia, de modo que un documento viejo sigue calculando con la tasa que tenía el día en que se emitió.

Cambio de tasa: usa Nueva vigencia, no Editar. Editar la regla cambia el cálculo de todo, incluido lo ya emitido.

Parte B — Retenciones

Impuestos → Reglas y Retenciones → Retenciones (/impuestos/retenciones)

Categorías de retención (ITBIS retenido, ISR retenido) que se aplican al pagar a proveedores. El sistema calcula la retención automáticamente; un usuario con el permiso tax:override-calculation puede sustituir el monto calculado, y esa sustitución queda auditada.

Parte C — Secuencias de NCF

Impuestos → Serie Fiscal (/impuestos/serie-fiscal/nuevo)

Cada rango que la DGII te autoriza se registra como una secuencia:

No puedes registrar dos secuencias del mismo tipo con el mismo número inicial en la misma empresa.

Tipos de comprobante disponibles

Para la mayoría de empresas basta empezar con B01 (clientes con RNC) y B02 (consumidor final).

Formato del número emitido

El sistema emite B + tipo (2 dígitos) + secuencial (8 dígitos), 11 caracteres sin guiones:

B0100000026

Cuándo se consume el NCF — importante

El NCF se asigna al contabilizar (postear) la factura, no al guardarla como borrador.

Esto es lo que hace que la numeración fiscal no tenga saltos.

Parte D — Configuración de impuesto por defecto (opcional)

Seguridad → Configuración → Configurar Impuesto (/security/config/impuesto)
Impuestos → Impuesto Configuración (/impuestos/configuracion/nuevo)

Valores por defecto que el sistema propone al crear documentos.

Cómo verificar

1. Impuestos → Consulta NCF muestra las secuencias con su consumo y disponibilidad.
2. Crea una factura de prueba, postéala y confirma que recibió un NCF con el formato de 11

caracteres.

1. Impuestos → Reporte 607 debe incluir esa factura.

Sobre e-CF (facturación electrónica)

El sistema tiene el módulo de e-CF implementado contra la API real de la DGII (autenticación por semilla firmada, envío y consulta de estado). Requiere tu certificado digital y su clave, que se cargan en la configuración de e-CF. Consulta el artículo e-CF / DGII en Integraciones antes de activarlo en producción: la habilitación depende de tu proceso de certificación con la DGII, no solo del sistema.

Siguiente

Paso 5 — Revisa las formas de pago y condiciones.

Estado: Listo. Los tipos de pago se crean en la inicialización; las condiciones controlan de verdad el vencimiento, el límite de crédito y el descuento por pronto pago.

Son dos catálogos distintos y suelen confundirse:

Parte A — Tipos de pago

Contabilidad → Tipos de Pago (/accounting/payment-types)

La inicialización (paso 1) ya creó cuatro:

Puedes añadir los tuyos (p. ej. Tarjeta Visa, Depósito BHD). El código es único por empresa. Un tipo se puede desactivar, lo que lo saca de los selectores sin borrar el historial.

Parte B — Condiciones de pago

Cuentas por Cobrar → Condición de Pago (/cxc/condiciones)

Esta es la que cambia el comportamiento del sistema:

Qué cambia según el tipo

Parte C — Crédito por cliente

En la ficha del cliente (Cuentas por Cobrar → Cliente) se define:

• Condición de pago predeterminada — la que se propone al facturarle.
• Límite de crédito — monto máximo pendiente permitido.
• Crédito bloqueado — impide facturarle a crédito.
• Bloqueo comercial total — impide facturarle, incluso de contado.

Recomendación mínima

Crea al menos:

1. CONTADO — tipo CONTADO, 0 días, marcada por defecto.
2. 30D — tipo CRÉDITO, 30 días.

Con eso ya puedes facturar en los dos escenarios.

Cómo verificar

Crea una factura de prueba: al elegir la condición CONTADO el sistema debe pedirte el cobro en la misma pantalla; al elegir 30D debe calcular la fecha de vencimiento a 30 días.

Siguiente

Paso 6 — Importa tus clientes.

Estado: Listo. Importación tipada con plantilla, validación fila a fila, reporte de errores y deduplicación. Una fila inválida no bloquea las demás.

Ruta

Cuentas por Cobrar → Cliente (/cxc/clientes)

Permisos

Paso 1. Descarga la plantilla

Descarga plantilla_clientes.csv. Trae el encabezado correcto y una fila de ejemplo:

code,name,rnc,email,phone,creditLimit,paymentTerms,currency
,Cliente Ejemplo SRL,131000001,[email protected],809-555-0100,50000,30,DOP

Paso 2. Completa el archivo

Columnas aceptadas

• Cualquier otra columna se ignora y se reporta al final como columna ignorada.
• Las columnas id, companyId y tenantId están prohibidas: si aparecen, el archivo

se rechaza completo. La empresa la determina la pantalla, nunca el archivo.

Límites

Si tienes más, divide el archivo en varias cargas.

Paso 3. Sube el archivo

El sistema procesa fila a fila y devuelve un resumen:

Las filas con error no se intentan; las válidas sí se crean. No hay carga a medias.

Motivos de error que verás

Consejos para que salga a la primera

1. Guarda el CSV en UTF-8. Si lo exportas desde Excel, elige CSV UTF-8, o las tildes

y las «ñ» llegarán rotas.

1. Limpia los RNC antes de subir: el sistema no valida el formato del RNC ni

consulta el padrón de la DGII. Un RNC mal escrito llega tal cual al reporte 607.

1. Revisa duplicados en tu archivo original: el sistema los detecta dentro del CSV y

contra la base, pero es más rápido corregirlos antes.

1. Empieza con 10 filas de prueba antes de subir las 3 000.

Alta manual

Si son pocos, créalos a mano en la pestaña Cliente. Los únicos campos obligatorios son Nombre y Documento.

Cómo verificar

Cuentas por Cobrar → Cliente → Buscar Cliente con filtros por nombre, código, documento, tienda, vendedor, estatus y tipo de cliente.

Siguiente

Paso 7 — Importa tus productos.

Estado: Operativo con una limitación importante. El alta de artículos es completa (individual y edición masiva de los ya creados), pero no existe importación por CSV de artículos. Lee la nota al final antes de planificar una migración grande.

Ruta

Inventario → Ítem (/inventory/items)

Antes de crear artículos: los catálogos base

Créalos primero o tendrás que volver a editar cada artículo:

Permisos

Ver costos es un permiso aparte. Un usuario sin inventory:view-cost ve el catálogo pero no los costos ni la valuación.

Crear un artículo

Sobre el método de costeo

Elígelo antes de que el artículo tenga movimientos: cambiarlo después altera la valoración del inventario existente.

Servicios

Un servicio (mano de obra, asesoría) también se crea como artículo, pero no lleva existencias: no descuenta stock ni genera costo de venta.

Edición masiva

Si necesitas cambiar el mismo campo en muchos artículos (por ejemplo, asignar una categoría), selecciónalos en la lista y usa la edición masiva: aplica el mismo cambio a todos los seleccionados en una sola operación.

Limitación real: no hay importación CSV de artículos

Qué hacer con un catálogo grande: cárgalo mediante la API (POST de artículos con una API Key, ver Integraciones y API), o solicita la carga inicial a soporte. No existe hoy una pantalla de importación masiva de artículos, y esta documentación no va a decir lo contrario.

Cómo verificar

Inventario → Panel de Inventario muestra el conteo de artículos, y Inventario → Ítem permite buscarlos por código, nombre y categoría.

Siguiente

Paso 8 — Configura inventario.

Estado: Listo. Almacenes, existencia inicial valorizada y costeo (promedio / FIFO / estándar) verificados contra la contabilidad.

Este es el paso que más se salta y el que más problemas causa después: si cargas la existencia sin costo, tu costo de venta sale en cero y el margen queda inflado.

Parte A — Almacenes

Inventario → Almacén (/inventory/warehouses)

Un almacén es donde vive físicamente el stock. Crea uno por cada lugar donde guardas mercancía: bodega principal, tienda, vehículo de reparto, mercancía en consignación.

Almacén ≠ Sucursal. El almacén controla existencias; la sucursal es una dimensión contable. Puedes tener varios almacenes en una misma sucursal.

Si necesitas más detalle dentro de un almacén (pasillo, estante), usa ubicaciones (/inventory/locations).

Parte B — Existencia inicial

Inventario → Revalorización de Costos (/inventory/valuation)

Cada carga inicial registra, para un artículo en un almacén:

Reglas que el sistema aplica

Al cargar sobre un artículo que ya tiene existencia, el sistema recalcula el promedio ponderado entre lo que había y lo que entra: no reemplaza el costo, lo promedia.

Parte C — Verifica la valuación

Inventario → Existencia en Almacén / Consulta Inventario (/inventory/reports)

Filtra por artículo, almacén y fecha. Debes ver cantidad, costo unitario y valor total.

Esta pantalla exige el permiso inventory:view-cost. Sin él verás cantidades pero no costos.

Parte D — Conteos y ajustes

Efecto contable

La existencia inicial y todo movimiento posterior impactan las cuentas configuradas en la empresa:

Se configuran en Seguridad → Configuración → Configurar Inventario y en la configuración contable de la empresa.

Cómo verificar antes de facturar

1. El artículo aparece en Existencia en Almacén con cantidad y costo distintos de cero.
2. Contabilidad → Balanza Comprobación muestra saldo en la cuenta Inventarios.

Si el paso 2 da cero pero sí tienes existencias, la cuenta de inventario no está configurada.

Siguiente

Paso 9 — Emite tu primera factura.

Estado: Listo. Cobro aplicado por antigüedad o manualmente, con control de concurrencia y su asiento contable.

Requisitos previos

Permisos

Ruta

Cuentas por Cobrar → Recibo (/cxc/recibos)

Paso 1. Datos del recibo

Si no eliges cuenta bancaria, se usa la cuenta de caja por defecto de la empresa. La contrapartida del asiento sale de la cuenta de tesorería elegida — no es un valor fijo.

Paso 2. Aplicar a facturas

Hay dos formas:

Si el monto recibido supera lo aplicado, el recibo queda abierto con saldo a favor del cliente, listo para aplicarse a facturas futuras.

Paso 3. Grabar

Validaciones del sistema

Qué queda registrado

Cómo verificar

1. Cuentas por Cobrar → Dashboard — el saldo por cobrar bajó.
2. Cuentas por Cobrar → Reporte CxC — la factura aparece saldada o con el nuevo saldo.
3. Contabilidad → Diario — el asiento del cobro, cuadrado.
4. Contabilidad → Balanza Comprobación — la cuenta de caja/banco subió.

Casos relacionados

¡Listo!

Ya cerraste el ciclo completo: empresa → catálogos → factura → cobro → contabilidad.

Revisa ahora el Checklist de puesta en marcha para confirmar que nada quedó a medias.

Estado: Listo. Acceso con correo y contraseña, verificación en dos pasos (TOTP), sesiones rotativas con detección de reutilización de token y cierre de sesión remoto.

Tu dirección de acceso

Cada empresa entra por su propia dirección, no por una página compartida:

https://<tu-empresa>.<dominio>

Esa dirección identifica tu empresa: la pantalla de acceso muestra tu logo y colores. Si entras por la dirección equivocada, tus credenciales no funcionarán, aunque sean correctas.

Guarda la dirección en favoritos. Si no la recuerdas, pídesela a quien administra el sistema en tu empresa.

Entrar

1. Abre la dirección de tu empresa.
2. Escribe tu correo (el mismo con el que te dieron de alta) y tu contraseña.
3. Pulsa Iniciar sesión.

Si tu empresa tiene activada la verificación en dos pasos, verás un segundo paso pidiendo el código de 6 dígitos.

Primera vez: invitación por correo

Si te invitaron, recibiste un enlace de la forma:

https://<tu-empresa>.<dominio>/accept-invite?t=...&token=...

Ábrelo y define tu contraseña. El enlace vence a los 7 días; pasado ese plazo pide una invitación nueva. Hasta que lo uses, tu cuenta está inactiva.

Verificación en dos pasos (MFA)

Es el control que evita que alguien entre solo con tu contraseña. Usa una app de autenticación (Google Authenticator, Microsoft Authenticator, 1Password, Authy…).

Activarla

1. Entra a tu perfil → Seguridad.
2. Elige Activar verificación en dos pasos. Aparece un código QR.
3. Escanéalo con tu app de autenticación.
4. Escribe el código de 6 dígitos que muestra la app para confirmar.
5. Guarda los códigos de respaldo que el sistema te entrega: son tu única forma de entrar

si pierdes el teléfono. Se muestran una sola vez.

Usarla

Al iniciar sesión, después de la contraseña se te pedirá el código de 6 dígitos.

Desactivarla

Desde el mismo lugar, confirmando con un código válido. No se puede desactivar sin demostrar que controlas el segundo factor.

Recomendación: actívala al menos en todas las cuentas con perfil Administrador.

Cerrar sesión

Ver dónde tienes sesión abierta

En tu perfil, la lista de sesiones activas muestra cuándo se abrió cada una, desde qué IP y cuándo vence. Puedes cerrar cualquiera de forma individual.

Úsalo si perdiste un equipo o crees que alguien más entró con tu cuenta.

Cuánto dura la sesión

La renovación es automática: no notarás nada mientras trabajes.

Si ves «sesión revocada por seguridad»

El mensaje completo es:

Refresh token ya usado — sesión revocada por seguridad, inicia sesión de nuevo

Significa que el sistema detectó que una credencial de sesión se intentó usar dos veces, la señal típica de un token robado. Ante la duda, el sistema cierra toda la cadena de esa sesión. Vuelve a iniciar sesión con normalidad; si se repite a menudo, avisa a quien administra el sistema.

Cambiar tu contraseña

Desde tu perfil. La nueva contraseña debe cumplir la política que definió tu empresa (longitud mínima, mayúsculas, números o caracteres especiales). Si no la cumple, el sistema la rechaza y te dice qué falta.

Si olvidaste tu contraseña, pide a quien administra el sistema que te la restablezca desde Seguridad → Usuarios.

Problemas al entrar

Estado: Listo

Objetivo

Que un usuario nuevo pueda ingresar al ERP, elegir su empresa y entender cómo está organizada la pantalla.

A quién va dirigido

Cualquier usuario final que use UtilARA ERP por primera vez.

Cuándo se usa

La primera vez que entras, o cuando cambias de empresa.

Requisitos previos

• Tener un usuario creado por el administrador de la empresa (ver ../administrativo/usuarios.md).
• La URL del sistema (en producción: bajo documentolisto.com).
• Un navegador moderno (Chrome/Edge/Firefox actualizado).

Paso a paso

1. Abre la URL del ERP. Verás la pantalla de Login.
2. Escribe tu correo y contraseña y presiona Ingresar.

• Si te invitaron por correo, primero aceptas la invitación (pantalla Aceptar invitación) y defines tu contraseña.

1. Al entrar, el sistema te ubica en tu empresa (tenant). Si tienes acceso a varias, hay un selector de empresa en la barra superior (CompanyBar).
2. La pantalla tiene 3 zonas:

• Barra superior: empresa activa, tu usuario, notificaciones.
• Menú lateral (sidebar) izquierdo: los módulos (Facturación, CxC, CxP, Compras, Inventario, Banco, Contabilidad, etc.). Se despliegan en sub-ítems.
• Área central: la pantalla del módulo que elegiste.

1. Cada ítem del menú es su propia página. Al entrar a un módulo, dentro verás sub-pestañas propias, típicamente "Buscar X" (lista/búsqueda) y "X" (crear/editar el registro).

Campos explicados (login)

Botones/acciones

• Ingresar: valida credenciales y abre la sesión.
• Selector de empresa (arriba): cambia el tenant activo sin cerrar sesión.

Validaciones importantes

• Solo ves los módulos y apps que tu empresa tiene instalados y para los que tienes permiso. Si no ves un módulo, puede ser permiso o app no instalada (ver ../soporte/faq.md).

Errores comunes

• "Credenciales inválidas": correo/contraseña incorrectos.
• "No veo ningún módulo": tu perfil no tiene permisos asignados → contacta al administrador.
• "Veo una versión vieja": el navegador cacheó el frontend (Service Worker). Prueba en Incógnito. Ver ../soporte/errores-comunes.md.

Resultado esperado

Estás dentro del ERP, en tu empresa, viendo el menú de módulos permitidos.

Integraciones relacionadas

• Seguridad / RBAC (qué ves depende de tus permisos).
• Apps instalables (qué módulos existen depende de lo instalado).

Permisos necesarios

Ninguno para entrar; los permisos determinan qué módulos ves después.

Notas técnicas

• Frontend React/Vite. Layout del cliente: ClientLayout. El menú se pinta data-driven desde el manifest/override del tenant (ver ../tecnico/menu-y-overrides.md).
• Autenticación por JWT. Ver ../tecnico/autenticacion.md.

Estado: Operativo. Descrito sobre las pantallas reales. Donde hay una limitación (por ejemplo la búsqueda global), se dice.

El patrón que se repite en todas partes

Casi todos los módulos usan la misma estructura de dos pestañas:

Ejemplo: Facturación → Factura tiene Buscar Factura y Factura. Cuentas por Cobrar → Cliente tiene Buscar Cliente y Cliente.

Para editar un registro: búscalo en la pestaña de búsqueda, selecciónalo y se abre en el formulario.

El selector de empresa

Casi todo se registra dentro de una empresa. Si un selector de empresa aparece vacío, no podrás guardar. Si un cliente, artículo o factura "no aparece", lo primero a revisar es que estés en la empresa correcta.

Buscar

Buscador de cada pantalla (el que debes usar)

Cada pantalla de búsqueda trae los filtros que tienen sentido para ese documento. Por ejemplo, Buscar Cliente filtra por ID, Nombre, Código, Documento, Tienda, Comprobante Fiscal, Vendedor, Estatus y Tipo de Cliente.

Consejos:

• Los filtros de texto buscan coincidencias parciales: escribir mueble encuentra

Mueblería Santo Domingo.

• Los filtros se combinan: rango de fechas + estado + cliente.
• Si no aparece nada, quita filtros de arriba hacia abajo hasta encontrar cuál sobra.

Búsqueda global (Ctrl+K) — con una limitación importante

El atajo Ctrl+K (o ⌘+K en Mac) abre un buscador general en la barra superior.

Limitación real: hoy la búsqueda global consulta únicamente los registros de entidades personalizadas, no los documentos del núcleo del ERP. No encontrará facturas, clientes, artículos ni proveedores. Para esos, usa el buscador de la pantalla correspondiente.

Escribe al menos 2 caracteres; devuelve hasta 20 resultados, con las coincidencias por nombre primero.

Editar

1. Encuentra el registro en la pestaña de búsqueda y ábrelo.
2. Modifica lo que necesites.
3. Pulsa Grabar / Guardar.

Lo que ya está contabilizado no se edita. Un documento posteado se corrige con una anulación o una nota de crédito / débito, nunca reescribiendo el original: es lo que mantiene la contabilidad auditable.

Anular

Anular no borra: revierte. El documento queda visible con estado Anulado y el sistema genera el asiento espejo que deja los saldos en cero. Requiere permiso de eliminación del módulo (cxc:delete, cxp:delete, …).

En comprobantes fiscales, anular no devuelve el NCF: el número pasa al reporte 608 y no se reutiliza.

Imprimir y descargar PDF

Las facturas y otros comprobantes tienen acciones de documento:

El formato del comprobante (A4, Carta o rollo térmico de 80 mm) se configura por empresa en Seguridad → Configuración → Configurar Compañía.

Exportar

Casi todos los listados y reportes se exportan. Según la pantalla verás uno o varios formatos:

Los estados financieros (Balanza, Estado de Resultados, Balance General, Flujo de Efectivo, Mayor General, Consolidación) ofrecen los tres. Otros listados exportan solo CSV.

Sobre "exportar a Excel": el sistema no genera archivos .xlsx nativos. La opción EXCEL produce un archivo que Excel abre sin problema; la opción CSV es la más segura para reimportar en otro sistema. Abre siempre el CSV como UTF-8 para que las tildes se vean bien.

Exportar puede requerir un permiso específico (accounting:export, profit_loss:export, etc.). Si el botón no aparece, es un tema de permisos.

Atajos y detalles útiles

Cuando algo "no aparece"

Recórrelo en este orden:

1. ¿Estás en la empresa correcta?
2. ¿Hay un filtro activo que lo excluye (estado, fechas, almacén)?
3. ¿El registro está inactivo? Los catálogos inactivos no salen en los selectores.
4. ¿Tienes permiso para verlo? Sin permiso de lectura, la pantalla se ve vacía en vez de

dar error.

1. ¿El período está cerrado? Algunos listados se limitan al período abierto.

Estado: Casi listo. Existen varias pantallas de inicio (DashboardPage, HomeDashboardPage, DeskHomePage). El grado de datos reales vs. widgets estáticos por tenant no se verificó end-to-end (No verificado).

Objetivo

Dar una vista rápida del estado del negocio al entrar (ventas, cobros, saldos, alertas).

A quién va dirigido

Todos, especialmente gerencia.

Cuándo se usa

Es la pantalla de aterrizaje tras el login.

Paso a paso

1. Al ingresar, llegas al panel de inicio.
2. Revisa los indicadores y accesos rápidos.
3. Navega a un módulo desde el menú lateral o desde los accesos del panel.

Validaciones importantes

• Los widgets dependen de los módulos/apps instalados y de tus permisos.

Errores comunes

• "Widgets vacíos": aún no hay datos, o el widget consume un módulo no instalado.

Resultado esperado

Vista general del negocio y navegación rápida.

Integraciones relacionadas

• Consume datos de Facturación, CxC, CxP, Inventario, Banco.

Permisos necesarios

Los de los módulos que alimentan cada widget.

Notas técnicas

• Frontend: DashboardPage.tsx, HomeDashboardPage.tsx, DeskHomePage.tsx. Backend tenant-runtime/dashboard.
• No verificado: conexión de cada widget a datos reales por tenant. Verificar antes de destacar el dashboard en una demo.

Estado: Listo (facturación, cotización, orden de venta, POS conectados a backend real)

Objetivo

Emitir facturas de venta a clientes, con o sin NCF, descontar inventario y generar la contabilidad y la cuenta por cobrar automáticamente.

A quién va dirigido

Facturadores, cajeros (POS), vendedores.

Cuándo se usa

Cada vez que se vende un producto o servicio a un cliente.

Requisitos previos

• Al menos un cliente (ver cuentas-por-cobrar.md o ../guias-rapidas/crear-cliente.md).
• Al menos un ítem (producto/servicio) (ver inventario.md).
• Si facturas fiscal en RD: una serie NCF configurada (ver ncf-dgii.md).
• Impuestos (ITBIS) configurados.

Pantallas (menú Facturación)

Paso a paso (factura de venta)

1. Menú Facturación → Factura → Factura (nuevo).
2. Selecciona el cliente (buscador/lookup).
3. Elige el tipo de comprobante / serie NCF si aplica.
4. Agrega líneas: ítem, cantidad, precio, descuento. El ITBIS se calcula según la configuración del ítem/impuesto.
5. Revisa subtotal, impuesto y total.
6. Guardar (borrador) y luego Emitir/Postear para que impacte contabilidad, inventario y CxC.
7. Imprimir o generar el comprobante.

Campos explicados

Botones/acciones

• Guardar: deja la factura en borrador (no contabiliza).
• Emitir/Postear: confirma; genera asiento, movimiento de inventario y CxC. Consume el NCF.
• Imprimir / Imprimir en lote: genera el documento.
• Anular: revierte (si el sistema lo permite según estado/período).

Validaciones importantes

• No se puede emitir sin cliente ni sin líneas.
• Si el ítem controla stock, valida disponibilidad.
• El NCF se consume de la serie; no se reutiliza (numeración sin huecos).
• No se puede postear en un período contable cerrado.

Errores comunes

• "No hay NCF disponible": la serie se agotó o no está configurada → ver ncf-dgii.md.
• "Stock insuficiente": falta inventario del ítem.
• "Período cerrado": la fecha cae en un período cerrado.
• "Sin permiso": falta permiso de facturación.

Resultado esperado

Factura emitida con NCF (si aplica), inventario descontado, cuenta por cobrar creada y asiento contable generado. Ver el detalle contable en ../contable/facturacion-y-cxc.md.

Integraciones relacionadas

• Inventario: descuenta stock y registra costo de venta.
• CxC: crea la cuenta por cobrar del cliente.
• Contabilidad: asiento invoice.created.
• NCF/DGII: consume comprobante, alimenta el 607.

Permisos necesarios

Facturación/ventas (recurso sales/billing según pantalla) y cxc para el impacto en cobros. La app base utilara-erp debe estar instalada.

Notas técnicas

• Backend: backend/src/tenant-runtime/{sales,quotes,pricing,ncf,cxc}; POS en .../pos.
• Asiento automático regla invoice.created: Dr Cuentas por Cobrar / Cr Ingreso / Cr ITBIS por pagar (cuentas 110201 / 410102 / 210201). Ver ../contable/facturacion-y-cxc.md.
• Skill de referencia: utilara-billing-production.

Estado: Listo (clientes, recibos, notas de crédito/débito, anticipos, reportes conectados a backend real)

Objetivo

Gestionar lo que los clientes te deben: registrar clientes, cobrar facturas, aplicar notas de crédito/débito y anticipos, y ver el estado de cuenta y la antigüedad de saldos (aging).

A quién va dirigido

Cobradores, cajeros, contabilidad de cuentas por cobrar.

Cuándo se usa

Cuando registras un cliente, cobras una factura, das una nota de crédito o consultas cuánto te deben.

Requisitos previos

• Facturas emitidas (ver facturacion.md) para poder cobrarlas.
• Una cuenta de caja/banco para recibir el cobro (ver banco.md).

Pantallas (menú Cuentas por Cobrar)

Nota: algunas pantallas de catálogo (Tipo de Cliente, Condición de Pago) pueden ser catálogos maestros básicos. Ver estado en ../comercial/limitaciones-actuales.md.

Paso a paso (cobrar una factura — Recibo)

1. Menú Cuentas por Cobrar → Recibo (nuevo).
2. Selecciona el cliente.
3. El sistema muestra sus facturas abiertas. Marca cuáles cobras y por cuánto (total o parcial).
4. Indica la cuenta de caja/banco donde entra el dinero y el medio de pago.
5. Si el cliente te aplicó retención o das descuento por pronto pago, regístralo.
6. Guardar/Aplicar. Se genera el asiento y baja el saldo del cliente.

Campos explicados

Botones/acciones

• Aplicar recibo: confirma el cobro y postea.
• Nota de crédito: reduce lo que el cliente debe (por descuento o devolución).
• Anticipo: registra dinero recibido por adelantado, aplicable luego a facturas.
• Desaplicar: corrige a qué factura se imputó un recibo, una nota o un anticipo sin anularlo.

Desaplicar: cuando el cobro fue a la factura equivocada

El cobro está bien y el dinero entró bien, pero se imputó a la factura que no era.

Desaplicar no anula el cobro. El recibo sigue existiendo con su número y su asiento; la factura vuelve a figurar como pendiente y el recibo recupera saldo disponible para aplicarlo donde corresponde. Anular el recibo, en cambio, reversa el asiento y el movimiento de caja — y el dinero entró de verdad, así que no es lo que quieres.

Cómo se hace: abre el Recibo, el Anticipo o la Nota de Crédito y pulsa Desaplicar. Verás el historial de a qué documentos se aplicó; puedes deshacer una línea o todas, y escribir el motivo, que queda guardado junto a la aplicación.

Qué pasa con la contabilidad:

Nada se borra. La aplicación deshecha queda guardada y marcada como reversada, para que el historial del documento sea completo.

Validaciones importantes

• No se puede cobrar más de lo que la factura debe.
• Dos aplicaciones simultáneas del mismo anticipo no deben sobre-aplicar (control de concurrencia).
• No se postea en período cerrado.

Errores comunes

• "Monto excede el saldo": intentas cobrar más de lo debido.
• "Sin cuenta de caja/banco": falta indicar dónde entra el dinero.
• "Anticipo ya aplicado": el anticipo se usó en otra parte.

Resultado esperado

Saldo del cliente reducido, dinero registrado en caja/banco y asiento contable generado. Detalle en ../contable/facturacion-y-cxc.md.

Integraciones relacionadas

• Facturación: origina los documentos a cobrar.
• Banco/Caja: recibe el dinero.
• Contabilidad: asiento payment.received (Dr Caja / Cr CxC, cuentas 110101 / 110201).

Permisos necesarios

cxc:read, cxc:create, cxc:update, cxc:delete según la acción. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/cxc. Controller t/:slug/cxc.
• Skill: utilara-cxc-production. Contrato de paridad con 22 pantallas legacy.
• Auditoría 2026-08-18: suite de backend en verde (14 archivos de test, 294 casos). El asiento customer_advance.applied (traslado del pasivo "Anticipos de Clientes" a CxC al aplicar un anticipo) tiene test de regresión y postea correctamente — el bug histórico de GL en Anticipo ya está corregido.
• Límite conocido: Reporte CxC (ReportesCxC.tsx) trae hasta 500 registros por consulta; el backend ya soporta page/limit/totalPages pero la pantalla todavía no tiene los controles de paginación conectados. No afecta la exactitud del reporte, solo el tope de filas visibles a la vez.

Estado: Listo (solicitud → cotización → orden de compra → recepción → factura → matching conectados a backend real)

Objetivo

Gestionar el ciclo de abastecimiento: pedir materiales, cotizar con proveedores, emitir órdenes de compra, recibir mercancía y casar la factura del proveedor (invoice matching).

A quién va dirigido

Compradores, almacén (recepción), cuentas por pagar.

Cuándo se usa

Cuando la empresa necesita comprar productos o servicios a proveedores.

Requisitos previos

• Proveedores registrados (compartidos con CxP).
• Ítems en inventario.
• Almacenes definidos para recibir.

Pantallas (menú Compras)

Paso a paso (compra estándar)

1. Solicitud de Material (opcional): quien necesita algo lo solicita.
2. Solicitud de Cotización a uno o varios proveedores; registra sus cotizaciones.
3. Orden de Compra: confirma qué, a quién, cuánto y a qué precio.
4. Recepción: al llegar la mercancía, se recibe contra la OC (total o parcial) → entra al inventario.
5. Factura de Compra + Matching: al llegar la factura del proveedor, se casa (2-way/3-way) contra la OC y la recepción; se crea la CxP.

Campos explicados

Botones/acciones

• Crear OC / Aprobar OC.
• Recibir (recepción): afecta inventario.
• Casar factura (matching): genera la CxP y su asiento.

Validaciones importantes

• La recepción no debe exceder lo ordenado (salvo tolerancia configurada).
• El matching detecta variancias de cantidad/precio.
• Recepción y factura son transaccionales (no dejan estados a medias).

Errores comunes

• "OC ya cerrada": intentas recibir contra una OC completada.
• "Variancia fuera de tolerancia": la factura no cuadra con la OC/recepción.

Resultado esperado

Mercancía recibida en inventario y factura del proveedor registrada como CxP, con contabilidad generada.

Integraciones relacionadas

• Inventario: la recepción aumenta stock y costo.
• CxP: el matching crea la cuenta por pagar.
• Contabilidad: entrada de inventario (inventory.movement) y factura de proveedor (vendor_bill.created).
• Activos Fijos: una factura de proveedor puede capitalizar un activo (ver activos-fijos.md).

Permisos necesarios

purchasing:read/create/update/delete. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/purchasing (+ solape con cxp y ncf). Controller t/:slug/purchasing.
• Skill: utilara-purchasing-production. Flujo E2E en ../flujos/compra-completa.md.

Estado: Listo (suplidores, facturas de compra, pagos, notas, retenciones conectados a backend real)

Objetivo

Gestionar lo que tú debes a tus proveedores (suplidores): registrar sus facturas, aplicar retenciones ITBIS/ISR, pagarles, y ver antigüedad de saldos y estado de cuenta.

A quién va dirigido

Cuentas por pagar, tesorería, contabilidad.

Cuándo se usa

Cuando recibes la factura de un proveedor, le pagas, o consultas cuánto le debes.

Requisitos previos

• Un suplidor registrado.
• Idealmente una orden de compra / recepción (ver compras.md) si sigues el flujo completo de compras.
• Cuenta de banco/caja para pagar.

Pantallas (menú Cuentas por Pagar)

Paso a paso (registrar y pagar factura de proveedor)

1. Registrar factura: menú CxP → Factura Suplidor (nuevo). Selecciona el suplidor, escribe el NCF del proveedor, las líneas (gasto/compra), el ITBIS y las retenciones (ITBIS/ISR) si aplican. Guarda → se crea la CxP y su asiento.
2. Pagar: menú CxP → Pago (o Pago de Contado). Selecciona el suplidor, marca las facturas a pagar, indica la cuenta de banco/caja y el medio de pago. Aplica → baja el saldo y postea.

Campos explicados

Botones/acciones

• Guardar factura: crea la CxP y su asiento.
• Aplicar pago: paga una o varias facturas y postea.
• Nota de crédito/débito: ajusta el saldo del proveedor.
• Desaplicar: corrige a qué factura se imputó un pago, una nota o un anticipo sin anularlo.

Desaplicar: cuando el pago fue a la factura equivocada

Es el error más común del día a día: el pago está bien, el dinero salió bien, pero se imputó a la factura que no era.

Desaplicar no anula nada. El pago sigue existiendo con su número, su fecha y su asiento; la factura vuelve a figurar como debida y el pago recupera saldo disponible para aplicarlo donde corresponde. Anular el pago, en cambio, reversa el asiento y el movimiento del banco — y el dinero salió de verdad, así que no es lo que quieres.

Cómo se hace: abre el documento (Pago de Contado, Anticipo o Nota) y pulsa Desaplicar. Verás el historial de a qué facturas se aplicó; puedes deshacer una línea o todas, y escribir el motivo. El motivo queda guardado junto a la aplicación, así que dentro de un año se puede saber quién la corrigió y por qué.

Qué pasa con la contabilidad, según el documento:

Nada se borra. La aplicación deshecha queda guardada y marcada como reversada, para que el historial del documento sea completo.

Validaciones importantes

• No se puede pagar más del saldo pendiente.
• Concurrencia: dos pagos sobre la misma factura no deben sobre-aplicar.
• No se postea en período cerrado.

Errores comunes

• "NCF duplicado": el NCF del proveedor ya se registró.
• "Saldo insuficiente en la factura": intentas pagar de más.
• "Sin cuenta de banco": falta indicar la fuente del pago.

Resultado esperado

Deuda con el proveedor registrada y luego reducida al pagar; asientos contables generados; NCF del proveedor listo para el 606.

Integraciones relacionadas

• Compras: origina las facturas (invoice matching).
• Banco/Caja: sale el dinero.
• Contabilidad: vendor_bill.created (Dr Gasto + Dr ITBIS adelantado / Cr Retenciones / Cr CxP) y payment.sent (Dr CxP / Cr Caja). Cuentas 520105 / 110401 / 210203-210204 / 210101 / 110101.
• NCF/DGII: alimenta el 606.

Permisos necesarios

cxp:read, cxp:create, cxp:update, cxp:delete. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/cxp. Controller t/:slug/cxp.
• Skill: utilara-cxp-production. Ver detalle contable en ../contable/compras-y-cxp.md.

Estado: Listo (ítems, almacenes, movimientos, costeo conectados a backend real). Nota: la pantalla real conectada es InventoryPage.tsx; existió una maqueta antigua bajo pages/inventario/ — usar las rutas /inventory/* del menú.

Objetivo

Controlar los productos: qué hay, dónde, cuánto cuesta, y registrar todas sus entradas y salidas.

A quién va dirigido

Almacenistas, compras, ventas, contabilidad de costos.

Cuándo se usa

Al crear productos, recibir/despachar mercancía, trasladar entre almacenes, ajustar existencias o consultar stock.

Requisitos previos

• Al menos un almacén (ver ../administrativo/almacenes.md).
• Categorías/unidades básicas del ítem.

Pantallas (menú Inventario)

Paso a paso (crear un ítem)

1. Menú Inventario → Ítem (nuevo).
2. Escribe código, nombre, categoría, unidad.
3. Define si controla stock, su método de costeo (FIFO / promedio / estándar), impuestos y precio.
4. Guarda.

Paso a paso (movimiento de inventario)

1. Menú Inventario → Movimiento de Inventario.
2. Elige el tipo (entrada, salida, traslado…).
3. Selecciona almacén(es), ítems y cantidades.
4. Confirma → actualiza existencias y, si aplica, postea el asiento de inventario.

Cuadrar el inventario con la contabilidad

Tu inventario vive en dos sitios que deben decir lo mismo:

• El auxiliar — lo que hay en el almacén, artículo por artículo, con su valor.
• La cuenta contable de Inventario — lo que dice tu balance general.

Si no coinciden, tu balance está mal aunque cada asiento por separado esté cuadrado.

En Inventario → Reportes → Conciliación se comparan las dos cifras y, cuando hay diferencia, se listan los asientos que tocaron la cuenta de Inventario sin venir de un movimiento de inventario — que es la causa habitual.

También se revisa una segunda cosa: que la existencia de cada artículo coincida con la suma de su kardex. El sistema escribe ambas a la vez, así que una diferencia solo puede venir de una manipulación hecha por fuera de la aplicación.

Regularizar una diferencia

Cuando la diferencia es real y su origen ya no se puede reconstruir, se regulariza. La forma correcta no es retocar movimientos viejos ni cambiar fechas: es reconocer la diferencia hoy, dejando constancia.

Al regularizar se te exige un motivo, y el sistema genera dos cosas:

1. Un movimiento de ajuste (AJU-…) que repone el rastro del kardex. **No cambia tu

existencia**: el almacén tiene lo que tiene; lo que se repara es el registro de cómo llegó a esa cantidad.

1. Un asiento contable fechado hoy, contra la cuenta Ajuste de Inventario — nunca

contra Costo de Ventas, porque una diferencia de conciliación no es un costo de vender.

Ambos quedan visibles, con tu nombre y tu motivo, y se pueden anular como cualquier otro documento. Si vuelves a regularizar cuando ya cuadra, no hace nada: no duplica.

Antes de regularizar, vale la pena hacer un conteo físico si la diferencia es grande. Regularizar cierra el hueco contable; contar confirma que la existencia que quedará como buena es la real.

Campos explicados

Botones/acciones

• Guardar ítem.
• Postear movimiento: afecta existencias (y GL si corresponde).
• Revalorizar: ajusta el costo de existencias.
• Conteo cíclico: ajusta stock a lo contado físicamente.

Validaciones importantes

• El stock no debe quedar negativo (salvo configuración).
• Existencia y libro de inventario (Kardex/Stock Ledger) siempre coinciden.
• Los movimientos son transaccionales.

Errores comunes

• "Stock insuficiente": no hay existencia para la salida.
• "Ítem sin costo": falta costo para valorar.

Resultado esperado

Existencias actualizadas, costo recalculado y, cuando corresponde, asiento de inventario/costo de venta.

Integraciones relacionadas

• Compras: recepción aumenta stock.
• Facturación: venta descuenta stock y genera costo de venta (COGS).
• Contabilidad: regla inventory.movement (entrada: Dr Inventario / Cr contrapartida; salida: Dr COGS / Cr Inventario; cuentas 110301 / 510101).

Permisos necesarios

inventory:read/create/update/delete. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/inventory. Controller t/:slug/inventory. Frontend real: InventoryPage.tsx.
• Skill: utilara-inventory-production. Detalle contable en ../contable/inventario-y-costo.md.

Estado: Completo. Las cuentas de banco/caja y sus movimientos usan el ledger real (BankAccount/BankTransaction). La conciliación bancaria es completa desde el 2026-07-22: captura el saldo del extracto, permite marcar partidas a mano o importar el extracto del banco con emparejamiento automático, y no deja cerrar una conciliación que no cuadre. Las cuentas contables por moneda y la impresión de cheques con formato configurable quedaron cerradas el 2026-07-22.

Objetivo

Administrar las cuentas bancarias y de caja de la empresa: registrar cheques, depósitos, transferencias, cargos bancarios y conciliar contra el estado del banco.

A quién va dirigido

Tesorería, contabilidad, finanzas.

Cuándo se usa

Cuando se mueve dinero por banco/caja fuera de una factura de venta/compra directa (transferencias, cheques, cargos, depósitos, conciliación).

Requisitos previos

• Cuentas de banco/caja creadas (menú Banco → Banco → Cuenta Banco).
• Monedas configuradas.

Pantallas (menú Banco) — menú de 3 niveles

Paso a paso (transferencia entre cuentas)

1. Menú Banco → Transferencia Bancaria → Transferencia.
2. Elige cuenta origen y cuenta destino.
3. Escribe monto y fecha.
4. Confirma → mueve el saldo y postea el asiento.

Paso a paso (conciliación bancaria)

Conciliar es comprobar que lo que tú registraste coincide con lo que el banco dice.

1. Menú Banco → Conciliación → Conciliar.
2. Elige la cuenta y escribe el saldo según el extracto del banco — el número que

aparece en el estado de cuenta que te envía el banco. Es obligatorio: es contra lo que se compara todo.

1. Marca las partidas que el banco ya refleja. Dos formas:

• A mano: la lista de la izquierda son las que el banco todavía no muestra;

márcalas una a una a medida que las encuentres en tu estado de cuenta.

• Importando el extracto: sube el archivo CSV que descargas del banco

(fecha,descripción,referencia,monto, con el monto negativo si es una salida). El sistema empareja solo las que coinciden en monto y fecha.

1. Mira la diferencia arriba a la derecha. Cuando llegue a cero, el botón

Cerrar Conciliación se habilita.

Cómo leer la pantalla

La franja de arriba es la cuenta que tienes que cuadrar:

Saldo según el banco + depósitos en tránsito − pendientes de cobro = saldo en libros

• Depósitos en tránsito: dinero que tú ya registraste como entrado pero que el banco

todavía no acredita.

• Pendientes de cobro: cheques que giraste o pagos que hiciste y que el banco aún no

ha descontado.

• Diferencia: lo que falta por explicar. Si no es cero, algo no está cuadrado.

Si importaste el extracto, abajo verás las líneas del banco. Las que queden sin pareja son cosas que el banco cobró y tú no has registrado — casi siempre comisiones o intereses. Regístralas como Cargo Bancario o Crédito Bancario y vuelve a conciliar.

Reglas que te va a aplicar el sistema

• No se puede cerrar una conciliación que no cuadra. Si lo intentas, te dice cuánto

falta y por qué. Cerrar es afirmar que libros y banco coinciden.

• Una sola conciliación abierta por cuenta. Dos repartirían las partidas entre dos

documentos y ninguno cuadraría.

• Solo entran las partidas hasta la fecha del extracto. Un movimiento posterior no es

una partida en tránsito, es del mes siguiente.

• Lo cerrado no se toca. Si necesitas corregir algo, usa Reabrir — las marcas se

conservan.

• Desmarcar una partida nunca borra nada: vuelve a la columna de pendientes.

Cuentas por moneda

Si facturas en dólares además de en pesos, no querrás que ambos saldos caigan en la misma cuenta contable: el balance por moneda sería imposible de presentar.

En Banco → Moneda → Cuentas por Moneda eliges, para cada moneda, qué cuenta usa cada concepto: Cuentas por Cobrar y por Pagar, Anticipos, Caja, Notas de Crédito, y las de Ganancia y Pérdida por Diferencia Cambiaria.

• Lo que dejes en blanco usa la cuenta general de la empresa, igual que hasta ahora.

No configurar nada no rompe nada.

• Las cuentas de Prima reciben el ajuste por diferencia cambiaria. Si las configuras,

la revaluación mueve la prima y deja intacta la cuenta de control — así ves el ajuste por separado del saldo real del cliente o del proveedor. Si las dejas vacías, el ajuste va contra la propia cuenta de control.

• Solo puedes elegir cuentas de movimiento: una cuenta de agrupación no admite asientos.

Imprimir cheques

En Banco → Cheque → Imprimir Cheques en lote seleccionas los cheques y los mandas a imprimir. Lo que sale por la impresora son solo los datos, colocados para caer en su sitio sobre el papel preimpreso del banco.

• El tamaño y los ajustes vertical y horizontal salen de la cuenta bancaria

(Banco → Cuenta Banco). Cada impresora alimenta el papel con un desvío distinto: se corrige una vez por cuenta, imprimiendo una prueba y moviendo los milímetros que hagan falta.

• El monto en letras lo escribe el sistema. No es un adorno: si no coincide con el

número, legalmente manda la cantidad en letras.

• Todos los cheques del lote deben ser de una misma cuenta, porque cada una tiene su

propio papel y sus propios ajustes.

• Al imprimir quedan marcados como impresos y dejan de aparecer en el listado.

Campos explicados

Validaciones importantes

• Toda transferencia/cheque/depósito genera su contrapartida en el GL (fail-closed).
• No se crea saldo bancario paralelo: es el mismo ledger que usan CxC/CxP/Caja Chica.

Errores comunes

• "Saldo insuficiente": la cuenta origen no tiene fondos.
• "Conciliación no cuadra": faltan partidas en tránsito por identificar.

Resultado esperado

Movimientos de banco/caja registrados con su asiento, y conciliación con el saldo del banco.

Integraciones relacionadas

• CxC/CxP/Caja Chica: todos los cobros/pagos aterrizan aquí.
• Contabilidad: cada movimiento postea al GL.

Permisos necesarios

banking:read/create/update/delete. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/banking (reutiliza modelos de Tesorería BankAccount/BankTransaction). Controller t/:slug/banking.
• Skills: utilara-banking-production, utilara-treasury-production.
• Multi-moneda: cada moneda puede tener sus propias cuentas contables (Moneda → Cuentas por Moneda). Lo que se deje en blanco usa la cuenta general de la empresa.
• Cheques: la impresión usa el formato y los ajustes configurados en la cuenta, y escribe el monto en letras automáticamente. Ver ../comercial/limitaciones-actuales.md.

Estado: Listo (fondo, desembolso, reposición con GL + Tesorería; migración aplicada a tenants).

Objetivo

Manejar un fondo de efectivo pequeño para gastos menores: crear el fondo, registrar desembolsos y reponerlo cuando baja.

A quién va dirigido

Encargado de caja chica, contabilidad.

Cuándo se usa

Para gastos menores en efectivo que no pasan por banco directamente (transporte, papelería, etc.).

Requisitos previos

• Una cuenta de banco de la que sale el dinero para fondear/reponer.
• Cuentas de gasto para clasificar los desembolsos.

Pantallas (menú Caja Chica)

Paso a paso

1. Crear fondo: menú Caja Chica → Caja Chica (nuevo). Define el monto del fondo y la cuenta de banco de la que sale. Al crear/fondear, se transfiere el dinero (asiento vía Tesorería).
2. Desembolso: menú Desembolso. Registra cada gasto: cuenta de gasto, monto, beneficiario, comprobante. El fondo disponible baja.
3. Reposición: menú Reposición. Cuando el fondo está bajo, se repone por el total de los desembolsos, devolviéndolo a su monto original (sale dinero del banco).

Campos explicados

Botones/acciones

• Crear fondo (pay-check desde banco).
• Registrar desembolso (reduce disponible; postea gasto fluctuante).
• Reponer (devuelve el fondo al tope; sale dinero del banco).

Validaciones importantes

• No se desembolsa más que el disponible del fondo.
• Concurrencia controlada (CAS) para no duplicar desembolsos.
• No crea saldo bancario paralelo: usa BankAccount/BankTransaction.

Errores comunes

• "Fondo insuficiente": el desembolso supera lo disponible.
• "Módulo no responde": revisar guard (no debe usar CombinedAuthGuard propio) — nota técnica.

Resultado esperado

Fondo creado, gastos registrados y fondo repuesto, todo con su contabilidad.

Integraciones relacionadas

• Banco/Tesorería: fondear y reponer mueven dinero del banco.
• Contabilidad: gasto fluctuante en el desembolso; ver ../contable/caja-chica.md.

Permisos necesarios

Recurso petty-cash (acciones propias del módulo). App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/petty-cash. Controller t/:slug/petty-cash/:companyId.
• Skill: utilara-petty-cash-production. GOTCHA: permisos en doble copia .ts/.mjs; no usar CombinedAuthGuard dentro del módulo.

Estado: Listo (activos, depreciación, retiro, revalorización con GL balanceado; migración aplicada a tenants).

Objetivo

Registrar los bienes de larga duración (equipos, mobiliario, vehículos), depreciarlos periódicamente, revalorizarlos y darlos de baja cuando se venden o desechan.

A quién va dirigido

Contabilidad de activos, administración.

Cuándo se usa

Al comprar un activo capitalizable, al correr la depreciación mensual, o al retirar/vender un activo.

Requisitos previos

• Tipo de Activo Fijo y Tipo de Depreciación configurados.
• Cuentas contables de activo, depreciación acumulada y gasto.

Pantallas (menú Activos Fijos)

Paso a paso

1. Crear activo: menú Activos Fijos → Activo Fijo (nuevo). Registra descripción, costo, fecha de adquisición, vida útil, valor residual y método de depreciación. (Puede capitalizarse desde una Factura de Suplidor.)
2. Depreciar: menú Depreciación. Selecciona el período y ejecuta → genera el asiento de gasto por depreciación.
3. Revalorizar (opcional): ajusta el valor del activo al alza/baja.
4. Retirar/dar de baja: menú Retiro. Registra venta o desecho → calcula ganancia/pérdida y genera el asiento.

Campos explicados

Botones/acciones

• Crear/Capitalizar activo.
• Ejecutar depreciación (postea gasto).
• Revalorizar / Retirar (postean sus asientos).

Validaciones importantes

• No se deprecia dos veces el mismo período (control de concurrencia).
• Los asientos siempre cuadran (Σdébito=Σcrédito).
• No se postea en período cerrado.

Errores comunes

• "Ya depreciado en este período": doble depreciación evitada.
• "Activo ya retirado": intentas operar un activo dado de baja.

Resultado esperado

Activo registrado y su valor en libros actualizado por depreciación/revalorización; al retirarlo, ganancia/pérdida reconocida.

Integraciones relacionadas

• Compras/CxP: una factura de proveedor puede capitalizar el activo.
• Contabilidad: asientos de depreciación, revalorización y retiro. Ver ../contable/activos-fijos.md.

Permisos necesarios

fixed-assets:read/create/update/delete/capitalize/depreciate/dispose. App utilara-erp.

Notas técnicas

• Backend: backend/src/tenant-runtime/fixed-assets. Controller t/:slug/fixed-assets + sub-controllers (depreciation-type, asset-revaluation, asset-disposal, inflation-rate, fixed-asset-type). GOTCHA: registrar sub-controllers antes del base.
• Skill: utilara-fixed-assets-production.

Estado: Listo. Turnos con arqueo, venta de contado y a crédito, anulación, devolución, reimpresión y reportes, todo con permisos que se aplican de verdad.

Para quién

Cajeros y encargados de tienda. El POS es la pantalla de mostrador: rápida, con teclado, para cobrar de cara al cliente.

Rutas

Terminal POS → Punto de Venta (/pos → /facturacion/pos)
Terminal POS → Terminal (/terminal-pos/terminal)
Terminal POS → Terminal de Impresión (/terminal-pos/impresion)
Facturación → Tiendas (/facturacion/tienda/buscar)

Antes de vender

Permisos — cada acción tiene el suyo

Esto es lo que permite dar a un cajero solo lo que necesita:

Recomendación: un cajero típico necesita read, open-session, sell, close-session y reprint. No le des void-sale, override-price ni approve-difference: esos son del encargado.

Abrir el turno

1. Entra al Terminal POS y elige tu tienda / caja.
2. Pulsa Abrir turno.
3. Declara el fondo inicial (el efectivo con el que empiezas).

Sin turno abierto no se puede vender.

Vender

1. Agrega artículos: por código de barras, por búsqueda o desde el catálogo en pantalla.
2. Ajusta cantidades.
3. Elige el cliente si aplica (para consumidor final no es obligatorio; para crédito, sí).
4. Cobra: elige el método de pago e indica el efectivo recibido — el sistema calcula el

cambio.

1. El comprobante se imprime.

Venta a crédito

Requiere pos:sell-on-credit y un cliente identificado. La venta genera una cuenta por cobrar, igual que una factura normal.

Descuentos y cambios de precio

Requieren su permiso. Un cambio de precio queda auditado: se registra quién lo hizo.

Movimientos de caja durante el turno

Regístralos en el momento: el arqueo los toma en cuenta.

Reporte X — cómo va el turno

Muestra el estado del turno sin cerrarlo: ventas, cobros por método y efectivo esperado. Úsalo para revisar a mitad de jornada o antes de cerrar.

Anular y devolver

Anular revierte la venta, el inventario y la contabilidad. Si la venta llevó comprobante fiscal, el número no se reutiliza: pasa al reporte 608.

Cerrar el turno (arqueo)

1. Cuenta el efectivo físico en caja.
2. Pulsa Cerrar turno y declara lo contado.
3. El sistema compara contra lo esperado y muestra la diferencia.

Cerrar el turno deja el registro completo del día: ventas, cobros por método, movimientos de caja y diferencia.

Reimprimir un comprobante

Con pos:reprint, desde la venta.

Reportes

Con pos:view-reports: ventas por turno, por caja y por método de pago.

Problemas frecuentes

Estado: Operativo. La rentabilidad se calcula sobre los asientos contables reales filtrados por la dimensión de proyecto. Las pantallas de tareas y horas funcionan; la planificación avanzada (diagrama de Gantt, dependencias entre tareas) no existe.

Para qué sirve

Para saber cuánto costó y cuánto dejó un trabajo concreto: una obra, una implementación, un contrato. El proyecto actúa como una dimensión contable: los documentos que lo llevan asignado suman a su rentabilidad.

Rutas

Proyecto → Proyecto (/proyecto/proyectos)
Proyecto → Rentabilidad (/proyectos/rentabilidad)
Proyecto → Reportes (/proyecto/reportes)
Proyecto → Tareas → Tareas (/utilara-erp/task)
Proyecto → Tiempo y Costos → Registro de Horas (/utilara-erp/timesheet)
Proyecto → Configuración → Tipos de Proyecto (/utilara-erp/project-type)

Permisos

Los botones de eliminación no aparecen si no tienes el permiso.

Crear un proyecto

El proyecto pertenece a una empresa: el espacio de trabajo respeta la empresa seleccionada y tus permisos efectivos.

Tareas

Con project:manage-tasks:

• Crear tareas dentro del proyecto, con su tipo de tarea.
• Registrar actualizaciones de avance.

No hay diagrama de Gantt, ni dependencias entre tareas, ni ruta crítica. Las tareas son una lista de trabajo con estado, no un planificador.

Registro de horas

Proyecto → Tiempo y Costos → Registro de Horas

Las horas se registran contra una tarea. Junto con los costos de actividad y los tipos de actividad, permiten valorar la mano de obra del proyecto.

Rentabilidad — de dónde salen los números

Proyecto → Rentabilidad (/proyectos/rentabilidad)

Esta pantalla no tiene cifras propias: consulta los asientos contables reales filtrados por la dimensión proyecto. Por eso:

• Un documento sin proyecto asignado no aparece en la rentabilidad de ningún proyecto.
• Un documento en borrador tampoco: solo cuentan los asientos posteados.

Lo más importante: para que la rentabilidad sea real, asigna el proyecto en los documentos (facturas, compras, gastos) en el momento de registrarlos. Si nadie lo asigna, la pantalla saldrá vacía y no será un error del sistema.

Cifras que nunca se muestran solas

Las magnitudes de comprometido y cobrado siempre se presentan con su contexto (contra qué se comparan), para no confundir un valor parcial con el resultado del proyecto.

Presupuesto por proyecto

En Contabilidad → Presupuestos, cada línea de presupuesto puede asignarse a un proyecto, además de centro de costo, departamento y sucursal. La importación por CSV acepta esas columnas.

Reportes

Proyecto → Reportes — listados de proyectos con su estado y avance.

Limitaciones reales

Problemas frecuentes

Estado: Casi listo. App hr. Empleados y Departamentos implementados; la nómina postea al GL (PayrollRun/Line/Config). Verificar cobertura de pantallas de nómina en el frontend antes de prometer corridas completas por UI.

Objetivo

Gestionar empleados y departamentos, y procesar la nómina (devengo y pago) con impacto contable.

A quién va dirigido

Recursos Humanos, nómina, contabilidad.

Cuándo se usa

Al registrar empleados, correr la nómina del período y pagarla.

Requisitos previos

• App RRHH instalada (ver ../apps/hr.md).
• Configuración de nómina (cuentas contables de nómina).

Pantallas

Menú nav-hr (hr/*): Empleados, Departamentos, y PayrollAccountingPage (integración contable de nómina).

Paso a paso (nómina)

1. Registra empleados y departamentos.
2. Crea una corrida de nómina (PayrollRun) del período.
3. El sistema calcula las líneas (salario, deducciones) y devenga (asiento balanceado).
4. Paga la nómina vía banco (asiento de pago).

Validaciones importantes

• El devengo es un asiento balanceado.
• Concurrencia controlada (CAS) para no duplicar corridas.
• No se postea en período cerrado.

Errores comunes

• "No aparece RRHH": app no instalada o sin gating.
• "Configuración de nómina faltante": faltan cuentas contables de nómina.

Resultado esperado

Nómina calculada, devengada y pagada, con contabilidad.

Integraciones relacionadas

• Contabilidad: devengo y pago. Ver ../contable/nomina.md.
• Banco: pago de nómina.

Permisos necesarios

Recurso hr (@RequireApp('hr')).

Notas técnicas

• Backend: backend/src/tenant-runtime/hr (hr.controller, payroll.controller). Manifest apps/hr/manifest.json.
• Skills: utilara-hr-app-production, utilara-hr-payroll-accounting-production.

Estado: Listo. Reglas fiscales con vigencia, retenciones con sustitución auditada, reportes 606/607/608 con historial de versiones y conciliación contra la contabilidad.

Mapa del módulo

Impuestos → Reglas y Retenciones → Reglas Fiscales (/impuestos/reglas-fiscales)
Impuestos → Reglas y Retenciones → Retenciones (/impuestos/retenciones)
Impuestos → Serie Fiscal (/impuestos/serie-fiscal/buscar)
Impuestos → Consulta NCF (/impuestos/consulta-ncf)
Impuestos → Impuesto Configuración (/impuestos/configuracion/buscar)
Impuestos → Proporcionalidad del ITBIS (/impuestos/proporcionalidad/buscar)
Impuestos → Reporte 606 / 607 / 608 / 609
Impuestos → Reporte IR-17 / IR-3 / IT-1
Impuestos → Reporte Novedades TSS / Dependientes TSS
Impuestos → Reporte Dinámico (/impuestos/reporte-dinamico)

Permisos

Fíjate en la separación: ver un reporte, generar su versión y descargarlo son tres permisos distintos.

Reglas fiscales

Definen la tasa que se aplica y desde cuándo.

La regla de oro: cuando cambia una tasa, crea una nueva vigencia; no edites la regla anterior. Editarla recalcularía documentos ya emitidos con una tasa que no correspondía a su fecha.

Todas las líneas de impuesto del sistema (ventas, compras, ITBIS automático de Cuentas por Pagar) resuelven contra este motor central. No hay tasas escritas dentro del código.

Retenciones

Categorías de retención (ITBIS retenido, ISR retenido) que se aplican al pagar a proveedores.

• El sistema calcula la retención según la categoría y la regla vigente.
• Con tax:override-calculation se puede sustituir el monto calculado desde la factura de

proveedor. La sustitución queda registrada: quién, cuándo y qué valor.

• El botón de sustitución no aparece para quien no tiene ese permiso.

Series de NCF

Cada rango autorizado por la DGII se registra como una secuencia con su tipo, número de autorización, rango, vigencia y umbral de alerta. El detalle está en la Guía de inicio rápido, paso 4.

Consulta NCF muestra el consumo y la disponibilidad de cada secuencia. Revísala antes de un pico de facturación.

Proporcionalidad del ITBIS

Para empresas con operaciones gravadas y exentas: determina qué proporción del ITBIS pagado en compras es deducible.

Reportes de la DGII

Qué entra y qué no

Esta es la corrección clave de julio de 2026: antes el 607 incluía borradores y anulados.

Historial de versiones

Cada vez que generas un reporte queda registrada la versión: cuándo se generó, quién y con qué resultado. Sirve para saber exactamente qué se declaró y cuándo.

Conciliación fiscal contra la contabilidad

Las pantallas de 606, 607 y 608 incluyen la conciliación contra el mayor: compara lo que declara el reporte fiscal contra lo que dice la contabilidad. Ejecútala antes de presentar: una diferencia aquí es una diferencia que la DGII también verá.

Reporte dinámico

Constructor de consultas sobre los datos fiscales, exportable a CSV.

Rutina mensual sugerida

1. Cierra la facturación del mes.
2. Revisa que no queden facturas en borrador que debían emitirse.
3. Genera el 607 y ejecuta la conciliación contra la contabilidad.
4. Genera el 606 y verifica que los NCF de proveedor estén completos.
5. Genera el 608 y confirma que corresponde a lo anulado.
6. Descarga los CSV y preséntalos.
7. Cierra el período contable para que nadie modifique lo declarado.

Problemas frecuentes

Estado: Listo (app ncf-dgii; reutiliza la lógica fiscal probada del core vía adapter).

Objetivo

Cumplir con la DGII (República Dominicana): emitir Comprobantes Fiscales (NCF) y e-CF, y generar los reportes 606/607/608.

A quién va dirigido

Facturación, contabilidad, cumplimiento fiscal.

Cuándo se usa

Al facturar con comprobante fiscal, registrar NCF de proveedores y presentar reportes a la DGII.

Requisitos previos

• App NCF/DGII instalada (ver ../apps/ncf-dgii.md).
• Series NCF configuradas (ver ../administrativo/ncf-dgii.md).

Pantallas

Se integra con Facturación (consumo de NCF al emitir) y con el menú Impuestos:

Además, la app añade pantallas propias (e-CF recibidos, aprobación comercial, cancelaciones, carga masiva).

Paso a paso (emitir NCF)

1. Al emitir una factura (ver facturacion.md), elige la serie NCF. El sistema asigna el siguiente número sin huecos.
2. El NCF queda consumido y aparece en el 607.

Paso a paso (reporte 607)

1. Menú Impuestos → Reporte 607.
2. Selecciona el período.
3. Genera → lista las ventas con NCF para presentar a la DGII.

Validaciones importantes

• Numeración sin huecos (gapless) por tipo de comprobante.
• El tipo de NCF debe corresponder a la operación (venta, consumidor final, nota de crédito, etc.).

Errores comunes

• "No hay NCF disponible": la serie se agotó.
• "Tipo de NCF incorrecto": el comprobante no aplica a la operación.

Resultado esperado

Comprobantes emitidos correctamente y reportes 606/607/608 listos para la DGII.

Integraciones relacionadas

• Facturación / CxC: consumo de NCF de ventas → 607.
• CxP / Compras: NCF de proveedores → 606.

Permisos necesarios

Los de la app ncf-dgii (@RequireApp('ncf-dgii')).

Notas técnicas

• Backend: apps/ncf-dgii/backend (adapter que reutiliza NcfService/EcfXmlService del core). Modelos Ecf*.
• Skill: utilara-ncf-dgii-app-production.

Estado: Listo. Los indicadores, la diferencia cambiaria y el presupuesto se calculan sobre los datos contables reales, con desglose.

Qué encuentras aquí

Finanzas es la capa de análisis sobre la contabilidad. Los estados financieros básicos están tanto aquí como en Contabilidad; lo propio de este módulo son los indicadores, el presupuesto y lo multimoneda.

Finanzas → Análisis Financiero (/finanzas/analisis-financiero)
Finanzas → Balanza de Comprobación (/finanzas/balanza-comprobacion)
Finanzas → Balance General (/finanzas/balance-general)
Finanzas → Estado de Resultados (/finanzas/estado-resultados)
Finanzas → Flujo Efectivo (/finanzas/flujo-efectivo)
Finanzas → Variación Capital (/finanzas/variacion-capital)
Finanzas → Conversión Moneda (/finanzas/conversion-moneda)
Finanzas → Diferencia Cambiaria (/finanzas/diferencia-cambiaria)
Finanzas → Presupuesto (/finanzas/presupuesto)
Finanzas → Reporte Dinámico (/finanzas/reporte-dinamico)

Permisos

Los permisos son finos a propósito: puedes dar acceso a los estados financieros sin dar acceso al presupuesto.

Análisis financiero

Presenta el conjunto de indicadores con desglose: cada ratio permite ver de qué cuentas salió. Sin ese desglose un indicador es un número sin defensa; con él se puede auditar.

Se agrupan en las familias habituales: liquidez, endeudamiento, rentabilidad y actividad.

Un indicador solo es tan bueno como la contabilidad que lo alimenta. Si la clasificación de cuentas está mal, el ratio saldrá mal.

Diferencia cambiaria

Reporte real sobre el motor de tipo de cambio: muestra el efecto de la variación de la tasa sobre los saldos en moneda extranjera.

Depende de dos cosas:

1. Que las tasas de cambio estén cargadas (Banco → Cambio Tasa).
2. Que estén configuradas las cuentas por moneda de la empresa: cuenta por cobrar y por

pagar de cada moneda, sus cuentas de prima, y las cuentas de ganancia y pérdida cambiaria.

Sin la configuración por moneda, los saldos en pesos y en dólares se mezclan en la misma cuenta de control y el reporte pierde sentido.

Conversión de moneda

Presenta los saldos convertidos a la moneda que elijas, usando las tasas registradas.

Presupuesto

Conectado al motor real de presupuesto: lo que registras aquí es lo que compara la ejecución.

Reporte dinámico

Constructor de reportes sobre los datos contables: eliges columnas, filtras y agrupas.

Campos disponibles (entre otros): número de asiento, fecha, estado (DRAFT / POSTED / VOID), origen, concepto, cuenta, naturaleza de la cuenta, débito, crédito, centro de costo y departamento, moneda, tasa y período fiscal.

Se exporta a CSV.

Filtra por estado POSTED si quieres cifras contables definitivas: los borradores no forman parte de la contabilidad.

Diferencia con el módulo de Contabilidad

Ambos leen la misma contabilidad: no hay dos fuentes de verdad.

Problemas frecuentes

Estado: Casi listo. App crm (Citrus). Fase 1 (Dashboard + Configuración, 25 secciones) y Fase 2 (pantallas operativas) implementadas. Verificar qué pantallas operativas están conectadas antes de prometer flujos completos.

Objetivo

Gestionar la relación con clientes y prospectos: pipeline de ventas, contactos, actividades y marketing.

A quién va dirigido

Ventas, marketing, servicio al cliente.

Cuándo se usa

Para seguimiento de oportunidades, contactos y campañas — complementa Facturación/CxC (no las duplica).

Requisitos previos

• App CRM instalada (ver ../apps/crm.md).

Pantallas

La app añade su propio menú (crm/): Dashboard, Configuración (25 secciones), y pantallas operativas (contactos, oportunidades, actividades, reportes, chat). Rutas bajo crm/ en App.tsx.

Paso a paso (uso típico)

1. Instala y entra a CRM desde el menú.
2. Revisa el Dashboard.
3. Configura las secciones necesarias en Configuración.
4. Trabaja tus contactos/oportunidades en las pantallas operativas.

Validaciones importantes

• El CRM reutiliza entidades del core (User, Currency, Tax, Item, Company) — no crea clientes/ítems paralelos.
• Si la app no está instalada, sus endpoints responden fail-closed.

Errores comunes

• "No aparece CRM": la app no está instalada, o client.sidebar.hiddenCodes la oculta.

Resultado esperado

Gestión comercial complementaria al ERP.

Integraciones relacionadas

• Reutiliza clientes/ítems del ERP; se enlaza con Facturación/CxC.

Permisos necesarios

Los de la app crm (@RequireApp('crm')).

Notas técnicas

• Backend/Frontend: apps/crm/. 31 modelos Crm*. Manifest en /home/admin/devapps/utilara-crm/manifest.json.
• Skill: utilara-crm-app-production.

Estado: Casi listo. Los reportes financieros (Balanza, Mayor, Estado de Resultados, Balance General, Flujo) están conectados y derivan del mayor real. El menú Reportes agrupa accesos a esos reportes de otros módulos; algunos "reportes dinámicos" pueden ser genéricos (No verificado).

Objetivo

Consultar la información del negocio en forma de reportes: financieros, de ventas/CxC, de compras/CxP e inventario.

A quién va dirigido

Contabilidad, finanzas, gerencia.

Pantallas (menú Reportes)

Cada módulo también tiene sus propios reportes internos (CxC, CxP, Inventario, Banco, Compras, Impuestos, Facturación).

Paso a paso

1. Menú Reportes → elige el grupo y el reporte.
2. Define período/filtros.
3. Genera y, si aplica, exporta.

Validaciones importantes

• Los estados financieros derivan del mayor (gl-entry), no de un módulo aparte.

Errores comunes

• "Reporte vacío": sin movimientos en el período, o filtros muy restrictivos.

Resultado esperado

Reporte con datos consistentes con la contabilidad.

Integraciones relacionadas

• Contabilidad (fuente de los financieros), CxC, CxP, Inventario.

Permisos necesarios

accounting:read y los del módulo correspondiente.

Notas técnicas

• Ver ../contable/reportes-financieros.md. Detalle técnico en ../tecnico/eventos-y-gl.md.

Estado: Listo.

Objetivo

Crear, invitar y gestionar los usuarios de la empresa, y asignarles sus perfiles.

A quién va dirigido

Administrador de la empresa.

Cuándo se usa

Al incorporar personal, cambiar responsabilidades o dar de baja usuarios.

Requisitos previos

• Perfiles (roles) definidos (ver roles-y-permisos.md).

Paso a paso

1. Menú Seguridad → Usuarios → Usuario (nuevo).
2. Registra nombre, correo y datos básicos.
3. Guarda / envía invitación (el usuario define su contraseña al aceptar).
4. Menú Seguridad → Usuario → Perfiles Usuario: asigna uno o más perfiles.

Campos explicados

Botones/acciones

• Crear / Invitar usuario.
• Asignar perfiles.
• Desactivar (bloquea acceso sin borrar historial).

Validaciones importantes

• Un usuario sin perfil no ve módulos.
• La baja debe ser desactivación, no borrado, para preservar auditoría.

Errores comunes

• "El usuario no ve nada": falta asignar perfil/permisos.
• "Invitación no llega": revisar configuración de correo.

Resultado esperado

Usuario activo con el acceso correcto.

Integraciones relacionadas

• RBAC / Perfiles.

Permisos necesarios

Administración de usuarios/seguridad.

Notas técnicas

• Frontend: /security/usuario/*, AcceptInvitePage. Backend: tenant-runtime/users, tenant-runtime/auth.

Estado: Listo (permisos centrales manifest-driven; fail-closed).

Objetivo

Controlar con precisión qué puede hacer cada usuario, mediante perfiles (roles) que agrupan permisos por recurso y acción.

A quién va dirigido

Administrador de la empresa.

Conceptos

Paso a paso (definir permisos de un perfil)

1. Menú Seguridad → Perfiles → Permisos Perfil (SecPerfilPermisosPage).
2. La matriz muestra el catálogo de permisos = núcleo ERP + apps instaladas (GET /permissions/catalog).
3. Marca las acciones permitidas por recurso.
4. Guarda.
5. Asigna el perfil a los usuarios (ver usuarios.md).

Validaciones importantes

• Fail-closed: sin el permiso, la acción se rechaza (403) — TenantPermissionGuard.
• Instalar una app siembra sus permisos y los otorga al ADMIN automáticamente (idempotente).
• Existe RBAC a nivel de campo/fila en apps tipadas (Etapa 3, ver commits recientes) para restringir campos dentro de una pantalla.

Errores comunes

• "403 al operar": el perfil no tiene el permiso.
• "Un permiso nuevo no aparece": la app que lo aporta no está instalada.

Resultado esperado

Cada rol con exactamente el acceso que necesita.

Integraciones relacionadas

• Todos los módulos y apps.

Permisos necesarios

Administración de seguridad.

Notas técnicas

• Seed: tenant-runtime/provisioning/tenant-rbac.seed.ts, catálogo tenant-runtime/permissions/permission-catalog.ts. Guard tenant-runtime/auth/tenant-permission.guard.ts (RequirePermission).
• Memoria: project_rbac_central_permissions. Detalle técnico en ../tecnico/rbac.md.

Estado: Casi listo. El aislamiento multi-tenant (base por cliente, ADR-001) está implementado. La creación de tenants es del control-plane (dueño de la plataforma), no del admin de empresa.

Objetivo

Entender cómo se organiza el ERP en empresas (tenants) y compañías, y quién administra cada nivel.

A quién va dirigido

Administrador de empresa y equipo de UtilARA (provisioning).

Conceptos

Cómo se crea un tenant

• Lo hace el control-plane (Admin Panel / provisioning del dueño), no el admin de la empresa. Ver ../tecnico/multi-tenant.md y ../tecnico/admin-panel.md.
• Al crear el tenant se siembra su base: plan de cuentas base, RBAC (perfil ADMIN), y se instala el app core utilara-erp.

Qué administra el admin de empresa

• Usuarios y permisos dentro de su tenant.
• Catálogos maestros (cuentas, impuestos, almacenes, monedas).
• Apps instalables de su empresa.

Validaciones importantes

• Aislamiento por base: un usuario de un tenant no puede leer datos de otro (regla R12). El aislamiento es por conexión, no por RLS.

Errores comunes

• "Veo datos de otra empresa": sería un fallo grave de aislamiento; reportar de inmediato (existe test de arquitectura anti-regresión y skill utilara-security-production).

Resultado esperado

Cada empresa opera aislada y con su propia configuración.

Notas técnicas

• ADR-001: database-per-tenant. Provisioning en tenant-runtime/provisioning. Control-plane en backend/src/control-plane/tenants.
• Memoria: project_erp_core_spec, project_security_hardening_2026-07-06.

Estado: Operativo. Los cuatro conceptos existen y se usan de verdad. La confusión entre ellos es la causa más común de una implantación que hay que rehacer.

La decisión, en una tabla

Los cuatro se combinan. Un caso típico: una empresa, tres sucursales, cada una con su almacén y su tienda.

Empresa

Una entidad legal con contabilidad propia.

Contabilidad → Configuración (/accounting/config)

Crear una empresa de más es caro: duplica catálogos y obliga a consolidar para ver el total. Créala solo si hay una razón legal o fiscal.

Sucursal

Una dimensión contable, junto a centros de costo y departamentos.

Contabilidad → Configuración → Dimensiones → Sucursales

Dónde se usa: asientos y sus líneas, filtros del Mayor, Estado de Resultados, Balance, Flujo de Efectivo, y líneas de presupuesto (columna branchCode en la importación CSV).

Lo que la sucursal NO hace: no tiene numeración propia de factura, ni secuencia de NCF propia, ni controla existencias.

Existe además el campo Sucursal / Establecimiento en Configurar Compañía: es solo un texto que se imprime en el comprobante. No es la dimensión contable.

Almacén

Donde vive físicamente el stock.

Inventario → Almacén (/inventory/warehouses)

• Cada movimiento de inventario entra o sale de un almacén.
• La factura descuenta del almacén de despacho elegido.
• La existencia inicial se carga por artículo y por almacén.
• Dentro de un almacén puedes definir ubicaciones (/inventory/locations).

Crea un almacén por cada sitio donde de verdad necesites saber cuánto hay: bodega, tienda, vehículo de reparto, mercancía en consignación.

Tienda

El punto de venta.

Facturación → Tiendas (/facturacion/tienda/buscar)
Facturación → Tipo Tienda (/facturacion/tipo-tienda/buscar)

La tienda es la unidad del Terminal POS: contra ella se abren turnos, se cobra y se hace el arqueo. Se asocia a un almacén, de donde descuenta la mercancía.

Cómo se relacionan

Empresa (RNC, contabilidad, NCF)
 ├── Sucursal → dimensión contable: "¿cuánto dejó este local?"
 ├── Almacén → existencias: "¿cuánto hay aquí?"
 └── Tienda → punto de venta: "¿quién cobró y cuánto?"

Ejemplos

Cadena de tres locales, un solo RNC

• 1 empresa.
• 3 sucursales: SD, STGO, LR.
• 4 almacenes: uno por local + bodega central.
• 3 tiendas, una por local.

Resultado: Estado de Resultados por sucursal, existencias por almacén y arqueo por tienda.

Dos razones sociales

• 2 empresas, cada una con su plan de cuentas y sus secuencias de NCF.
• Sucursales, almacenes y tiendas dentro de cada una.
• Consolidación para ver el total del grupo.

Empresa con bodega y venta solo por facturación

• 1 empresa, 1 almacén, sin tiendas (no usas POS), y sucursales solo si quieres

separar el resultado por zona.

Errores frecuentes

Estado: Casi listo. Fase 1 (Dashboard + Configuración) y Fase 2 (operativas) implementadas; verificar cobertura de pantallas operativas conectadas.

Identidad

Qué hace

Gestión de relación con clientes: dashboard, configuración (25 secciones), y pantallas operativas (contactos, oportunidades, actividades, reportes, chat). Complementa Facturación/CxC, no las duplica.

Cómo reutiliza el core

Reutiliza User, Currency, Tax, Item, Company del ERP. **31 modelos Crm*** propios.

Backend

apps/crm/backend: crm.controller.ts, crm-config.controller.ts, crm-operational.controller.ts, crm-lookups.controller.ts, crm-reports.controller.ts, crm-chat.controller.ts — con @RequireApp('crm').

Frontend

apps/crm/frontend, rutas crm/* en App.tsx, pantallas en appScreenRegistry.tsx. Manifest vivo: /home/admin/devapps/utilara-crm/manifest.json.

GOTCHAs

• client.sidebar.hiddenCodes puede ocultar la app.
• AppRequirementGuard ya no cachea (gating instantáneo).

Usuario

Ver ../usuario/crm.md.

Skill

utilara-crm-app-production. Memoria project_crm_app.

Estado: Casi listo. Es la app dental real que se conserva (a diferencia de las demos borradas). Verificar cobertura de pantallas/flujos antes de prometer clínica dental completa.

Identidad

Qué hace

App vertical para clínica dental. Estructura más autónoma que las demás (tiene prisma/, schemas/, seeds/ propios en apps/dental/).

Estructura

apps/dental/
├── manifest.json
├── backend/ (dental.controller.ts con @RequireApp)
├── frontend/
├── prisma/ (schema propio)
├── schemas/
└── seeds/

Notas

• Es la app dental verdadera; las demos utilara-dental/utilara-retail/utilara-veterinary (solo manifests) fueron borradas en la limpieza del catálogo (memoria project_apps_catalog_cleanup). No confundir.
• Frontend tiene pages/dental/.

Verificar antes de demo

• Qué pantallas están conectadas a backend real vs. genéricas.
• Si factura/contabiliza a través del core.

Skill

No hay skill utilara-dental-* dedicada en la lista; usar el código en apps/dental/ y apps/dental/README.md como referencia. Estado detallado: No verificado verificar end-to-end.

Estado: Listo (Production ready según skill utilara-ncf-dgii-app-production).

Identidad

Qué hace

Comprobantes Fiscales Electrónicos (e-CF) y cumplimiento DGII (RD): emisión, recepción, aprobación comercial, cancelaciones, carga masiva, y reportes 606/607/608.

Cómo reutiliza el core

La lógica fiscal probada del core (NcfService, EcfXmlService, series NcfSequence, uso NcfUsage, e-CF EcfDocument, reportes 606/607/608) se reutiliza vía adapter — no se duplica.

Modelos propios (6)

EcfReceived, EcfCommercialApproval, EcfCancellation, EcfRecurringTransaction, EcfBulkUpload, EcfSignedXmlLog.

Pantallas

Menú propio de la app + integración con Facturación (consumo NCF) e Impuestos (606/607/608). Ver ../usuario/ncf-dgii.md.

Backend

apps/ncf-dgii/backend — controllers ncf-dgii.controller.ts, ncf-dgii-config.controller.ts con @RequireApp('ncf-dgii').

GOTCHAs

• Build con riesgo de heap OOM (usar heap ampliado).
• Permisos en doble copia .ts/.mjs.

Contabilidad

Ver ../contable/ncf-dgii.md.

Skill

utilara-ncf-dgii-app-production. Memoria project_ncf_dgii_app.

Estado: Casi listo. Empleados/Departamentos + integración contable de nómina (postea al GL). Verificar cobertura de UI de nómina.

Identidad

Qué hace

Gestión de empleados y departamentos, y motor de nómina tipado (PayrollRun/PayrollLine/PayrollConfig) que postea al GL central (devengo + pago).

Backend

backend/src/tenant-runtime/hr (hr.controller.ts, payroll/payroll.controller.ts) con @RequireApp('hr'). Manifest apps/hr/manifest.json.

Contabilidad de nómina

• Devengo: Dr Gasto sueldos / Cr Sueldos por pagar (neto) / Cr deducciones (TSS/ISR/INFOTEP).
• Pago: Dr Sueldos por pagar / Cr Banco.
• Cuentas configurables en PayrollConfig (bloquea si faltan). Ver ../contable/nomina.md.

Frontend

Rutas hr/* en App.tsx, PayrollAccountingPage.tsx, HrPage.tsx.

Cierra brecha de auditoría

RRHH antes no posteaba al GL; ahora sí (memoria project_hr_payroll_accounting).

Usuario

Ver ../usuario/rrhh.md y ../flujos/nomina.md.

Skills

utilara-hr-app-production, utilara-hr-payroll-accounting-production.

Estado: Listo (Production ready según skill utilara-veterinary-app-production).

Identidad

Qué hace

Clínica veterinaria completa: dueños, mascotas, agenda, expediente clínico, vacunas, quirófano, hospitalización, laboratorio, imagenología, farmacia, grooming, hotel, caja, CRM, portal público del dueño, y reportes.

Alcance real

• 66 tablas / 101 pantallas + uploader real de archivos.
• Portal público del dueño de la mascota.
• Proveedores de mensajería y web pública.
• Retiró el módulo veterinario legado basado en EntityRecord.
• Delega facturación/CRM/marketing al ERP y a la app CRM (commit refactor(veterinary): delegate billing/CRM/marketing to ERP and CRM app).

Backend

apps/veterinary/backend: controllers veterinary.controller.ts, veterinary-clinical.controller.ts, veterinary-operations.controller.ts, veterinary-billing.controller.ts, veterinary-crm.controller.ts, veterinary-portal.controller.ts, veterinary-premium.controller.ts, veterinary-resource.controller.ts, veterinary-attachments.controller.ts — con @RequireApp('veterinary').

Frontend

apps/veterinary/frontend, rutas veterinary/ en App.tsx, pantallas en appScreenRegistry.tsx. Modelos Veterinary en el schema de tenant.

RBAC de campo/fila

La app tiene permisos a nivel de campo/fila (Etapa 3, commits recientes). Ver ../tecnico/rbac.md.

Verificación

Smoke tests: docs/fixtures/veterinary-*-smoke.md. Test: veterinary-app.spec.ts.

Skill

utilara-veterinary-app-production. Memoria project_veterinary_app.

Estado: Listo (depends_on real en los manifests).

Qué es

Una app puede declarar en su manifest.json que depende de otra (depends_on). No debe instalarse ni funcionar sin su base.

Dependencias reales (de los manifests)

dental no declara depends_on en su manifest (app vertical más autónoma). El resto de apps requieren el core utilara-erp.

Por qué importa

• Las apps que dependen de utilara-erp reutilizan su facturación, contabilidad, inventario, clientes, etc. No duplican el core.
• Instalar la dependiente sin la base dejaría endpoints/pantallas sin su backing.

Cómo se declara

{
 "code": "crm",
 "depends_on": ["utilara-erp"],
 "minPlan": "BASIC"
}

minPlan

Indica el plan mínimo requerido (ej. BASIC). El gating por plan lo evalúa la plataforma.

Validaciones

• Al instalar, verificar que las dependencias estén presentes.
• Al desinstalar el core, considerar el impacto en las apps dependientes.

Notas técnicas

• Manifests en apps/<code>/manifest.json (y copia en /home/admin/devapps/). Ver crear-nueva-app-instalable.md.

Estado: Listo.

Instalar

Desde la UI: Catálogo de Apps del tenant → Instalar / Desinstalar.

Qué pasa al instalar (AppInstallerService.install)

1. Crea/actualiza InstalledApp con enabled=true.
2. Siembra los permisos de la app y los otorga al perfil ADMIN (idempotente).
3. Registra las entradas de menú del manifest de la app.

Qué pasa al desinstalar

1. Marca enabled=false.
2. Dispara onAppUninstalled(tenant, code) (limpieza de integraciones).
3. Los endpoints de la app vuelven a responder fail-closed (403/404) de inmediato.

Efecto en el menú

• Al instalar, el menú de la app aparece. Si depende de overrides de menú, puede requerir reiniciar el backend. Ver ../tecnico/menu-y-overrides.md.
• client.sidebar.hiddenCodes puede ocultar una app aunque esté instalada.

Validaciones

• Dependencias: una app con depends_on requiere que la base esté instalada (ej. crm, hr, ncf-dgii, veterinary dependen de utilara-erp). Ver dependencias-de-apps.md.
• Reinstalar es idempotente (no duplica permisos).

Verificar

curl -H "Authorization: Bearer <jwt>" http://localhost:3000/t/<slug>/apps

Debe listar la app con enabled: true.

Flujo E2E completo

Ver ../flujos/app-install-uninstall.md.

Para quién: implementadores y desarrolladores que instalan, configuran o crean apps para el ERP.

¿Qué es una app instalable?

UtilARA ERP tiene un núcleo (core) de módulos siempre presentes (Contabilidad, CxC, CxP, Compras, Inventario, Banco, Activos Fijos, Caja Chica, Facturación). Sobre ese núcleo, cada empresa puede instalar apps adicionales que:

• añaden pantallas al menú,
• exponen sus propios endpoints (bloqueados si la app no está instalada — fail-closed),
• declaran sus permisos y a veces dependencias de otras apps,
• reutilizan el core (facturación, contabilidad, inventario) en vez de duplicarlo.

Las apps viven en apps/<code>/ (backend + frontend + manifest.json).

Apps documentadas

Guías transversales

Detalles técnicos

Ver también ../tecnico/apps-instalables.md y ../tecnico/app-registry.md para el mecanismo interno (@RequireApp, AppRequirementGuard, AppRegistryService).

Estado: Casi listo. La configuración está repartida por módulo (Contabilidad → Configuración, Facturación, Impuestos, etc.) y en el menú Seguridad → Configuración (permisos por área). No existe un único "módulo de Configuración General" centralizado del core (el módulo general fue eliminado; ver memoria del proyecto).

Objetivo

Ajustar los parámetros del ERP para la empresa.

A quién va dirigido

Administrador de la empresa.

Dónde se configura cada cosa

Paso a paso

1. Identifica qué vas a configurar (usa la tabla anterior).
2. Ve al módulo correspondiente y su pantalla de Configuración / catálogo.
3. Guarda; algunos cambios de menú requieren reiniciar el backend (ver nota técnica).

Validaciones importantes

• Cambios al menú/manifest no aplican en caliente: requieren reinicio del backend y purgar overrides si aplica.

Errores comunes

• "Configuré algo del menú y no aparece": backend no reiniciado / override no purgado. Ver ../tecnico/menu-y-overrides.md.

Resultado esperado

ERP ajustado a la operación de la empresa.

Permisos necesarios

Permisos de administración por área (ver ../administrativo/roles-y-permisos.md).

Notas técnicas

• El módulo "Configuración General" del core fue eliminado (memoria project_modules_removed_2026-07-11). La configuración vive por módulo.

Estado: Casi listo. No hay un único módulo de "Configuración General" del core (fue eliminado). La configuración vive por módulo y en Seguridad → Configuración.

Objetivo

Orientar al administrador sobre dónde ajustar cada parámetro del ERP.

A quién va dirigido

Administrador de la empresa.

Dónde se configura cada cosa

Paso a paso

1. Identifica el parámetro con la tabla.
2. Ve al módulo → su pantalla de configuración/catálogo.
3. Guarda. Si tocaste el menú/manifest, requiere reinicio del backend.

Validaciones importantes

• Cambios de menú/manifest no son en caliente. Ver ../tecnico/menu-y-overrides.md.

Errores comunes

• "Cambié el menú y no aparece": falta reiniciar el backend / purgar overrides.

Notas técnicas

• Memoria: project_modules_removed_2026-07-11 (Configuración General del core eliminada). Ver ../usuario/configuracion.md.

Estado: Casi listo. Existen pantallas de Moneda y Cambio de Tasa en el módulo Banco. La automatización de la diferencia cambiaria/revaluación debe verificarse (No verificado).

Objetivo

Definir las monedas que maneja la empresa y sus tasas de cambio.

A quién va dirigido

Administrador / tesorería / contabilidad.

Pantallas

Paso a paso

1. Menú Banco → Moneda: registra la moneda (código, símbolo).
2. Menú Banco → Cambio Tasa → Crear: registra la tasa vigente por fecha.

Validaciones importantes

• Las operaciones multi-moneda usan la tasa registrada.
• La diferencia cambiaria debe reconocerse contablemente (verificar automatización).

Errores comunes

• "Sin tasa para la fecha": falta registrar la tasa del período.

Resultado esperado

Operaciones en varias monedas con conversión correcta.

Integraciones relacionadas

• Banco, CxC, CxP, Facturación, Finanzas.

Permisos necesarios

banking:create/update.

Notas técnicas

• Backend: tenant-runtime/banking. Verificar revaluación automática y diferencia cambiaria antes de prometerlas.

Estado: Casi listo. Existe un menú Impuestos completo (configuración, retenciones, reglas fiscales, reportes). Algunas pantallas de reporte fiscal (IR-17, IR-3, IT-1, TSS) y "reporte dinámico" deben verificarse individualmente (No verificado).

Objetivo

Configurar los impuestos que aplica la empresa: ITBIS (impuesto a las ventas), retenciones ITBIS/ISR y reglas fiscales.

A quién va dirigido

Administrador / contador / cumplimiento fiscal.

Pantallas (menú Impuestos)

Paso a paso (configurar ITBIS)

1. Menú Impuestos → Impuesto Configuración (nuevo).
2. Define la tasa (ej. 18%), la cuenta contable asociada (ITBIS por pagar / adelantado) y su aplicación.
3. Asocia el impuesto a los ítems correspondientes.

Paso a paso (retenciones)

1. Menú Impuestos → Retenciones.
2. Define la categoría de retención (ITBIS/ISR), tasa y cuenta.
3. Se aplican al registrar facturas de proveedor (CxP).

Validaciones importantes

• Las cuentas de impuestos deben existir en el plan.
• Las series NCF alimentan 606/607/608.

Errores comunes

• "El impuesto no se calcula": el ítem no tiene el impuesto asociado.
• "Retención no aplica": falta la categoría de retención en el proveedor/factura.

Resultado esperado

Impuestos y retenciones calculados automáticamente en facturas y compras, y reportes fiscales generables.

Integraciones relacionadas

• Facturación (ITBIS ventas → 210201), CxP (retenciones → 210203/210204, ITBIS adelantado → 110401), NCF/DGII (606/607/608).

Permisos necesarios

Administración fiscal / contabilidad.

Notas técnicas

• Reglas de posting usan cuentas de impuestos (ver cuentas-contables.md). NCF: ver ncf-dgii.md.
• Verificar el estado real de los reportes IR-17/IR-3/IT-1/TSS antes de prometerlos (algunos pueden ser pantallas genéricas).

Estado: Parcial, y conviene saberlo antes de prometerlo. La numeración fiscal (NCF) es totalmente configurable. La numeración interna de los documentos es automática y no se configura desde ninguna pantalla.

Los dos tipos de numeración

Son independientes: una factura tiene ambos.

Numeración interna — cómo funciona

El sistema asigna el número al guardar el documento, con el formato:

<PREFIJO>-<AÑO>-<SECUENCIAL DE 6 DÍGITOS>

Características:

• Por empresa y por año. Cada empresa lleva su propia serie y reinicia al cambiar el año.
• Automática. El campo aparece como (auto) y no se puede escribir.
• No configurable. No existe pantalla para cambiar el prefijo, la longitud o el punto de

partida.

Si necesitas otro formato, es un cambio de sistema, no de configuración. Plantéalo a soporte antes de arrancar: cambiarlo con documentos ya emitidos es mucho más complejo.

Preguntas que surgen siempre

¿Puedo empezar en el número 1000 porque vengo de otro sistema? No desde la interfaz.

¿Puedo tener una serie por sucursal? No. La serie es por empresa. Si necesitas series separadas de verdad, la separación real es por empresa.

¿Se saltan números? La numeración interna es correlativa por empresa y año. Un documento anulado conserva su número: no se reutiliza ni se reasigna.

Numeración fiscal (NCF) — sí es configurable

Impuestos → Serie Fiscal (/impuestos/serie-fiscal/nuevo)

Aquí registras cada rango que la DGII te autorizó:

Restricción: no puede haber dos secuencias del mismo tipo con el mismo número inicial en la misma empresa.

Formato emitido

B + tipo (2 dígitos) + secuencial (8 dígitos) = 11 caracteres, sin guiones: B0100000026.

Cuándo se consume

Es lo que garantiza una numeración fiscal sin huecos y trazable.

Vigilar el consumo

Impuestos → Consulta NCF (/impuestos/consulta-ncf)

Muestra cuánto queda de cada secuencia. Revísala antes de un pico de facturación: quedarse sin NCF a mitad de mes detiene la facturación hasta que la DGII autorice un rango nuevo, y esa autorización no es inmediata.

Ajusta el umbral de alerta según tu volumen: si emites 200 facturas al día, un umbral de 50 te avisa con apenas unas horas de margen.

Resumen

Estado: Listo.

Objetivo

Mantener el plan de cuentas (catálogo de cuentas) que usa toda la contabilidad de la empresa.

A quién va dirigido

Administrador / contador.

Cuándo se usa

Al configurar la empresa y al necesitar cuentas nuevas.

Pantalla

Menú Contabilidad → Plan de Cuentas (/accounting/accounts).

Paso a paso

1. Menú Contabilidad → Plan de Cuentas.
2. Crea una cuenta: código, nombre, tipo (activo, pasivo, patrimonio, ingreso, gasto) y si es de movimiento o agrupadora.
3. Guarda.

Cuentas clave que usa el sistema automáticamente

Las reglas de posting automático usan códigos específicos (pueden variar por empresa; revisar accounting-rules):

Estos son los valores por defecto de accounting-rules.defaults.ts. La empresa puede tener un mapa distinto; verificar en Contabilidad → Configuración.

Validaciones importantes

• No borrar cuentas con movimiento (desactivar en su lugar).
• Las cuentas que usan las reglas automáticas deben existir.

Errores comunes

• "Cuenta inexistente al postear": una regla apunta a un código que no está en el plan.

Resultado esperado

Plan de cuentas completo y coherente con las reglas de posting.

Integraciones relacionadas

• Todos los módulos que postean al GL.

Permisos necesarios

accounting:create/update.

Notas técnicas

• Backend: tenant-runtime/accounting (createAccount). Reglas: accounting-rules.defaults.ts. Ver ../contable/plan-de-cuentas.md.

Estado: Listo.

Objetivo

Definir los almacenes (bodegas) donde se guarda y mueve el inventario.

A quién va dirigido

Administrador / almacén.

Pantalla

Menú Inventario → Almacén (/inventory/warehouses).

Paso a paso

1. Menú Inventario → Almacén (nuevo).
2. Registra código, nombre, ubicación.
3. Guarda. Ya puedes recibir/mover inventario en ese almacén.

Validaciones importantes

• Los movimientos requieren un almacén válido.
• No borrar almacenes con existencias.

Errores comunes

• "Sin almacén": no se puede registrar un movimiento sin almacén.

Resultado esperado

Almacenes listos para operar inventario, recepciones y traslados.

Integraciones relacionadas

• Inventario, Compras (recepción), Facturación (despacho).

Permisos necesarios

inventory:create/update.

Notas técnicas

• Backend: tenant-runtime/inventory. Ver ../usuario/inventario.md.

Estado: Listo (lógica fiscal del core probada; app ncf-dgii para e-CF).

Objetivo

Configurar las series de NCF (rangos de comprobantes autorizados por la DGII) para que Facturación pueda emitir comprobantes fiscales.

A quién va dirigido

Administrador / cumplimiento fiscal.

Requisitos previos

• Autorización de rangos por la DGII.
• App NCF/DGII instalada si se usa e-CF (ver ../apps/ncf-dgii.md).

Paso a paso (crear una serie NCF)

1. Menú Impuestos → Serie Fiscal (nuevo).
2. Define el tipo de comprobante (ej. crédito fiscal B01, consumidor final B02, nota de crédito B04, etc.), el rango (desde/hasta) y la fecha de vencimiento.
3. Guarda. Facturación asignará el siguiente número disponible al emitir.

Campos explicados

Validaciones importantes

• Numeración sin huecos (gapless) por tipo.
• No emitir con serie vencida o agotada.

Errores comunes

• "No hay NCF disponible": serie agotada o vencida.
• "Tipo incorrecto": el comprobante no aplica a la operación.

Resultado esperado

Series listas para que Facturación emita comprobantes válidos, y reportes 606/607/608 correctos.

Integraciones relacionadas

• Facturación (consumo NCF ventas → 607), CxP (NCF proveedor → 606).

Permisos necesarios

Administración fiscal.

Notas técnicas

• Backend core: tenant-runtime/ncf (NcfService, EcfXmlService, NcfSequence, NcfUsage, EcfDocument). App: apps/ncf-dgii.
• Skill: utilara-ncf-dgii-app-production. Ver ../contable/ncf-dgii.md.

Estado: Listo (instalar/desinstalar por endpoint real; siembra permisos y menú).

Objetivo

Que el administrador instale/desinstale las apps que su empresa necesita (CRM, RRHH, NCF/DGII, verticales).

A quién va dirigido

Administrador de la empresa.

Cuándo se usa

Al habilitar una funcionalidad opcional para la empresa.

Requisitos previos

• La app debe existir en el registry de la plataforma.
• Algunas apps dependen de otras (ver ../apps/dependencias-de-apps.md).

Paso a paso

1. Entra al Catálogo de Apps del tenant (pantalla apps/).
2. Elige la app y presiona Instalar.
3. Al instalar, el sistema:

• marca la app como instalada (InstalledApp),
• siembra sus permisos y los otorga al perfil ADMIN (auto-grant idempotente),
• añade sus entradas de menú.

1. Para quitarla, presiona Desinstalar (marca enabled=false).

Endpoints reales

Validaciones importantes

• Fail-closed: si una app no está instalada/enabled, sus endpoints responden 403/404 (@RequireApp).
• El gating es instantáneo (el AppRequirementGuard ya no cachea).
• Al desinstalar, se dispara onAppUninstalled (limpieza de integraciones).

Errores comunes

• "La app no aparece tras instalar": el menú puede requerir reinicio del backend si depende de overrides; y client.sidebar.hiddenCodes puede ocultarla.
• "Install respondió error pero la app quedó activa": bug histórico corregido (no marcar enabled si el install falla) — verificar en versiones viejas.

Resultado esperado

App instalada, con menú y permisos, lista para usar.

Integraciones relacionadas

• RBAC (siembra de permisos), Menú (entradas del manifest de la app).

Permisos necesarios

Administración del tenant / apps.

Notas técnicas

• Backend: backend/src/tenant-runtime/apps/tenant-apps.controller.ts + AppInstallerService. Guard AppRequirementGuard.
• Apps del registry final: utilara-erp (core), ncf-dgii, crm, hr, dental, veterinary. Ver ../apps/README.md.
• Memoria: project_apps_catalog_cleanup.

Estado: Casi listo. El sistema funciona, pero varias tareas de operación son manuales (reinicio del backend, purga de overrides, invalidación de caché del frontend).

Objetivo

Que el administrador/operador sepa qué mantenimiento requiere el ERP y cómo hacerlo con seguridad.

A quién va dirigido

Administrador de empresa avanzado, soporte, operación.

Tareas de mantenimiento

1. Reiniciar el backend (aplicar cambios)

El backend corre desde dist/ y no aplica cambios en caliente. Tras un despliegue o cambio de menú/manifest, hay que reiniciar el proceso. Ver ../tecnico/despliegue.md y ../soporte/comandos-utiles.md.

2. Menú que no cambia

Si editaste manifest.json o la tabla app_menu_tree_overrides y el menú no cambia: hay que reiniciar el backend (los overrides se cargan una vez en el boot). Ver ../tecnico/menu-y-overrides.md.

3. Frontend con versión vieja

Un Service Worker cacheado puede servir código viejo. Validar en Incógnito o usar el kill-switch. Ver ../soporte/errores-comunes.md.

4. Copia de seguridad

Menú Seguridad → Copia de Seguridad → Exportar para exportar datos. Ver también ../tecnico/backups.md.

5. Salud del sistema

Endpoint de health del backend (backend/src/health). Ver ../tecnico/monitoreo.md.

Validaciones importantes

• Antes de reiniciar en horario laboral, avisar a los usuarios (se cae la sesión brevemente).
• No borrar overrides sin entender qué shadowean.

Errores comunes

• Ver ../soporte/errores-comunes.md.

Permisos necesarios

Acceso de administración / operación del servidor (para reinicios).

Notas técnicas

• Ver ../tecnico/systemd.md y ../tecnico/nginx-cloudflare.md.

Estado: Listo. Política de contraseñas aplicada, verificación en dos pasos, sesiones rotativas con detección de reutilización, permisos por campo y por fila, cifrado de datos sensibles y bitácora de actividad.

Este artículo es para quien administra el sistema dentro de la empresa. Explica qué protege la plataforma por defecto y qué depende de tu configuración.

1. Cómo se protegen las cuentas

Contraseñas

Seguridad → Configuración → Configurar Usuarios (/security/config/usuarios)

La política se aplica al crear el usuario y al cambiar la contraseña. Endurecerla no cambia las contraseñas ya existentes: si la endureces, pide un cambio de contraseña al equipo.

Las contraseñas se guardan con hash bcrypt. Nadie —ni el proveedor— puede leerlas.

Verificación en dos pasos (MFA)

Basada en códigos temporales (TOTP), compatible con cualquier app de autenticación estándar.

• El usuario la activa desde su perfil escaneando un QR.
• Se entregan códigos de respaldo una sola vez.
• Para desactivarla hay que presentar un código válido.

Actívala como mínimo en todas las cuentas con perfil Administrador.

Bloqueo por intentos

Si lo activas, tras N intentos fallidos la cuenta queda bloqueada el tiempo configurado. Es la defensa contra el probado sistemático de contraseñas.

2. Sesiones

La detección de reutilización es lo que limita el daño de una credencial robada: en cuanto se usa desde dos sitios, la sesión completa cae.

3. Permisos

El control de acceso tiene tres niveles:

Por acción (RBAC)

Cada perfil concede acciones sobre recursos: cxc:create, accounting:close-period, inventory:view-cost… Se gestionan en Seguridad → Perfiles → Permisos Perfil.

Los permisos se validan en el servidor. Ocultar un botón es solo comodidad; quien manipule la pantalla igualmente recibe un rechazo.

Por campo

Seguridad → (permiso security:manage-field-rbac)

Permite ocultar o proteger campos concretos para determinados perfiles. Útil para datos como salarios o costos.

Por fila

Políticas que limitan qué registros ve cada perfil (por ejemplo, un vendedor solo sus clientes).

4. Cifrado de datos sensibles

Con security:manage-encryption puedes marcar campos como cifrados. El sistema los cifra en la base de datos y admite rotación de llaves. Existe además un mapa de datos que muestra qué información sensible se guarda y dónde.

5. Aislamiento entre empresas

Cada empresa cliente tiene su propia base de datos. No es una separación por filtro en una tabla compartida: son bases distintas. Una consulta de una empresa no puede alcanzar los datos de otra, ni por error de programación ni manipulando identificadores.

Lo mismo aplica a las API Keys: una llave pertenece a una empresa y solo alcanza sus datos.

6. Auditoría

Las sustituciones sensibles —cambiar un precio en el POS, sustituir una retención calculada— quedan registradas con su autor.

7. Buenas prácticas

1. Una cuenta por persona. Las cuentas compartidas destruyen la auditoría: no se sabe

quién hizo qué.

1. Perfiles por función, no por persona. Crea Cajero, Contador, Compras; asigna

personas a esos perfiles.

1. Mínimo privilegio. Empieza restrictivo y añade permisos cuando hagan falta.
2. Separa las acciones críticas. Quien registra no debería ser quien aprueba ni quien

cierra períodos.

1. Al menos dos administradores, nunca uno solo. El sistema impide quedarse sin ninguno,

pero uno solo es un punto único de fallo.

1. Revisa los accesos cada trimestre, y desactiva de inmediato a quien deja la empresa.
2. MFA obligatorio para administradores.
3. Revisa las API Keys: revoca las que llevan meses sin uso.

8. Permisos que conviene restringir

9. Qué hacer si crees que una cuenta fue comprometida

Actúa en este orden:

1. Cierra todas las sesiones de esa cuenta (Cerrar todas las sesiones).
2. Cambia la contraseña.
3. Activa MFA en esa cuenta si no lo tenía.
4. Revisa la bitácora de actividad de los últimos días: busca accesos a horas inusuales o

cambios que el usuario no reconozca.

1. Revisa las API Keys: si la cuenta comprometida pudo crear llaves, revócalas.
2. Revisa los usuarios: confirma que no se creó ninguna cuenta nueva.
3. Si hubo movimientos indebidos, anúlalos (no los borres: la anulación deja rastro).
4. Avisa a soporte con las fechas y horas exactas.

10. Lo que depende de ti

La plataforma aporta los mecanismos; la configuración es tuya:

• [ ] Política de contraseñas endurecida.
• [ ] Bloqueo por intentos activado.
• [ ] MFA en las cuentas administrativas.
• [ ] Perfiles con el mínimo necesario.
• [ ] Sin cuentas compartidas.
• [ ] Bajas procesadas el mismo día.
• [ ] API Keys revisadas.
• [ ] Alguien mira la bitácora de vez en cuando.

Estado: Listo (usuarios, perfiles, permisos manifest-driven; RBAC central).

Objetivo

Que el usuario/administrador entienda cómo se controla el acceso: usuarios, perfiles (roles) y permisos por recurso/acción, incluyendo permisos a nivel de campo/fila en apps tipadas.

A quién va dirigido

Administrador de la empresa (gestión) y usuario final (entender por qué ve o no ve algo).

Cuándo se usa

Al dar de alta usuarios, asignarles perfiles y afinar permisos.

Pantallas (menú Seguridad)

Paso a paso (dar acceso a un usuario)

1. Menú Seguridad → Usuarios → crea el usuario (o invítalo).
2. Menú Seguridad → Perfiles → Permisos Perfil: define qué puede hacer un perfil (por recurso y acción: read/create/update/delete y acciones especiales).
3. Menú Seguridad → Usuario → Perfiles Usuario: asigna el perfil al usuario.

Campos explicados

Validaciones importantes

• Fail-closed: sin permiso, la acción se rechaza (403).
• Instalar una app siembra sus permisos y los otorga al perfil ADMIN (auto-grant idempotente).
• El catálogo de permisos (/permissions/catalog) = núcleo ERP + apps instaladas.

Errores comunes

• "Sin permiso (403)": falta el permiso en el perfil del usuario.
• "No veo un módulo": puede ser permiso o app no instalada.

Resultado esperado

Usuarios con exactamente el acceso que su rol necesita.

Integraciones relacionadas

• Todos los módulos consultan estos permisos.
• Apps instalables aportan sus propios permisos.

Permisos necesarios

Permiso de administración de seguridad/usuarios.

Notas técnicas

• Frontend: SecPerfilPermisosPage. Backend: tenant-runtime/permissions, tenant-runtime/roles. Guard: TenantPermissionGuard.
• Skills: utilara-security-production. Memoria: project_rbac_central_permissions. Ver ../tecnico/rbac.md.