--- audiencia: usuario screen_key: contactos titulo: Contactos aliases: [contacto, contactos, cliente, clientes, proveedor, proveedores, vendedor, vendedores, cobrador, cobradores, supervisor, supervisores, equipo, direccion, dirección, direcciones, zona, lista de precios] --- # Contactos — Guía para el Usuario Esta guía cubre la pantalla **Contactos** del ERP: cómo dar de alta clientes, proveedores y la fuerza de venta y cobranza (vendedores, cobradores, supervisores y equipos), cómo cargar las direcciones y cómo cada uno impacta en facturación, cobros, finanzas y reportes. --- ## ¿Dónde encuentro esto en el menú? - **Contactos**: pantalla principal con varias solapas — **Clientes**, **Proveedores**, **Vendedores y Cobradores** (según permisos), y además **Transportistas / Choferes / Vehículos / Agentes Transporte** si el usuario tiene permiso de remisión (`VEN_NR_NOTA_REMISION_VER`). Esta guía cubre solo las tres primeras. - **Productos → Listas Precios**: ahí se crean/mantienen las listas de precios (no está en Configuración). La lista se **asigna** al cliente desde su propia ficha (Contactos → Clientes → campo "Lista de Precios"). - No existe una pantalla catálogo de "Zonas" ni "Canales" en Configuración. **Zona** es hoy un campo de **texto libre** en la ficha del cliente (ver más abajo), sin catálogo detrás. - **Finanzas → Asignación**: vincula clientes con cobradores en masa (cartera). - **Cobranzas → Cobradores** (tab **Hoja de Ruta**): consume la zona y el cobrador asignado de cada cliente. (Ya no vive en Finanzas — se migró al módulo Cobranzas.) --- ## Solapa: Clientes Listado de clientes con paginación de 20 por página y búsqueda en vivo (por nombre, RUC, documento o email). ### Columnas visibles - **Cliente**: razón social + nombre fantasía. - **RUC / Documento**: RUC-DV o número de documento. - **Contacto**: email y teléfono. - **Tipo** (naturaleza): Contribuyente / No Contribuyente. - **Tipo Cliente**: minorista / mayorista / distribuidor (solo si el módulo Lista de Precios está activo). - **Lista de Precios** (chip). - **Zona**. - **Estado**: Activo / Inactivo. ### Acciones por fila - 👁️ **Ver historial**: drawer lateral con saldos, facturas, recibos, NC y mora del cliente. - ✏️ **Editar**. - 📍 **Direcciones**: gestiona las direcciones del cliente (ver sección Direcciones). - ⚡ **Activar / Desactivar**: soft-delete (el cliente queda inactivo, no se borra). - 🗑️ **Eliminar**: solo si no tiene movimientos. ### Alta / edición de cliente Formulario con dos pestañas: **Datos** y **Direcciones** (la segunda solo aparece en modo edición). #### Pestaña "Datos" — campos **Obligatorios**: - **Naturaleza**: Contribuyente / No Contribuyente. - **RUC + DV** (si es Contribuyente; debe tener 8 dígitos). - **Tipo de Documento** y número (si es No Contribuyente). - **Razón Social**: 4 a 255 caracteres (requisito SIFEN). - **Tipo de Operación SIFEN**: B2B / B2C-B2F / B2G (se filtra según la naturaleza). **Opcionales**: - Email, teléfono, celular, dirección base. - **Nombre Fantasía**: marca comercial o apodo. - **Código cliente**: código interno. - **Tipo Cliente**: minorista / mayorista / distribuidor. - **Lista de Precios** asignada. - **Zona**: texto libre (se usa en Hoja de Ruta y agrupaciones). - **Cobrador asignado**: combobox de cobradores activos. - **¿Es Agente de Retención?**: marca si el cliente nos hace retenciones de IVA o Renta. > El sistema deduce automáticamente el tipo de contribuyente a partir del RUC (RUC < 80.000.000 → persona física; ≥ 80.000.000 → persona jurídica). #### Pestaña "Direcciones" Solo en edición. Lista las direcciones cargadas y permite agregar / editar / eliminar (ver sección Direcciones). ### Cliente "Sin nombre" Existe un cliente especial creado por el sistema llamado **"Sin nombre"** que se usa para ventas rápidas sin identificar al consumidor final. No se puede desactivar, editar ni eliminar. --- ## Solapa: Proveedores Listado simple con búsqueda. Carga local (sin paginación). ### Columnas - Razón Social, RUC / Documento, Contacto (email + teléfono), Ciudad, Estado. ### Acciones - ✏️ Editar, ⚡ Activar / Desactivar, 🗑️ Eliminar. ### Formulario — campos **Obligatorios**: - Naturaleza (Contribuyente / No Contribuyente). - RUC o tipo de documento + número. - Razón Social. **Opcionales**: - Teléfono, celular, email. - Ciudad (combobox). - **Observaciones**: notas internas (ej. "paga a 30 días", "pedidos mínimos 5M Gs"). ### Diferencias con Clientes | Campo | Clientes | Proveedores | |-------|----------|-------------| | Lista de Precios | Sí | No | | Tipo Cliente | Sí | No | | Cobrador asignado | Sí | No | | Direcciones múltiples | Sí | No (campo simple) | | Agente de Retención | Sí | No | | Observaciones internas | No | Sí | --- ## Solapa: Vendedores y Cobradores Sub-divide en **Equipo** (vendedores y cobradores individuales) y **Supervisores** (responsables del equipo). ### Sub-solapa "Equipo" Listado con KPIs arriba: total, activos, desglose por tipo. #### Campos del formulario - **Tipo** (obligatorio): **Vendedor**, **Cobrador** o **Ambos**. - **Nombre** (obligatorio), Apellido. - Código interno, Documento, Teléfono, Email, Dirección. - **Usuario vinculado** (opcional): vincula a un usuario para que pueda loguearse en la app móvil **Novasis Cobros**, ver Hoja de Ruta, etc. - **Zona de Cobranza**. - **Comisión Venta %** y **Comisión Cobranza %**. - **Comisión fija** (monto adicional). - **Meta Mensual** (monto objetivo). #### Columnas listadas Nombre, Código, Documento, Tipo (chip de color), Com. Venta %, Com. Cobranza %, Estado. #### Reglas - Un vendedor / cobrador **no se puede eliminar** si tiene facturas activas asignadas (pendientes o en ruta). - Si se pone Inactivo, deja de aparecer en los combos de "vendedor asignado" / "cobrador" al facturar o cobrar. - Si tiene un **usuario** vinculado, ese usuario puede loguearse en la app móvil **Novasis Cobros** y ver su cartera. (Existe también una pantalla web "Panel Cobrador" en `/cobranzas/panel-cobrador`, pero está **oculta del sidebar** — "deshabilitada temporalmente" — así que hoy el canal real es la app móvil.) ### Sub-solapa "Supervisores" Personas que agrupan a varios vendedores y cobradores bajo su responsabilidad. Las comisiones se calculan **a nivel supervisor** sobre el total del equipo (no se reparten individualmente). #### Campos - Nombre, Apellido, Código, Documento, Teléfono, Email. - **% Comisión Ventas** y **% Comisión Cobros** (sobre lo facturado / cobrado por el equipo). #### Asignación de equipo Desde el detalle de cada supervisor se asignan los miembros del equipo (vendedores y/o cobradores) con un selector múltiple. Se guarda en la tabla intermedia `supervisor_vendedores_cobradores`. #### Impacto - La **comisión del supervisor** se calcula sobre: - Facturas cuya dirección (`cliente_direcciones`) tiene asignado a este supervisor. - O ventas hechas por miembros del equipo. - Cobros realizados por cobradores del equipo (recibos con `cobrador_id` en el equipo). - Aparece en **Finanzas → Comisiones** y se liquida en **Finanzas → Liquidaciones**. --- ## Direcciones del cliente Un cliente puede tener **varias direcciones** (casa, oficina, depósito, sucursales). Se gestionan desde el icono 📍 en el listado. ### Campos por dirección - **Alias**: nombre corto ("Casa Matriz", "Depósito Sur"). - **Dirección** + número. - **Referencia**: orientación al chofer ("3 cuadras al norte de la rotonda"). - **País / Departamento / Distrito / Ciudad** (combos en cascada). - **Es Principal** (⭐): solo una dirección puede ser la principal. - **Vendedor asignado** a esta dirección. - **Cobrador asignado** a esta dirección. - **Supervisor asignado** a esta dirección. ### Para qué se usan - **Facturación**: en la factura se puede elegir qué dirección figura como entrega. - **Hoja de Ruta**: el cobrador toma la dirección con su referencia + celular para visitar. - **Comisiones**: el vendedor / cobrador / supervisor de la dirección es quien gana la comisión de esa operación. - **Distribución / entrega**: picking ordenado por zona y dirección. ### Reglas - Sin límite de direcciones por cliente. - Una dirección queda como **principal** y es la que se usa por defecto. - Si una dirección no tiene cobrador asignado, se usa el cobrador del cliente; si tampoco, queda "sin cobrador" y aparece en Cobranzas → Cobradores → Hoja de Ruta. --- ## Impacto en otros módulos > Esta sección requiere que el ERP tenga activos los módulos de **Ventas**, **Cobranzas**, **Compras** y **Contabilidad** según corresponda (no existen módulos de primer nivel llamados "Facturación" o "Finanzas" en el sidebar — la pantalla de Comisiones/Liquidaciones vive en el ítem de sidebar "Finanzas", pero no es un módulo raíz). Si alguno está apagado, ese impacto no aplica. ### Un Cliente afecta a… | Módulo | Qué impacto tiene | |--------|------------------| | **Facturación** | Se debe seleccionar al facturar. Define lista de precios, condición default y tipo de operación SIFEN. Si es agente de retención, habilita el cálculo de retención. | | **Cobros y Recibos** | Sus facturas pendientes aparecen al cobrar. Sus NC con saldo disponible se pueden aplicar. Sus retenciones recibidas se cargan en el recibo. | | **Cuentas por Cobrar** | Acumula saldo. Aparece en aging (0-30/31-60/61-90/90+) y en Revisión CxC. | | **Hoja de Ruta** | La zona del cliente determina el orden de visita. El cobrador asignado define en qué ruta aparece. | | **App Novasis Cobros** | El cobrador en ruta ve a sus clientes asignados con saldo, promesa de pago y dirección. | | **Solicitud de Crédito** | Cada solicitud se vincula al cliente. El límite de crédito controla el bloqueo al facturar a crédito. Ver `guia-solicitud-credito.md`. | | **Reportes Cobranzas / CxC** | Agrupan datos por cliente. | ### Un Proveedor afecta a… | Módulo | Qué impacto tiene | |--------|------------------| | **Compras** | Selección obligatoria al cargar factura de compra. Define condición de pago. | | **Cuentas por Pagar** | Acumula saldo pendiente. Aparece en aging de CxP. | | **Órdenes de Pago** | Se generan a nombre del proveedor para cancelar facturas vencidas. | | **Marangatu Compras** | El bot importa facturas y vincula al proveedor (lo crea automáticamente si no existe). | ### Un Vendedor afecta a… | Módulo | Qué impacto tiene | |--------|------------------| | **Facturación** | Campo `vendedor_id` obligatorio en la factura. | | **Comisiones de Venta** | Se calculan sobre el total facturado por ese vendedor en el período (`comision_venta %`). | | **Liquidaciones** | Se pagan las comisiones acumuladas. | | **Reportes** | Productividad por vendedor (cantidad, monto, ticket promedio, margen). | | **Direcciones** | Si está asignado a una dirección, gana la comisión de las ventas a esa dirección. | ### Un Cobrador afecta a… | Módulo | Qué impacto tiene | |--------|------------------| | **Asignación de cartera** | Los clientes que tiene asignados forman su cartera. | | **Hoja de Ruta diaria** | El sistema arma la ruta diaria con los clientes del cobrador con saldo pendiente. | | **Cobros / Recibos** | Cada recibo registra el cobrador. | | **Rendiciones** | El cobrador rinde a tesorería lo cobrado (ver `guia-cobros-finanzas.md`). | | **Comisiones de Cobranza** | Se calculan sobre el monto cobrado (`comision_cobranza %`). | | **App Novasis Cobros (mobile)** | El cobrador con usuario asociado puede ver su cartera, registrar visitas, promesas y cobros en ruta. | ### Un Supervisor afecta a… - Se calcula su comisión sobre el total vendido / cobrado por los miembros de su equipo. - Aparece en el **Panel Supervisor** con la vista consolidada del equipo. Se accede vía **Cobranzas → Autorizaciones** (redirige a `Panel Supervisor → tab Descuentos`); el botón directo que existía en el header de Finanzas fue removido en la reorganización de junio 2026. --- ## Validaciones que aplica el backend Mensajes más frecuentes y qué significan: ### Clientes - **"Ya existe un cliente con RUC X: "**: RUC duplicado en la empresa. Buscar el cliente existente en lugar de crear uno nuevo. - **"Ya existe un cliente 'Sin nombre' en esta empresa"**: el sistema solo permite un cliente genérico. - **"El cliente ya existe"**: la persona ya tiene una ficha de cliente (puede estar inactiva). - **"El cliente ya fue eliminado"**: se está operando sobre un cliente marcado como eliminado. - **"No se puede cambiar el estado del cliente de sistema 'Sin nombre'"**: el cliente genérico está protegido. - **"No se puede eliminar el cliente de sistema 'Sin nombre'"**. - **"Cliente no encontrado"**: el ID no existe o pertenece a otra empresa. - **Razón Social** debe tener entre 4 y 255 caracteres (requisito SIFEN). - **RUC** debe tener exactamente 8 dígitos. ### Proveedores - **"El proveedor ya existe"** / **"El proveedor se encuentra inactivo"**. - **"Proveedor no encontrado"**. ### Vendedores / Cobradores - **"No se puede eliminar: tiene asignaciones de facturas activas"**: hay facturas pendientes o en ruta vinculadas. Reasignar antes de eliminar. - **"Vendedor/Cobrador no encontrado"**. ### Supervisores - **"El supervisor no tiene vendedores/cobradores asignados"**: no se puede generar comisión sin equipo. - **"Supervisor no encontrado"**. --- ## Lista de precios aplicada al cliente Resumen práctico de cómo se decide qué precio se carga al facturar (detalle completo en `configuracion-y-listas-de-precios.md` y `explicacion-funcionalidad-lista-precios.md`): 1. Si el cliente tiene una **Lista de Precios** asignada en su ficha → se usa esa. 2. Si no, se busca una lista que aplique a su **zona** o **canal**. 3. Si tampoco hay → se usa la **lista general** o el **precio base** del producto. Cambiar la lista del cliente se hace desde su ficha (campo "Lista de Precios"). El cambio aplica a las facturas futuras; las ya emitidas no se recalculan. --- ## Búsqueda y filtros — buenas prácticas - En el buscador podés escribir RUC, parte del nombre, email o documento. La búsqueda se ejecuta a los 400 ms de tipear (no requiere Enter). - Si la lista da mucho, conviene marcar a los inactivos como Inactivo en lugar de eliminar, y usar el filtro de estado. - El listado de Vendedores y Cobradores se puede filtrar por tipo (Vendedor / Cobrador / Ambos). --- ## Lo que NO se puede hacer - Tener dos clientes con el mismo RUC en la misma empresa. - Tener más de un cliente "Sin nombre". - Eliminar un cliente con facturas / cobros asociados — solo se puede desactivar. - Eliminar un vendedor / cobrador con facturas activas o rendiciones abiertas. - Asignar el mismo supervisor como responsable de dos empresas distintas (cada uno es por empresa). - Cambiar el RUC de un cliente que ya facturó: rompe la trazabilidad SIFEN. Se sugiere crear uno nuevo. --- ## Problemas frecuentes - **"No me aparece el cliente al facturar"**: está Inactivo. Activarlo desde Contactos → Clientes. - **"El sistema dice que el RUC ya existe pero no lo encuentro en la lista"**: probablemente esté Inactivo. Filtrar por estado "Todos" o "Inactivo". - **"La factura no toma el precio que esperaba"**: revisar la lista de precios asignada al cliente y la prioridad de las listas. Ver `explicacion-funcionalidad-lista-precios.md`. - **"El cobrador no ve al cliente en su Hoja de Ruta"**: verificar que tiene cobrador asignado (en la ficha del cliente o en la dirección) y que tiene saldo pendiente o cuotas vencidas. - **"No me deja eliminar al vendedor"**: tiene facturas asociadas. Reasignar primero o desactivar en lugar de eliminar. - **"El cobrador no puede loguearse en la app Novasis Cobros"**: el vendedor / cobrador no tiene un **usuario vinculado**. Editar la ficha y asignar usuario. - **"La comisión del supervisor sale en 0"**: no tiene miembros en el equipo o ninguno facturó / cobró en el período. --- ## Limitaciones actuales - El **filtro por zona/canal** en listas de precios funciona, pero la lógica de **prioridad y fallback** está en evolución (ver `explicacion-funcionalidad-lista-precios.md`). - Las direcciones todavía no tienen geo-referenciación (lat/lng) en producción para Hoja de Ruta — se usa texto + referencia. - Los **proveedores** no manejan múltiples direcciones (campo único). - La **repartición de comisiones** entre miembros del equipo y el supervisor no es proporcional: el supervisor recibe un porcentaje del total del equipo, los miembros reciben su comisión individual. --- ## Documentos relacionados - `guia-facturacion.md` — uso del cliente y vendedor en la factura. - `guia-cobros-finanzas.md` — uso del cobrador, supervisor y equipo en cobros, rendiciones y comisiones. - `guia-apertura-cierre-caja.md` — relación caja ↔ usuario del cobrador. - `guia-solicitud-credito.md` — límite de crédito y cuotas asociadas al cliente. - `configuracion-y-listas-de-precios.md` y `explicacion-funcionalidad-lista-precios.md` — cómo se asigna lista de precios al cliente. - `plan-supervisores-sup01.md` — Panel Supervisor. - `plan-hoja-ruta-cobrador.md` — uso de zona, cobrador y dirección del cliente. - `plan-creditos-cobranzas.md` — flujo completo de créditos y cobranza. - `guia-rubros.md` — si la empresa maneja dos negocios, la lista de proveedores se filtra por rubro.