Conciliacion Service

ConciliacionService es el servicio con mayor densidad de reglas del dominio Finanzas. Vincula movimientos bancarios con documentos del sistema, resuelve diferencias, aplica anticipos, marca incobrables y emite eventos post-COMMIT.

Flujo Principal

flowchart TB
  IN["vincular(ctx, dto)"]
  MOV["findMovimientoById"]
  CAT["categoria_movimiento_id actual"]
  ANT{"categoria = ANTICIPO-PROV<br/>y movimiento CARGO?"}
  AV["aplicarAnticipoProveedorDesdeConciliacion"]
  DISP["calcular monto disponible"]
  DOCS["validar documentos<br/>COMPRA_VENTA / DECLARACION / HONORARIO"]
  AUTO["resolver categoria automatica"]
  TX["withTransaction"]
  INS["insertVinculos"]
  UPD["actualizar estados de documentos<br/>y movimiento"]
  EVT["queue conciliacion:matched<br/>queue movimiento:vinculado si aplica"]

  IN --> MOV --> CAT --> ANT
  ANT -- si --> AV
  ANT -- no --> DISP --> DOCS --> AUTO --> TX --> INS --> UPD --> EVT

Métodos

Método	Uso
solicitarMatch(tenantDb, compraId)	Busca candidatos para una compra contabilizada; si existe exactamente un candidato, llama vincular.
vincular(ctx, dto)	Vincula movimiento bancario con documentos de sistema y actualiza estados.
conciliarManual(ctx, dto)	Cierra un movimiento con categoría contable sin documento externo.
desconciliar(ctx, movimientoId)	Elimina conciliaciones de un movimiento y emite conciliacion:desconciliada.
getResumen(ctx, bancoId, anio, mes, acumulado)	Devuelve resumen enriquecido de conciliación.
marcarIncobrable(ctx, conciliacionId)	Marca diferencias de ventas o boletas como incobrables.
castigarContraEstimacion(ctx, conciliacionId, dto)	Contabiliza castigo contra estimación de incobrables.
reversarCastigoContraEstimacion(ctx, conciliacionId, dto)	Reversa el castigo previamente contabilizado.
compensarProveedorDesdeConciliacion	Compensa una diferencia de cliente contra factura de proveedor desde una conciliación específica.
compensarProveedorMultipleDesdeDocumento	Distribuye compensación contra varias facturas proveedor desde un documento cliente.
reversarCompensacionProveedor	Elimina una resolución de compensación y recalcula coberturas.

Contrapartidas Soportadas

Tipo	Origen	Validación principal	Efecto
COMPRA_VENTA	operaciones_sii.compras_ventas_detalle	Documento contabilizado.	Marca pagado y actualiza conciliación.
DECLARACION	declaraciones.declaraciones_f29	F29 no anulado y con total a pagar.	Registra fecha_pago.
HONORARIO	remuneraciones.honorarios	Honorario contabilizado.	Cambia a PAGADA.
MANUAL	Movimiento bancario	Categoría contable asignada y sin conciliaciones parciales.	Cierra el movimiento.

Categoría Automática

Código	Condición
PAGO-IMP	Solo documentos DECLARACION.
PAGO-HON	Solo documentos HONORARIO.
PAGO-PROV	Documento comercial identificado como compra/proveedor.
COBRO-CLTE	Documento comercial identificado como venta o boleta.
ANTICIPO-PROV	Movimiento CARGO ya categorizado como anticipo proveedor.

Incobrables

El servicio usa cuentas explícitas para castigo contra estimación:

Constante	Cuenta
CLIENTES_ACCOUNT_CODE	1104001
ESTIMACION_INCOBRABLES_ACCOUNT_CODE	1104002
INCOBRABLE_EXPENSE_ACCOUNT_CODE	3502003

Alcance de incobrables

La marca de incobrable y el castigo contra estimación aplican sobre documentos de cliente, no sobre facturas de proveedor. Las validaciones fallan antes de abrir la transacción si el documento no corresponde.

Eventos

Evento	Trigger
conciliacion:matched	Vinculación exitosa contra documentos comerciales.
movimiento:vinculado	Asignación automática de categoría a un movimiento sin categoría previa.
conciliacion:desconciliada	Desconciliación de movimiento bancario.

Listener de Compra Contabilizada

listeners.ts registra un listener sobre compra:contabilizada. Si formaPago es transferencia o cheque, llama ConciliacionService.solicitarMatch. Otras formas de pago no solicitan match automático.

Endpoints

Método	Ruta	Service call
POST	/api/financieros/conciliacion/vincular	vincular(ctx, body)
POST	/api/financieros/conciliacion/manual	conciliarManual(ctx, body)
GET	/api/financieros/conciliacion/resumen	getResumen(ctx, bancoId, anio, mes, acumulado)
DELETE	/api/financieros/conciliacion/movimiento/:id	desconciliar(ctx, id)
PUT	/api/financieros/conciliacion/:id/incobrable	marcarIncobrable(ctx, id)
POST	/api/financieros/conciliacion/:id/castigo-estimacion	castigarContraEstimacion(ctx, id, body)
PUT	/api/financieros/conciliacion/:id/castigo-estimacion/reversar	reversarCastigoContraEstimacion(ctx, id, body)
POST	/api/financieros/conciliacion/:id/compensacion-proveedor	compensarProveedorDesdeConciliacion(ctx, id, body)
POST	/api/financieros/conciliacion/documento/:id/compensaciones-proveedor	compensarProveedorMultipleDesdeDocumento(ctx, id, body)
DELETE	/api/financieros/conciliacion/compensacion-proveedor/:id	reversarCompensacionProveedor(ctx, id)