Clientes AY-029

Visión general

El módulo de Clientes administra el directorio de personas y empresas a quienes se les factura. Se compone de los siguientes módulos y campos:

Catálogo de Clientes CL-001Permiso 048

Listado paginado de todos los clientes de la empresa. Desde aquí se accede a crear, editar y consultar datos completos.

Columnas del listado

• Código — Identificador interno
• Cédula — Física, jurídica, DIMEX o NITE
• Nombre / Nombre comercial
• Teléfono, Email
• Tipo — Clasificación comercial
• Zona — Zona geográfica
• Saldo CxC — Saldo pendiente total
• Estado — Activo / Inactivo

Filtros

• Buscar por nombre, cédula, código, email o teléfono
• Filtrar por tipo, zona, agente, estado
• Solo clientes con saldo CxC pendiente

Crear / Editar Cliente

El formulario de cliente tiene varias secciones agrupadas por función.

Datos básicos (obligatorios)

• Tipo de identificación — Física, jurídica, DIMEX, NITE, extranjero sin ID
• Cédula — Sin guiones, con longitud según tipo
• Nombre — Aparece en la factura electrónica
• Email — Para enviar facturas (puede haber varios separados por coma)

Datos comerciales

• Nombre comercial — Alias de presentación
• Agente asignado — Vendedor responsable del cliente
• Tipo de cliente — Clasificación de texto libre con sugerencias: escriba uno nuevo o elija uno ya usado (ver sección Tipos)
• Zona — Ubicación geográfica de texto libre con sugerencias: escriba una nueva o elija una existente (ver sección Zonas)
• Nivel de precio — Lista de precios que aplica (P1..P10)
• Descuento automático — % que se aplica por defecto en cada factura

Datos de contacto

• Persona de contacto, teléfonos
• Emails (general, de factura y de cobro; pueden ser varios separados por coma)
• Link de pedido — Genere o copie el link para que el cliente haga pedidos en línea

Ubicación y GPS Nuevo

La pestaña Ubicación reúne todo lo geográfico del cliente:

• Dirección — Dirección exacta y señas.
• División territorial — Provincia, cantón, distrito y barrio, con un asistente para elegirlos paso a paso.
• Mapa interactivo (GPS) — Tocá el mapa para fijar la ubicación del cliente, arrastrá el marcador para afinar, o usá Detectar para tomar tu ubicación actual (útil para rutas de entrega). También podés pegar las coordenadas a mano o abrirlas en Google Maps.

Crédito y saldos Nuevo

En la pestaña Crédito, además del límite, plazo, interés y cuenta principal, ahora se ve el estado de cuenta del cliente: monto pendiente, vencido y por vencer con su cantidad de documentos. Con el permiso correspondiente aparece el botón Autorizar Crédito para permitir un sobregiro puntual.

Actividades económicas

Se pueden asignar múltiples actividades económicas según la matrícula que el cliente tenga ante Hacienda. Buscá una actividad en el catálogo, o traé las del cliente directamente desde Hacienda por su cédula. Al facturar, se elige la actividad correspondiente al tipo de bien o servicio.

Exoneración de IVA

Clientes con autorización para comprar sin IVA (ZF, misión diplomática, orden de exoneración DGT, etc.) se configuran en la pestaña de exoneración.

Campos

• Tipo de exoneración — 01 DGT, 02 ZF, 03 Diplomático, etc.
• Número de documento — Orden de exoneración
• Institución que emite — Combo con los 13 códigos enumerados oficialmente por Hacienda (ver tabla abajo). Al elegir, el código y nombre quedan visibles en el desplegable.
• Fecha de emisión y vencimiento
• Porcentaje de exoneración — Usualmente 13% (tarifa general)
• Lista de CABYS autorizados — Opcional, solo los códigos específicos que se pueden exonerar

Instituciones que emiten exoneración

El XML de Hacienda exige un código enumerado en el nodo <NombreInstitucion>; texto libre es rechazado con cvc-enumeration-valid. Por eso el campo es un combo cerrado (no editable) que toma su catálogo de la tabla TipoInstucionEmitioExoneracion:

Múltiples exoneraciones por cliente

Un mismo cliente puede tener varias autorizaciones de exoneración (por ejemplo: AL-13330 para materiales de construcción, AL-13332 para equipos eléctricos, AL-14154 para un CABYS específico). Cada autorización tiene su propia lista de CABYS en la pestaña CABYS autorizados.

Al facturar, el sistema asigna por línea la autorización correcta según el CABYS del artículo, en este orden de prioridad:

1. La marcada como Default (si cubre el CABYS de la línea).
2. Las demás, ordenadas por FechaVencimiento descendente.

Si ninguna autorización cubre el CABYS de una línea, esa línea sale gravada en la factura (no exonerada). Antes el sistema aplicaba siempre la default a todas las líneas, lo que generaba rechazos -401 "código de producto no se encuentra registrado en la autorización".

Documentos por LEY (tipos 03 y 08)

Cuando la exoneración cita un artículo de ley — TipoDocumentoEX1 = 08 (LEY, ej. LEY 9503) o TipoDocumentoEX1 = 03 (Autorizado por ley especial, ej. el decreto del MAG) — Hacienda exige que el XML contenga el campo <Inciso>. Si la ley no tiene inciso aplicable, debe enviarse 0. El sistema lo asegura automáticamente — pero el dato del inciso por cliente debe estar guardado en su pestaña de exoneración. Si falta, Hacienda rechaza con -479 "el Articulo de ley hace referencia a un Inciso, debe indicar el número del inciso".

Exoneración del MAG Nuevo

Los productores agropecuarios registrados ante el MAG compran insumos con una tarifa reducida del 1% de IVA en lugar del 13%, según el decreto 41824-H-MAG. En el sistema eso se representa como una exoneración del 12% (13% − 12% = 1%).

Cuando el sistema consulta el padrón del MAG, la exoneración del cliente se guarda completa y lista para facturar:

• Tipo de documento — 03 Autorizado por ley especial
• Número de documento — 41824-H-MAG (el decreto)
• Institución — 03 Ministerio de Agricultura y Ganadería
• % Exoneración — 12 · Artículo 1 · Inciso 0

Al elegir la institución 03 - Ministerio de Agricultura y Ganadería en la ficha del cliente, el sistema rellena solo el tipo, el decreto, el artículo, el inciso y el 12%. Solo completa los campos vacíos: si ya escribiste algo, no se pisa.

Editar las exoneraciones de un cliente Nuevo

En la pestaña Exonerar de la ficha del cliente se listan todas sus exoneraciones, cada una con su número interno, su origen (MAG o MANUAL), si está Vigente o Vencida, el porcentaje y la fecha de vencimiento.

• Tocá una para ver y editar sus datos en el formulario de abajo.
• Basurero — Cada exoneración se borra desde su propio ícono, sin afectar a las demás.
• Nueva exoneración — Limpia el formulario para agregar otra al mismo cliente.

Clientes Exonerados CL-020

Página de solo consulta (en Clientes → Catálogos) que muestra de un vistazo todos los clientes que tienen exoneración, sin entrar cliente por cliente.

Cómo funciona

• Lista (izquierda) — Cada cliente con exoneración: código, nombre, cédula y cuántas exoneraciones tiene.
• Detalle (derecha) — Al tocar un cliente se muestran sus exoneraciones: número de documento, tipo, institución, porcentaje, fechas de emisión y vencimiento, y CABYS autorizados.
• Estado — Cada exoneración indica si está Vigente o Vencida (según la fecha de vencimiento) y cuál es la predeterminada.
• Buscador — Filtra la lista al instante por código o nombre.

Crédito

Si el cliente compra a crédito, en la ficha se configuran los parámetros:

• Límite de crédito — Monto máximo autorizado
• Plazo de crédito — Días hasta el vencimiento
• Cuenta de saldo a favor — Se genera automáticamente al crear el cliente

Estos datos se muestran en el panel de Facturación Desktop al seleccionar el cliente. Si el saldo pendiente excede el límite, el sistema avisa al vendedor antes de procesar una factura a crédito.

Zonas

Las zonas son clasificaciones geográficas internas útiles para:

• Reportes de ventas por territorio (ver VE-019)
• Planificar rutas de entrega (boletillas / delivery)
• Asignar agentes por zona geográfica

Ejemplos de zonas

"Norte", "Sur", "GAM", "Fuera de GAM", "San José Centro", "Cartago", "Alajuela Ruta 1", etc. El administrador las define según la operación del negocio.

Cómo se asigna la zona

La zona se escribe directamente en la ficha del cliente (sección Datos comerciales). El campo es de texto libre con sugerencias: al escribir o tocarlo, aparece la lista de las zonas que ya usan otros clientes para elegir una existente, o puede escribir una zona nueva y queda disponible automáticamente para los siguientes clientes.

Mantenimiento: renombrar o unificar zonas

Si quedaron nombres repetidos o con errores de tipeo (ej. "GAM" y "G.A.M.", o un código viejo como "SJ" en vez de "San José"), use el módulo Clientes → Zonas y Tipos. Ahí ve la lista de todas las zonas con la cantidad de clientes que tiene cada una y puede:

• Renombrar una zona: al cambiar el nombre, todos los clientes con esa zona se actualizan de una sola vez.
• Unificar dos zonas: si escribe un nombre que ya existe, las dos se juntan en una sola (el sistema le avisa antes).

Tipos de Cliente

Los tipos de cliente son clasificaciones comerciales que agrupan clientes con comportamiento similar:

Ejemplos típicos

• Mayorista — Compras grandes, usa precio P2
• Detalle — Consumidor final, usa precio P1
• VIP — Cliente preferencial, 10% descuento automático
• Institucional — Gobierno, ONG, paga a 60 días
• Empleado — Empleados con beneficios internos

Para qué sirve

• Reportes de ventas agrupados por tipo
• Políticas comerciales diferenciadas
• Aplicar descuentos o precios base según el tipo

Cómo se asigna el tipo

Igual que la zona, el tipo de cliente se escribe directamente en la ficha del cliente (sección Datos comerciales), en un campo de texto libre con sugerencias: elija uno existente de la lista o escriba uno nuevo. La lista se forma con lo que se usa en las fichas.

Mantenimiento: renombrar o unificar tipos

Para corregir o juntar tipos repetidos use el módulo Clientes → Zonas y Tipos (la columna de la derecha). Funciona igual que con las zonas: ve cada tipo con su cantidad de clientes, lo renombra (se actualizan todos los clientes con ese tipo) o lo unifica con otro escribiendo un nombre que ya existe. Requiere el permiso 313 – Editar clientes.

Bitácoras de Clientes CL-010

Registro histórico de cambios realizados en las fichas de los clientes. Cada modificación se guarda con usuario, fecha y detalle de qué cambió.

¿Qué se registra?

• Creación de cliente nuevo
• Cambios en datos básicos (nombre, cédula, email)
• Cambios en límite y plazo de crédito
• Activación / inactivación del cliente
• Cambios en exoneración
• Cambios de agente asignado

Columnas

Filtros

• Por rango de fechas
• Por usuario
• Por cliente específico
• Por tipo de acción

Notificar Clientes CL-012

Envío masivo de correos electrónicos a clientes seleccionados por zona, tipo de cliente o búsqueda por nombre. Permite redactar el mensaje a mano, usar plantillas rápidas, cargar plantillas HTML externas o generar contenido con Inteligencia Artificial.

Para qué sirve

• Comunicar promociones, ofertas o campañas de temporada
• Informar cambios de horario, apertura de nuevas sucursales o novedades
• Enviar términos y condiciones actualizados
• Agradecimientos masivos de fin de año
• Distribuir manuales o documentación en HTML

Panel izquierdo — Seleccionar Destinatarios

• Zonas — checkboxes múltiples. Sin selección = todas las zonas
• Tipos de Cliente — checkboxes múltiples. Sin selección = todos los tipos
• Buscar por Nombre — LIKE contiene en el nombre del cliente
• ☑ Solo clientes con email válido — activado por defecto; filtra emails vacíos o sin @
• Botón Buscar Clientes carga la lista. Con Seleccionar todos se marcan/desmarcan todos los resultados.

Panel derecho — Redactar Mensaje

Plantillas Rápidas

Cuatro plantillas predefinidas que llenan automáticamente Asunto y Mensaje:

• Promoción — ofertas especiales de temporada
• Noticias — novedades de la empresa
• Términos — actualización de términos y condiciones
• Agradecimiento — agradecer preferencia del cliente

Asunto

Campo obligatorio. Se muestra en la línea de asunto del correo que recibe el cliente.

Plantilla HTML externa (opcional)

Si tiene un archivo HTML completo (manual, catálogo, documentación bonita) puede usarlo como cuerpo del correo reemplazando el mensaje libre:

• Select con todas las plantillas disponibles en /documentacion/manuales/
• Cargar — carga el HTML seleccionado al formulario (se envía tal cual, sin envolverlo)
• Ver — previsualiza el HTML en una pestaña nueva
• Subir HTML — sube un archivo .html o .htm nuevo al servidor. Se guarda en /documentacion/manuales/; si ya existe un archivo con el mismo nombre se le agrega sufijo timestamp

Mensaje (con IA)

Textarea con HTML permitido (<h2>, <p>, <ul>, <strong>, etc.). Arriba del textarea hay un campo de instrucción para generar contenido con IA:

1. Escribir una instrucción en lenguaje natural. Ej: "Redacta un correo informando sobre nuevas promociones de fin de año"
2. Click en el botón IA
3. El sistema busca contexto relacionado en las memorias del sistema y documentación interna según palabras clave (planilla, factura, inventario, cliente, hacienda, etc.) y lo envía a la API de Claude
4. La IA genera el HTML y lo pone automáticamente en el textarea de mensaje

Imágenes adjuntas

Se pueden adjuntar imágenes al correo de 3 formas:

• Pegar (Ctrl+V) — click en la zona de pegado y pegar desde el portapapeles
• Arrastrar — arrastrar imágenes desde el explorador de archivos hasta la zona
• Seleccionar archivos — botón + Agregar abre el explorador para elegir múltiples imágenes

Formatos aceptados: JPEG, PNG, GIF, WebP. Tamaño máximo: 5 MB por imagen. Se guardan en /uploads/notificaciones/ y se adjuntan al correo.

Envío

El botón verde Enviar Notificación pregunta confirmación ("Enviar notificación a N cliente(s)?") y procesa el envío uno por uno. Al finalizar muestra el total enviado y una lista de errores si alguno falló (email inválido, servidor SMTP caído, etc.).

Bitácora

Cada envío masivo queda registrado en la bitácora del sistema con el asunto y la cantidad de destinatarios exitosos.

Interfaz

Migrado al estándar visual Banking Bold (2026-04-22) — monocromático azul corporativo #0047AB, tipografía Inter + Roboto Mono, sin bordes redondeados, labels negras en mayúsculas.

Catálogo de Productos CL-011Permiso 053

Vista visual del catálogo de productos para que el agente se lo muestre al cliente. Tarjetas con imagen, nombre, detalle interno, stock y precio opcional. Se puede compartir por WhatsApp o Email mediante un enlace público con token.

Para qué sirve

• Agente visita al cliente y le muestra el catálogo con imágenes en tablet/celular
• Enviar link al cliente para que revise la oferta antes de una visita
• Catálogo digital actualizado (no se imprime, siempre refleja stock y precios actuales)

Filtros en la cabecera

• Buscar — por nombre, código o código de barras (debounce 350ms; al buscar se deselecciona automáticamente la categoría para ver todas)
• Lista de Precios — P1 a P10
• Ordenar por — Nombre A→Z, Código, Precio ↑, Precio ↓
• ☑ Solo con stock — oculta productos sin existencias
• ☑ Mostrar precio — toggle para ocultar/mostrar precios en las tarjetas

Sidebar de categorías

• Muestra todas las categorías activas con conteo de productos
• Al hacer click en una categoría con subcategorías, se despliega como acordeón
• Las subcategorías vienen recogidas por default — solo se abren al tocar la categoría padre
• En móvil/tablet el sidebar se convierte en un botón "Filtrar por categoría" colapsable

Tarjeta de producto

• Imagen cuadrada con fallback a placeholder si no hay foto
• Chip de stock verde/rojo (solo en admin; oculto en el catálogo público)
• Código en mono, Nombre, y Precio con IVA incluido + % entre paréntesis. Ej: ₡1,234.56 (13% IVA)

Modal detalle de producto

Al hacer click en una tarjeta se abre un modal con:

• Carrusel de imágenes — hasta varias imágenes por artículo (de la tabla ArticuloImagenes). Navegación con flechas ← → o thumbnails
• Nombre grande (h2)
• Detalle Interno — campo DetalleInterno en cuadro destacado
• Código, Categoría/Subcategoría, Stock chip
• Precio grande con IVA incluido y porcentaje

Compartir catálogo — Link público

Botón verde "Compartir" en la cabecera abre un modal con 2 pasos:

1. Configuración del token:
   • Título (opcional, lo verá el cliente)
   • Duración (7 / 30 / 90 / 365 días o sin expiración)
   • Lista de Precios a congelar
   • ☑ Mostrar precio al cliente (si se desmarca, el cliente no puede activarlo)
   • ☑ Solo productos con stock
   • Mensaje opcional para acompañar el envío
2. Enlace generado:
   • Input con URL única (formato ?t=serverdb.token)
   • Botón WhatsApp — abre wa.me con texto precompilado
   • Botón Email — abre el cliente de correo (mailto)
   • Invitar por Email directo — escribir email del cliente y el sistema envía correo HTML con botón "Ver Catálogo"
   • Botón Copiar el enlace al portapapeles

Banner de enlace activo

Tras generar un enlace, aparece un banner verde en la parte superior con la URL + botones rápidos (Copiar / WhatsApp / Email / Descartar). Se guarda en el navegador y queda visible al recargar la página hasta que se descarta.

Vista del cliente (pública)

URL: /modulos/clientes/catalogo_productos/catalogo_publico.php?t=<serverdb>.<token>

• Sin login — acceso solo por token
• Los ajustes del token quedan congelados: el cliente no puede activar precios si el agente los ocultó
• Sin indicadores de stock — el cliente no ve si hay o no existencias (evita desmotivar la compra)
• Responsive: desktop con sidebar, tablet/móvil con sidebar colapsable y grid de 2+ columnas
• Cada carga incrementa el contador Vistas y actualiza UltimaVista
• Meta noindex, nofollow — no aparece en buscadores

Base de datos

Tabla CatalogoProductosToken en cada empresa (migración #20260420234033): guarda Token, ServerDB implícito, FechaExpira, MostrarPrecio, ListaPrecio, SoloStock, Categoría, Titulo, Mensaje, Vistas, UltimaVista, Activo.

Pedido en Línea PE-001

Catálogo interactivo público donde el cliente entra desde su celular o computadora con un link único, ve los productos con imágenes, agrega al carrito, ajusta cantidades y confirma el pedido. No requiere login. El pedido llega al sistema FactuPOS de la empresa para que un agente lo facture o procese.

Cómo se genera el link

1. Abrir el cliente en CL-001 Catálogo de Clientes (botón Editar) o desde el modal de cliente en cualquier módulo de ventas.
2. Botón Link Pedido → Generar link de pedido.
3. El sistema crea un token único de 64 caracteres y devuelve la URL de la Tienda en Línea con acceso automático: https://soportereal.com/ecommerce/<empresa>?t=<token>
4. Copiar el link o usar el botón Enviar por WhatsApp para mandárselo al cliente directo a su celular.

Qué ve el cliente

• Header con el nombre de la empresa y nombre del cliente saludando
• Sidebar de categorías con conteo de productos por categoría
• Búsqueda por nombre, código o detalle interno (debounce 400ms)
• Cuadrícula de productos con imagen, nombre, categoría, precio y stock
• Botón "Agregar" en cada producto que mete 1 unidad al carrito
• Modal detalle al tocar el producto: carrusel con todas las imágenes, descripción, cantidad ajustable, agregar
• Carrito flotante con badge de cantidad total
• Confirmación con notas: el cliente puede dejar instrucciones (horario de entrega, etc.) antes de enviar

Listas de precios y descuentos

El precio que ve el cliente respeta su configuración fiscal en CL-001:

• Tipo de Precio (1-10) del cliente → se aplica la lista correspondiente (parámetro 275 decide si usa la versión 1 o 2 de las vistas de precios)
• Descuento del cliente → se aplica automáticamente sobre el precio, mostrando el original tachado

Modal detalle (carrusel)

• Galería: imagen principal grande + flechas + miniaturas + contador 1 / 3
• Navegación con teclado: ← → entre imágenes, Esc para cerrar
• Cantidad: − / input / + (respeta Fraccionamiento del artículo: si está activo permite decimales tipo 1.5 kg)
• Descripción: muestra el campo DetalleInterno del artículo en una card destacada
• Badge "+N imágenes" en la card de la cuadrícula si el producto tiene varias imágenes

Imágenes

Las imágenes se cargan desde la tabla ArticuloImagenes (campo ImagenNombre ordenado por Orden). Solo aparecen las que tienen archivo físico real en /img/<empresa>/articulos/: si la imagen está registrada en BD pero el archivo no existe, se muestra el placeholder de caja () en lugar de un 404.

Filtro de productos visibles

Solo se muestran al cliente los artículos con:

• MostrarEnWeb = 1 — checkbox "Mostrar en web" en IN-002
• ArticuloEstadoCodigo = 1 — Estado activo

Vista móvil compactada

En pantallas ≤ 600px el grid pasa a 3 columnas con cards muy compactas (categoría y stock ocultos en la card; visibles al abrir el modal detalle). En pantallas ≤ 360px se reduce aún más la tipografía. El botón "Agregar" en mobile muestra solo el ícono .

Estilo visual

El catálogo usa estilo SLDS (Salesforce Lightning Design System): header blanco con borde inferior, brand azul #0176d3, tipografía Salesforce Sans, radius conservador (4-8px), sombras planas, lozenges (badges pill) con borde fuerte para stock. Todos los tokens están en --slds-* dentro de /pedido/css/pedido.css.

Base de datos

• ClienteTokenPedido en cada empresa: Token (64 hex), ClienteCodigo, Estado, FechaCreacion, FechaExpiracion, UltimoAcceso
• token_lookup en dbcontrol: índice cross-empresa con ServerIP, ServerDB, ClienteCodigo para que la URL pública resuelva a la BD correcta sin saber a priori a qué empresa pertenece

APIs públicas (sin auth)

Control de Visitas CL-013Permisos 671/672/673

Registro de visitas a clientes con motivo, detalle de los trabajos realizados, fotos de respaldo, ubicación GPS y estado de la atención. Diseñado mobile-first para que los técnicos y agentes de campo lo usen desde el celular durante la visita y luego se consulte desde escritorio.

Para qué sirve

• Llevar bitácora de visitas de soporte técnico, mantenimiento, capacitación o entregas
• Registrar trabajos realizados con evidencia fotográfica
• Geolocalizar la visita (GPS desde el móvil) para validar asistencia y mantener historial de ubicaciones
• Dar seguimiento a casos abiertos (Pendiente / En proceso / Resuelto / Cancelado)
• Auditar visitas por cliente, por fecha, por motivo o por usuario

Lista de visitas

Listado paginado con filtros combinables:

• Código de cliente exacto
• Nombre de cliente contiene (LIKE)
• Motivo contiene (texto libre, sin catálogo)
• Estado — Todos / Pendiente / En proceso / Resuelto / Cancelado
• Rango de fechas Desde / Hasta
• Usuario que registró la visita

Crear / Editar visita

Bloque Cliente

• Buscador inline (debounce 300-350 ms) por código, nombre o cédula
• Al seleccionar, se muestra nombre, código, teléfono y dirección

Bloque Detalles

• Fecha y hora * — datetime-local; por defecto la fecha actual
• Motivo * — texto libre, máximo 150 caracteres. Ej: "Soporte impresora caja 2"
• Estado — radio buttons en móvil, select en desktop
• Trabajos realizados / observaciones — textarea sin límite

Bloque GPS

Solo funciona en dispositivos con servicio de ubicación activo:

• Botón "Capturar" dispara navigator.geolocation.getCurrentPosition con alta precisión (15 s timeout)
• Si el navegador pide permiso, el usuario debe aceptarlo
• Las coordenadas se guardan con 7 decimales y se muestra link directo a Google Maps
• Desde escritorio normalmente no devuelve coordenadas: el botón existe pero la captura es de campo

Bloque Fotos

Imágenes de respaldo del trabajo realizado:

• Móvil: dos botones — Cámara (abre la cámara directo con capture="environment") y Galería (selección múltiple)
• Desktop: botón Subir imágenes con selección múltiple desde el explorador
• Formatos aceptados: JPG, PNG, WebP. Tamaño máximo: 12 MB por imagen
• El servidor valida el MIME real con finfo (no confía en el header del cliente)
• Click en una foto abre la versión original en pestaña nueva
• Botón × en la esquina elimina la foto (pide confirmación)

Estados de la visita

Detección móvil / desktop

• El sistema detecta el User Agent y redirige automáticamente a la versión correspondiente
• Para forzar desktop desde un móvil: agregar ?desktop=1 al URL
• Para forzar móvil desde un escritorio: agregar ?mobile=1 al URL

Visibilidad

Cualquier usuario con el permiso 671 (Visitas Ver) puede consultar todas las visitas de la empresa, sin importar quién las haya creado. El registro guarda el código del usuario que creó cada visita y, si fue editada, quién la modificó por última vez.

Eliminar visita

Con el permiso 673 (Visitas Eliminar) aparece el botón rojo en el editor. Al eliminar:

• Se borra el registro de la visita
• Se eliminan en cascada todos los registros de imágenes asociados
• Se borran los archivos físicos del directorio /uploads/visitas/<empresa>/<visita_id>/
• La operación pide confirmación y no se puede deshacer

Tablas y archivos

• Tabla ClientesVisitas — datos de la visita
• Tabla ClientesVisitasImagenes — relación 1:N con FK ON DELETE CASCADE
• Almacenamiento físico de fotos: /uploads/visitas/<empresa_db>/<visita_id>/

Pendientes de Entrega VE-100Permiso 102

Mercadería ya facturada al cliente que se entrega físicamente en partes. La factura ya rebajó el inventario; este módulo solo controla cuánto del producto se ha retirado y cuánto queda pendiente. Útil para clientes que dejan la mercadería "guardada" y la van retirando con el tiempo, o que devuelven parte de lo facturado.

Crear un pendiente desde una factura

1. Click en Nuevo (esquina superior derecha)
2. Aparece el modal Localizar Factura: escribir número de documento o nombre de cliente (mínimo 3 caracteres) y Enter
3. Solo se permiten facturas (01) o tiquetes (04) como origen — las notas de crédito/débito no aplican
4. Click en la fila de la factura → confirma → se genera el pendiente con un número consecutivo VPE y abre automáticamente el detalle

Tabs Pendientes / Entregadas

• Pendientes (tab por defecto): pendientes con saldo > 0, donde aún hay mercadería por retirar
• Entregadas: pendientes ya cerrados (saldo = 0). Útil para auditar entregas pasadas e imprimir comprobantes

Filtros disponibles

• Filtrar por fecha — checkbox que activa el rango Desde / Hasta. Si se desactiva, trae todos los pendientes sin importar fecha
• Cliente — código exacto o parte del nombre
• Factura — número de la factura origen (parcial)

Detalle del pendiente

Doble click en una fila (o el botón ojo) abre el modal de detalle. Muestra:

• Cabecera: cliente, factura, fecha y estado del pendiente
• Saldos pendientes: cantidades por artículo que aún no se han retirado
• Movimientos: historial completo (saldo inicial, salidas hechas, devoluciones)

Generar Salida — el cliente retira

Cuando el cliente viene a llevarse parte (o todo) de la mercadería:

1. Botón Generar Salida (ámbar) en el detalle
2. Aparece la lista de saldos con checkbox y la cantidad pre-cargada al máximo
3. Tildar los artículos a entregar y ajustar cantidades si entrega menos
4. Click Confirmar Salida — se descuenta del saldo y se genera un comprobante PNE imprimible

Generar Ingreso — el cliente devuelve

Si el cliente trae de regreso parte de lo retirado:

1. Botón Generar Ingreso (azul) en el detalle
2. Tildar artículos y cantidad que devuelve
3. Click Confirmar Ingreso — el saldo pendiente vuelve a subir

Cierre automático

Cuando el saldo total del pendiente llega a cero (todo entregado y nada devuelto), el sistema cambia automáticamente el estado a Entregado y el pendiente desaparece de la pestaña Pendientes (queda visible en Entregadas).

Impresión

Las impresiones se envían vía WebSocket FactuPOS Print a la impresora térmica configurada en la estación:

• Imprimir Saldos — desde el detalle, imprime los saldos actuales por artículo (útil al cerrar caja, para que el cliente firme conforme)
• Imprimir Comprobante — botón impresora en cada movimiento (excepto el saldo inicial). Reimprime el comprobante de la salida o devolución

Estados

Tipos de movimiento

Clientes Inactivos CL-014Permiso 001

Pantalla para detectar clientes a los que hace tiempo no se les emite ninguna factura y, cuando corresponde, eliminarlos para mantener limpio el listado de clientes. Pensada para depurar clientes viejos que ya no compran y no dejaron deudas.

Elegir el corte de inactividad

El filtro «Sin facturar (meses)» define a partir de cuánto tiempo se considera inactivo a un cliente. Viene en 12 meses por defecto y se puede cambiar (por ejemplo 6, 18 o 24).

• Se listan los clientes activos cuya última factura es más vieja que ese plazo.
• También aparecen los clientes que nunca tuvieron una factura (se muestran como «Nunca»).

Qué muestra cada fila

• Última factura y meses sin facturar.
• Saldo CxC — cuánto debe el cliente en Cuentas por Cobrar.
• Recurrente — si el cliente tiene facturación recurrente (contrato con monto).
• Elegible — indica con Sí / No si el cliente se puede eliminar.

¿Cuándo un cliente es «Elegible» para eliminar?

Solo se puede eliminar un cliente que cumpla las dos condiciones:

• No tiene saldo pendiente en Cuentas por Cobrar.
• No tiene facturación recurrente (contrato).

Eliminar uno o varios

1. Uno por uno: botón rojo al final de la fila → confirma → se elimina.
2. En lote: tildar la casilla de los clientes elegibles (la casilla de los no elegibles está bloqueada). Aparece una barra arriba con «Eliminar elegibles seleccionados».
3. El botón «Seleccionar elegibles» del encabezado marca/desmarca todos los de la página.

Exportar

El botón Excel descarga la lista completa con los filtros aplicados (incluye la columna de elegibilidad y el motivo cuando no aplica).

Importar Clientes CL-016Permiso 311

Herramienta para cargar de una sola vez una lista de clientes desde un archivo de Excel (.xlsx, .xls) o CSV. Ideal cuando se migra desde otro sistema o cuando un vendedor entrega su cartera en una hoja de cálculo. La inteligencia artificial reconoce automáticamente qué columna del archivo corresponde a cada dato del cliente (cédula, nombre, correo, teléfono, zona, crédito…), aunque los títulos vengan con otros nombres.

Paso 1 — Subir el archivo

Arrastre el archivo a la zona punteada o haga clic para elegirlo. No hace falta un formato especial: el sistema detecta solo la fila de títulos aunque el archivo tenga encabezados decorativos arriba. Antes de subir, elija qué hacer si el cliente ya existe:

• Saltarlo (opción por defecto) — el cliente existente no se toca.
• Actualizar sus datos — se sobrescriben los campos que vengan con valor en el archivo (requiere además el permiso 313 de editar clientes).

• ☑ Detectar duplicados también por cédula — una cédula repetida cuenta como cliente existente, aunque el código sea distinto.
• ☑ Usar cédula como código cuando falte — si la fila no trae código, se usa la cédula; si tampoco hay, se numera automáticamente.

Paso 2 — Revisar el mapeo

La IA propone a qué campo de FactuPOS va cada columna y muestra los datos de muestra de cada una para verificar. Usted puede corregir cualquier asignación con el selector, o marcar «Ignorar esta columna» para las que no interesen. Cada campo destino solo puede usarse una vez.

Paso 3 — Vista previa e importar

Se muestran las primeras filas tal como quedarán los clientes, con el total de filas a procesar. Al presionar Importar clientes el sistema crea (o actualiza) los registros y muestra el resultado: creados, actualizados, saltados y con error, con el detalle fila por fila de lo que no se pudo procesar.

Qué hace el sistema con los datos

• El tipo de identificación (física, jurídica, DIMEX, NITE) se deduce solo de la cédula si no viene en el archivo.
• Los correos inválidos se descartan con aviso (no frenan la importación).
• Montos y fechas se aceptan en varios formatos (₡1.500,50 — 15/03/1980 — fechas de Excel).
• Si viene un límite de crédito mayor a cero, el crédito del cliente queda activado.
• Los clientes nuevos se crean activos, en colones, con plazo de 30 días si no se indica otro.
• La importación queda registrada en la bitácora del sistema.

Puntos por Compras (Fidelización) CL-017

El sistema de puntos por compras permite que sus clientes acumulen puntos automáticamente cada vez que se les factura. Es una herramienta de fidelización: mientras más compran, más puntos juntan.

Configuración

Desde el menú Clientes → Configuración de Puntos (botón con la estrella ⭐) se controla todo:

• Activar acumulación — enciende o apaga el sistema. Si está apagado, ninguna factura acumula puntos.
• Porcentaje de acumulación — qué porcentaje del monto de la compra se convierte en puntos. Ejemplo: con 3%, una compra base de ₡10.000 acumula 300 puntos.
• Base de cálculo — sobre qué monto se calcula:
  • Subtotal (con descuento, antes de impuesto) — recomendado. No incluye IVA ni otros cargos.
  • Total (con impuesto) — sobre el total facturado, IVA incluido.

Cómo se acumulan los puntos

• Al emitir una factura o tiquete a un cliente, se calculan los puntos y se suman a su saldo.
• Las ventas a cliente genérico / contado sin cliente (SN) no acumulan puntos.
• Cada movimiento guarda el porcentaje usado en ese momento: si luego cambia el porcentaje, los puntos ya acumulados no se modifican.
• Los puntos no vencen.

Ver los puntos del cliente

En Facturación → Factura Desktop, al seleccionar un cliente, la ficha del cliente muestra una tarjeta dorada «Puntos acumulados» con su saldo. Al hacer clic en esa tarjeta se abre, en una pestaña nueva, el detalle de movimientos de puntos del cliente: fecha, documento, monto base, porcentaje aplicado, puntos y saldo.

Permisos

Las bitácoras requieren permiso adicional del módulo de Seguridad para ver registros de otros usuarios.

El Catálogo de Productos (CL-011) reutiliza el permiso 053 del módulo de Inventarios. La vista pública compartida no requiere permiso (acceso por token).

El Control de Visitas (CL-013) usa permisos propios 671, 672 y 673 creados con la migración del módulo (idempotente, aplicable por empresa).