---
audiencia: usuario
screen_key: conciliacion-contable
titulo: Conciliación Contable
aliases: [conciliacion, conciliación, asientos pendientes, asientos faltantes, regenerar asientos, movimientos sin asiento, pendientes contables, contabilizar retroactivo, contabilidad tardía, activar contabilidad, historico contable, reprocesar asientos, cont_documentos faltantes, integracion contable pendiente]
---

# Conciliación Contable — Guía para el Usuario

Esta guía cubre el módulo **Conciliación Contable**: detección de movimientos operativos (facturas, cobros, gastos, tesorería, OPs, viáticos, liquidaciones, etc.) que **deberían tener asiento contable y no lo tienen**, diagnóstico de la causa (mapeo faltante, período cerrado, cuenta OLD-, etc.) y regeneración masiva de los asientos huérfanos.

---

## ¿Dónde encuentro esto en el menú?

- **Contabilidad → Conciliación** (pestaña dentro del módulo Contabilidad).

Se muestra solo si:
- La empresa tiene el módulo `CONTABILIDAD` activo en su suscripción.
- El usuario tiene el privilegio `CONT_CONC_PENDIENTES_VER`.

---

## Conceptos generales

### ¿Para qué sirve la Conciliación Contable?

Muchas empresas empiezan a usar el ERP sin contratar Contabilidad y luego la contratan más tarde. En ese momento, todo el histórico de facturas, cobros y gastos **existe** pero **no tiene asiento contable**. Otras empresas ya operan con Contabilidad pero por errores de configuración (mapeo faltante, período cerrado, cuenta OLD-) algunos movimientos no se contabilizaron en su momento.

Este módulo:

1. **Detecta** en vivo qué registros operativos no tienen asiento contable confirmado (busca por `origen_tipo` + `origen_id` en `cont_documentos`).
2. **Diagnostica** por qué cada registro no se contabilizó — 6 motivos catalogados.
3. **Regenera** los asientos faltantes en lote invocando los mismos integradores que se usan en tiempo real. Es **idempotente**: registros que ya tienen asiento se saltan automáticamente.
4. **Audita** cada intento (éxito o fallo) en `AuditService` para trazabilidad.

### Diferencia con "Asientos manuales"

| Aspecto | Asientos manuales | Conciliación Contable |
|---------|-------------------|------------------------|
| Origen del asiento | El contador tipea el DEBE/HABER | Se genera automáticamente por el integrador del origen |
| Vinculación con registro origen | Ninguna (o manual) | Automática via `origen_tipo` + `origen_id` |
| Riesgo de duplicar | Alto (el contador debe ser cuidadoso) | Nulo — cada integrador es idempotente |
| Cobertura | Universal (cualquier ajuste) | Solo los registros del registry (facturas, cobros, gastos, etc.) |
| Cuándo usar | Ajustes de fin de mes, provisiones, regularizaciones | Recuperar el histórico contable de la operación |

### Registry de orígenes

El sistema mantiene una tabla catálogo `cont_origen_registry` que declara qué orígenes son contabilizables. Cada entrada apunta a un service integrador (ya existente):

| `origen_tipo` | Descripción | Service |
|---|---|---|
| `factura_cab` | Facturas de venta | `integrarFacturaVenta` |
| `nota_credito_cab` | Notas de crédito de venta | `integrarNotaCredito` |
| `compra_cab` | Facturas de compra | `integrarFacturaCompra` |
| `gasto_cab` | Gastos | `integrarGasto` |
| `recibos_cobro` | Recibos de cobro simples | `integrarCobro` |
| `recibos_multi` | Recibos multi-factura | `integrarReciboMulti` |
| `pagos_proveedor` | Pagos a proveedor | `integrarPago` |
| `orden_pago_proveedor_cab` | Órdenes de pago | `integrarOrdenPago` |
| `tes_movimientos` | Movimientos de tesorería | `integrarMovimientoTesoreria` |
| `rrhh_liquidacion` | Liquidaciones RRHH | `integrarLiquidacionRrhh` |

> Agregar un origen nuevo (viáticos, comisiones, etc.) = agregar una entrada al registry. La UI y la lógica de detección/regeneración lo captan automáticamente.

---

## Configuración previa

### 1. Módulo Contabilidad activo

Sin esto la pantalla no se ve. Configurar en la suscripción de la empresa.

### 2. Mapeo de conceptos

Cada origen requiere mapeos contables específicos:

| Origen | Conceptos que usa |
|---|---|
| Facturas de venta | `VENTAS_10`, `CLIENTES`, `IVA_DEBITO_10` |
| Facturas de compra | `COMPRAS`, `PROVEEDORES`, `IVA_CREDITO_10` |
| Gastos | `GASTOS_GENERALES`, `PROVEEDORES`, `CAJA_GENERAL` |
| Recibos de cobro | `CAJA_GENERAL`, `CLIENTES` |
| Pagos a proveedor | `PROVEEDORES`, `CAJA_GENERAL` |
| Órdenes de pago | `PROVEEDORES`, `CAJA_GENERAL` |
| Movimientos de tesorería | `CAJA_GENERAL`, `BANCO` |
| Liquidaciones RRHH | `SUELDOS_JORNALES`, `SUELDOS_A_PAGAR` |

Si falta alguno, la conciliación reportará el motivo `SIN_MAPEO` y no se generará el asiento hasta que se configure.

### 3. Períodos contables abiertos

Cada asiento va a un período contable. Si la fecha del registro cae en un período cerrado, se reporta `PERIODO_CERRADO`. Solución: reabrir el período o asentar como regularización manual en el período abierto.

---

## Flujo típico paso a paso

### Paso 1 — Abrir la pantalla

**Contabilidad → Conciliación**. Al cargar, el sistema recorre el registry y cuenta pendientes por origen. Los KPIs muestran:

- **Orígenes con pendientes** — cuántos de los orígenes registrados tienen al menos un registro sin asiento.
- **Registros pendientes** — total absoluto.
- **Monto involucrado** — suma en Gs. de todos los pendientes.

### Paso 2 — Aplicar filtros

Filtros disponibles (persisten en URL):
- **Desde / Hasta** — rango de fechas basado en el campo fecha de cada origen (fecha_emision, fecha_pago, etc.).
- Presets: **Este año**, **Ejercicio actual**, **Últimos 90 días**, **Sin rango**.

### Paso 3 — Expandir un origen para ver el detalle

Cada fila del listado tiene una flecha ▼. Al expandir, se cargan los primeros 100 registros pendientes con:
- Fecha
- Número/referencia (según el origen — dnumdoc para ventas, numero_factura para compras/gastos, numero_recibo para cobros, numero_orden_pago para OPs, etc.)
- **Detalle enriquecido** con la contraparte y descripción:
  - Facturas de venta / NC / recibos → razón social del cliente + número completo (est-punto-nro)
  - Facturas de compra / gastos → razón social del proveedor
  - Pagos a proveedor → proveedor + medio de pago
  - Órdenes de pago → proveedor + número de OP
  - Movimientos de tesorería → cuenta (nombre) + tipo (INGRESO/EGRESO) + descripción libre
  - Liquidaciones RRHH → cantidad de empleados + período (MM/AAAA)
  - Viáticos (adelantos/devoluciones) → nombre del empleado + concepto del viaje o tipo
- El **ID interno** queda como tooltip (hover sobre el `#xxxxxxxx`)
- Monto
- **Motivo diagnosticado** (chip con color y tooltip explicativo)

El diagnóstico se hace en lote optimizado: chequea condiciones globales (módulo, mapeos, cuentas OLD-) una vez y por registro solo evalúa la fecha del período.

### Paso 4 — Resolver la causa raíz

Según el motivo:

| Motivo | Acción |
|--------|--------|
| `MODULO_INACTIVO` | Activar módulo Contabilidad en la suscripción |
| `SIN_MAPEO` | Contabilidad → Mapeo de Cuentas → asignar el concepto faltante |
| `PERIODO_CERRADO` | Contabilidad → Ejercicios → reabrir período (o asentar manualmente) |
| `CUENTA_OLD` | Mapeo de Cuentas → reasignar concepto a la cuenta vigente del plan nuevo |
| `DATOS_FALTANTES` | Ir al registro origen (factura, gasto, etc.) y corregir el dato faltante |
| `SIN_MOTIVO` | Ninguna, se puede regenerar directamente |

### Paso 5 — Regenerar

Tres opciones:

**Regenerar todo** (todos los orígenes con pendientes):
- Botón **Regenerar todo** en el header de la pantalla (naranja).
- Modal de confirmación con el total agregado.
- Procesa cada origen en secuencia. Puede tardar minutos.
- Al final se muestra desglose por origen (OK / Fallidos).

**Regenerar por origen** (todos los pendientes de un origen):
- Botón "Regenerar" en la fila del origen.
- Modal de confirmación con cantidad y monto de ese origen.
- Ejecuta hasta 500 registros por batch, secuencialmente, cada uno en su propia transacción.

**Regenerar por fila** (uno solo):
- Icono varita mágica ✨ en la fila del detalle expandido.
- Útil para probar con un caso puntual antes del lote.

### Paso 6 — Revisar resultado

Al terminar el lote se abre un modal con:
- **Total procesado** / **Exitosos** / **Fallidos**
- **Motivos de falla** agrupados con conteo

Los registros exitosos ya tienen su asiento — se pueden ver en **Contabilidad → Asientos** filtrando por fecha o por origen.

### Paso 7 — Exportar

- **Excel** — resumen (Origen, Módulo, Pendientes, Monto).
- **PDF** — reporte apaisado A4 (msv-kude) estilo moderno, con KPIs + tabla. Se abre en modal preview.

---

## Motivos catalogados

| Código | Descripción | Cómo resolver |
|--------|-------------|----------------|
| `MODULO_INACTIVO` | La empresa no tenía módulo Contabilidad activo cuando se creó el registro | Activar Contabilidad + regenerar |
| `SIN_MAPEO` | Falta mapeo de un concepto contable requerido | Contabilidad → Mapeo de Cuentas → asignar concepto |
| `PERIODO_CERRADO` | La fecha del registro cae en un período contable cerrado | Reabrir período o asentar como regularización manual |
| `CUENTA_OLD` | El mapeo apunta a una cuenta con código `OLD-` o inactiva | Reasignar concepto a la cuenta vigente |
| `CATEGORIA_SIN_CUENTA` | En movimientos de tesorería: la categoría del detalle no tiene cuenta contable asignada (ej. "Retiro de Efectivo") | Ir a Configuración → Tesorería y Bancos → Categorías de Movimiento → asignar cuenta a la categoría mencionada |
| `DATOS_FALTANTES` | Falta un dato requerido en el registro (proveedor null, moneda null, etc.) | Corregir el registro origen desde su pantalla |
| `SIN_MOTIVO` | El registro cumple todos los checks pero no se generó (probablemente creado antes de que el hook contable estuviera activo) | Regenerar directamente |

---

## Roles y permisos

Submódulo: **`CONTABILIDAD_CONCILIACION`** (bajo el módulo `CONTABILIDAD`).

| Privilegio | Descripción | Rol típico |
|------------|-------------|------------|
| `CONT_CONC_PENDIENTES_VER` | Ver movimientos sin asiento contable | Contador / Auxiliar / Gerente |
| `CONT_CONC_REGENERAR` | Regenerar asientos pendientes | Contador / Auxiliar |

Al bootear el módulo se ejecuta un seed idempotente (`POST /seguridad/seed-maestro`) que crea el submódulo y los privilegios.

---

## Endpoints (referencia técnica)

Base: `/contabilidad/conciliacion`. Todos requieren `AuthGuard('jwt') + ModuleGuard + PermissionGuard` con `@RequireModule('CONTABILIDAD')`.

| Método | Path | Privilegio |
|--------|------|-----------|
| GET | `/registry` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/estado` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/resumen` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/resumen/pdf` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/detalle/:origenTipo` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/motivos` | `CONT_CONC_PENDIENTES_VER` |
| GET | `/diagnostico/:origenTipo/:id` | `CONT_CONC_PENDIENTES_VER` |
| POST | `/diagnostico-lote/:origenTipo` | `CONT_CONC_PENDIENTES_VER` |
| POST | `/regenerar/:origenTipo/:id` | `CONT_CONC_REGENERAR` |
| POST | `/regenerar/:origenTipo` | `CONT_CONC_REGENERAR` |
| POST | `/regenerar-todo` | `CONT_CONC_REGENERAR` |
| POST | `/re-seed-registry` | `CONT_CONC_REGENERAR` |

---

## Validaciones del backend

- **"Origen \"X\" no está registrado o está inactivo"** — el `origen_tipo` no existe en `cont_origen_registry`.
- **"Tabla X no accesible"** — el service intenta acceder a una tabla que no existe en el cliente Prisma. Suele indicar que se agregó un origen sin correr `prisma generate`.
- **"Service X no disponible en el runtime"** — el service declarado en el registry no está registrado en el ModuleRef. Verificar que el módulo esté importado en el árbol de dependencias.
- **"Método X no encontrado en Y"** — el método declarado en el registry no existe (renombrado o typo).
- **403 Forbidden** — el usuario no tiene el privilegio requerido.

---

## Problemas frecuentes

- **"Regeneré todo y sigue apareciendo como pendiente"** → el integrador se ejecutó pero no creó `cont_documentos` (retornó null porque falla un check interno). Verificar en `AuditService` el evento `CONT_CONC_REGENERAR_FALLA` para el motivo. Suele ser mapeo o dato faltante.

- **"El botón Regenerar no aparece"** → el usuario no tiene `CONT_CONC_REGENERAR`. Asignar el privilegio al perfil.

- **"Todos los registros aparecen con SIN_MAPEO"** → el mapeo del concepto declarado como requerido no está configurado. Ir a Contabilidad → Mapeo de Cuentas.

- **"El resumen tarda mucho en cargar"** → hay muchos registros. Filtrar por rango de fechas más chico (mes por mes) para acelerar. La detección es en vivo, sin cache.

- **"Regenerar en lote falla con 'límite excedido'"** → hay más de 500 pendientes. Filtrar por rango más chico y correr varias veces.

- **"Agregué un origen nuevo al registry pero no aparece en la UI"** → llamar a `POST /contabilidad/conciliacion/re-seed-registry` o reiniciar el backend. El seed corre solo en `onModuleInit`.

- **"Regenerar todo tarda mucho"** → filtrar por rango de fechas más chico (ej. un mes por vez) o usar el botón "Regenerar" a nivel origen para procesar de a uno.

- **"El botón PDF no funciona"** → verificar que `msv-kude` esté corriendo y que `envs.apiGeneradorPDF` apunte correctamente.

---

## Lo que NO se puede hacer

- Regenerar asientos de orígenes que no están en el registry (agregar entrada nueva primero).
- Editar asientos existentes desde esta pantalla (usar la pantalla estándar de Asientos).
- Regenerar más de 500 registros por batch (refinar el filtro).
- Cambiar el mapeo automáticamente (el sistema detecta pero no corrige).
- Contabilizar transacciones futuras — solo los registros ya existentes en las tablas.

---

## Limitaciones actuales

- **Regeneración serial**: procesa un registro a la vez para no golpear la BD. Batches de 500 tardan varios segundos.
- **Sin scheduler**: no hay un job que corra la regeneración automáticamente en la noche. Es una acción del contador.
- **Sin diff visual**: no muestra "qué asiento se va a crear" antes de regenerar. Confía en el integrador.
- **Registry cerrado por seed**: la UI no permite agregar orígenes al registry (se hace en código).
- **Un solo nivel de origen**: no maneja "un registro depende de otro" (ej. una NC de venta que necesita que la factura original esté asentada primero).

---

## Documentos relacionados

- `guia-contabilidad.md` — mapeos de cuentas, asientos, períodos, ejercicios.
- `guia-facturacion.md` — cómo se contabiliza una factura de venta.
- `guia-gastos.md` — cómo se contabiliza un gasto.
- `guia-cobros-finanzas.md` — cómo se contabiliza un cobro.
- `guia-rendicion-viaticos.md` — módulo de viáticos (integrador propio, se agrega al registry en fase 4).
- `docs/plan-conciliacion-contable.md` (interno, backend) — plan de implementación técnico y fases del módulo.