Herramientas AY-034

Aplicaciones (Descargas)

Las descargas e instaladores del sistema ya no están dentro de Herramientas: ahora tienen su propia tarjeta Aplicaciones en el menú principal. Herramientas quedó solo con las utilidades en línea (validar cédulas, CABYS, XML a Excel, cola de impresión, auditoría, etc.).

Qué encontrás en Aplicaciones

• Impresión · Windows: FactuPOS Print Windows, Print Bridge Windows, SumatraPDF
• Impresión · Linux: FactuPOS Print Linux, Print Bridge Linux
• Impresión · Android: Print Bridge (Android)
• Etiquetas / Fuentes: Fuente Code 128, Fuente Libre Barcode 128
• Datáfono: FactuposDatafono (paquete y solo .exe)
• Respaldo: FactuposBackup (Windows) y versión CLI
• Huella Digital: servicio para Linux y Windows
• Pagos SINPE: FactuposSMS (Android)
• Redes: WinBox 4 (Linux)

Validar Cédulas

Consulta directa al API de Hacienda para verificar si una cédula existe y obtener el nombre registrado.

Cómo usar

1. Ingresar la cédula (sin guiones)
2. Seleccionar tipo (física, jurídica, DIMEX, NITE)
3. Presionar Validar
4. Se muestra: estado del contribuyente, nombre, actividades económicas registradas

Usos típicos

• Verificar datos antes de crear un cliente nuevo
• Confirmar la razón social correcta (para evitar rechazo de FE)
• Saber si un proveedor está en régimen simplificado o tradicional

Consulta CABYS

Buscador del catálogo oficial CABYS (Catálogo de Bienes y Servicios) del Ministerio de Hacienda. Usado para clasificar tributariamente cada producto/servicio.

Búsqueda

• Por código — 13 dígitos exacto (si lo conoce)
• Por palabra clave — Buscar "pan", "servicio de limpieza", "software" y ver sugerencias
• Por categoría — Navegar por el árbol de niveles (9 niveles)

Resultado

Para cada CABYS se muestra:

• Código completo (13 dígitos)
• Descripción
• Tarifa de IVA asociada (13%, 4%, 2%, 1%, 0%)
• Categoría padre

XML a Excel

Convertidor que extrae los datos de un XML de factura electrónica y genera un archivo Excel con las líneas de detalle.

Flujo

1. Cargar el archivo XML (puede ser venta propia, compra recibida, o XML de respaldo)
2. El sistema parsea el XML y extrae: datos del emisor, receptor, líneas, totales
3. Descarga un Excel con toda la información en formato tabular

Casos de uso

• Analizar una factura de proveedor (sumar por categoría, comparar con lista de precios)
• Crear respaldos legibles de facturas electrónicas
• Importar datos a otros sistemas que no leen XML directamente

Leer XML

Visor público de facturas electrónicas Hacienda Costa Rica. Soporta Factura Electrónica, Tiquete, Nota de Crédito / Débito, Factura de Compra (tipo 08), Exportación y Mensaje Receptor. Abre y renderiza XMLs v4.3 y v4.4 como factura legible con todos sus datos + validaciones automáticas.

URL pública: https://soportereal.com/utils/leerxml/ — sin login.

Acceso desde FactuPOS: Menú Principal → Herramientas → Conversores → Leer XML (abre en nueva pestaña, sin auth adicional).

Privacidad: la utilidad no guarda datos de los XMLs cargados. Todo se procesa en el request y se descarta. No hay logs ni base de datos.

Carga de XML

Tres formas de cargar el XML:

• Arrastrar archivo sobre la zona punteada (drag & drop)
• Click en la zona y seleccionar el archivo .xml del disco
• Pegar el XML completo en el área de texto (soporta XML crudo o Base64; auto-detecta con base64_decode)

Botón Ejemplo precarga un XML de demostración (factura de farmacia con una línea exonerada MAG) para probar la herramienta sin necesidad de subir archivo propio.

Botón Limpiar vuelve al estado inicial para cargar otro documento.

Qué extrae del XML

• Encabezado: tipo de documento, consecutivo (20 dígitos), clave (50 dígitos), fecha de emisión, condición de venta, medio de pago, moneda y tipo de cambio
• Emisor y Receptor: nombre, nombre comercial, tipo ID, cédula, ubicación (provincia-cantón-distrito-señas), teléfono, correo, código de actividad económica
• Detalle de líneas: número, código comercial, CABYS, cantidad, unidad, descripción, precio unitario, subtotal, descuentos, impuestos (IVA + específicos), exoneraciones, total línea
• Documentos Referenciados (si el XML los trae): tipo, número, fecha, motivo, razón
• Medios de Pago: tipo, código, moneda, tipo de cambio, monto pagado
• Resumen: totales gravados, exentos, exonerados, descuentos, impuestos, total comprobante

El parseo usa SimpleXMLElement + XPath con local-name() para ignorar los namespaces, compatible con ambas versiones (v4.3 y v4.4) del esquema Hacienda.

Validación de Clave

Botón Validar junto a la clave ejecuta una doble validación:

1. Validación estructural local (instantánea)

Descompone los 50 dígitos de la clave según la estructura oficial de Hacienda:

Cruza los datos con el XML: cédula, fecha y consecutivo deben coincidir entre la clave y el documento. Si hay discrepancias, marca el check correspondiente con ✗ rojo. No se muestran los valores en pantalla (solo "✓ coincide" / "✗ NO coincide") para proteger datos personales.

2. Consulta en línea en Hacienda

Dispara automáticamente un fetch al API oficial api.comprobanteselectronicos.go.cr (producción) con credenciales OAuth2 almacenadas en el sistema. Si Hacienda tiene registrado el documento y el contribuyente autenticado es emisor o receptor, devuelve el estado real:

• ACEPTADO (verde) — Hacienda procesó y aprobó
• RECHAZADO (rojo) — Hacienda rechazó; muestra el motivo oficial
• PROCESANDO (ámbar) — Hacienda aún lo está validando
• RECIBIDO (ámbar) — Hacienda lo recibió, sin procesar aún

Además del estado, muestra el mensaje y detalle que Hacienda emitió en su XML respuesta, más el total declarado en sus registros.

Si Hacienda responde 404 / Documento no encontrado, significa que el contribuyente del sistema no es emisor ni receptor de ese documento (Hacienda sólo entrega datos a las partes del comprobante, no a terceros).

Botones adicionales

• Copiar — copia los 50 dígitos al portapapeles
• ATV — abre atv.hacienda.go.cr en nueva pestaña para verificación manual

Validación CABYS

Botón Validar CABYS en el header de la tabla Detalle. Recorre las celdas .cabys-cell[data-cabys] y consulta cada código contra el API oficial api.hacienda.go.cr/fe/cabys.

Marca cada celda con:

• ✓ verde — código existe en el catálogo oficial CABYS (tooltip muestra la descripción oficial)
• ✗ rojo — código no encontrado
• — gris — línea sin CABYS

Al terminar, el botón muestra el contador: "X válidos · Y inválidos" (verde si todo está bien, rojo si hay inválidos). Los resultados se cachean en CABYS_CACHE para evitar re-consultas repetidas.

Usar esta validación para detectar artículos con CABYS mal asignados antes de aceptar una factura electrónica de compra o al auditar ventas emitidas.

Consulta de Actividades Hacienda

Botón Hacienda junto a la cédula de Emisor y Receptor. Consulta el API api.hacienda.go.cr/fe/ae?identificacion=XXX (CORS abierto, fetch directo desde el navegador) y muestra un panel con:

• Nombre legal del contribuyente según el registro tributario
• Situación: badges de color para Inscrito / Moroso / Omiso
• Administración Tributaria (San José, Cartago, etc.) y Régimen (General, Simplificado, etc.)
• Lista completa de actividades registradas con chips:
  • Principal — actividad económica principal del contribuyente
  • Inactiva — actividad declarada pero sin movimiento actual
  • En XML — actividad que coincide con el CodigoActividadEmisor/Receptor del XML cargado (se resalta en verde)
• Si la actividad declarada en el XML NO está registrada en Hacienda, se marca en rojo "NO declarada en Hacienda" — posible fraude o actividad vencida

Útil para verificar si el proveedor de una factura de compra es un contribuyente activo y si la actividad económica declarada en la factura corresponde realmente a lo que está habilitado en Hacienda. Las respuestas se cachean por cédula en HACIENDA_CACHE.

Verificación de Cálculos

Al cargar un XML, el visor valida automáticamente todos los cálculos y muestra:

• Banner verde "Cálculos consistentes · N líneas verificadas" si todo cuadra
• Panel rojo con lista de errores agrupados por línea / resumen si hay inconsistencias. Las filas problemáticas se marcan con ícono triángulo pulsante y borde izquierdo rojo

Tolerancia: ±0.05 por cálculo individual y ±0.05 × N_líneas en los agregados (absorbe los redondeos de Hacienda que trabaja con 5 decimales pero reporta 2).

Cómo interpreta los impuestos por línea

Una línea de detalle puede traer varios bloques <Impuesto>. Hacienda usa el campo Codigo para distinguir cada tipo:

El visor identifica el IVA principal como el impuesto con código 01, 07 u 08. Los impuestos específicos (02-06, 12) se muestran como badge amarillo +X.XX al lado del IVA en la tabla, con tooltip indicando qué códigos aparecen adicionalmente.

<Impuesto><Codigo>07</Codigo><Tarifa>13.00</Tarifa><Monto>1127.43</Monto></Impuesto>
<Impuesto><Codigo>05</Codigo><Tarifa>8.62</Tarifa><Monto>747.36</Monto></Impuesto>
<ImpuestoNeto>1127.43</ImpuestoNeto>
<SubTotal>8672.53</SubTotal>
<MontoTotalLinea>9799.96</MontoTotalLinea>

Validaciones por línea (4 checks)

1. Cantidad × PrecioUnitario ≈ SubTotal + Descuento (= MontoTotal bruto)
2. BaseImponible × TarifaIVA / 100 ≈ IVA principal (solo el IVA, no los específicos)
3. ImpuestoNeto ≈ IVA principal − Exonerado
4. MontoTotalLinea ≈ SubTotal + ImpuestoNeto

Validaciones del resumen (6 checks)

1. TotalGravado ≈ Σ MontoTotal de líneas con impuesto. Nota: Hacienda calcula TotalGravado antes de restar descuentos por línea (= SubTotal + Descuento)
2. TotalImpuesto ≈ Σ ImpuestoNeto (solo el IVA neto)
3. TotalExonerado ≈ Σ MontoExonerado
4. TotalDescuentos ≈ Σ Descuento
5. TotalComprobante ≈ TotalVentaNeta + TotalImpuesto − IVA Devuelto + Otros Cargos
6. Σ MontoTotalLinea ≈ TotalComprobante

¿Por qué a veces falla?

El XML viene generado por el software contable del proveedor. A veces tiene errores reales de cálculo (precio mal multiplicado, IVA incorrecto, total que no cuadra). El visor los detecta fila por fila, convirtiéndose en un auditor rápido antes de aceptar la factura o registrarla en compras.

Errores comunes:

• Redondeo acumulado: a veces los decimales difieren por un centavo. La tolerancia ±0.05 lo absorbe
• IVA mal calculado: generalmente por exoneración mal registrada en el ERP del proveedor
• Total del comprobante ≠ Σ líneas: cargos o descuentos globales no documentados
• Base imponible errónea: descuentos aplicados dos veces

Medios de Pago

Renderiza todos los medios de pago declarados en el XML. Soporta las tres variantes del esquema Hacienda para el bloque:

Códigos soportados:

• 01 Efectivo
• 02 Tarjeta
• 03 Cheque
• 04 Transferencia / depósito bancario
• 05 Recaudado por terceros
• 06 SINPE MÓVIL
• 07 Plataforma Digital
• 99 Otros

Fallback de monto: si el XML declara un medio de pago pero no especifica su monto (TotalMedioPago vacío o 0) y hay sólo uno, el visor usa el TotalComprobante del resumen. En ese caso aparece una nota amarilla informativa abajo de la tabla indicando el fallback.

Documentos Referenciados

Cuando el XML trae un bloque <InformacionReferencia>, el visor muestra una card "Documentos Referenciados" con tipo, número (clave del referenciado), fecha, motivo y razón. Típico en:

• Notas de Crédito / Débito que referencian la factura original
• Recibos Electrónicos de Pago que referencian las facturas pagadas
• Sustituciones por rechazo de Hacienda o del receptor

Soporta ambas variantes del esquema:

• v4.3: TipoDoc / Codigo
• v4.4: TipoDocIR / CodigoReferencia

Códigos de tipo de documento referenciado (Nota 10)

Códigos de motivo (Nota 9)

Los códigos nuevos de 2026 son obligatorios desde el 1 de noviembre. Ya están disponibles en los ambientes de staging y producción de Hacienda.

Cola de Impresión

Visualiza y gestiona los trabajos de impresión enviados al socket de impresión. Útil para diagnosticar problemas o reenviar impresiones fallidas.

Columnas

• ID del trabajo
• Fecha y hora de envío
• Usuario que lo envió
• Impresora destino
• Estación
• Tipo de documento (factura, cotización, NC, etc.)
• Estado: Pendiente, Enviado, Impreso, Error

Acciones

• Reenviar — Vuelve a intentar imprimir un trabajo fallido
• Eliminar — Cancela un trabajo pendiente
• Ver detalle — Muestra el contenido del trabajo (formato ESC/POS)

Impresión Bluetooth desde PC (Print Bridge)

El FactuPOS Print Bridge permite imprimir tiquetes por Bluetooth directamente desde una PC o tablet (Windows o Linux), sin depender del navegador. Se descarga desde Herramientas → Descargas → Impresión.

¿Cuál descargar?

• Windows (.exe) — PCs y tablets Windows, incluida la Surface ARM
• Linux (.deb) — equipos Debian, Ubuntu o Mint

Cada archivo lleva su versión en el nombre (ej. FactuPOS-Bridge-Windows.exe) para que siempre instales la más reciente.

Instalación y uso

1. Emparejá la impresora Bluetooth en el sistema (Windows o Linux) antes de empezar.
2. Instalá el archivo descargado. Queda en la bandeja del sistema y arranca solo al prender la PC.
3. Desde su ícono en la bandeja → menú Impresora → elegí tu impresora Bluetooth.
4. En Configuración de Estación activá la ruta APK Bridge.
5. Listo: los tiquetes se imprimen por Bluetooth.

Pendientes Hacienda

Muestra los documentos electrónicos sin respuesta de Hacienda. Son documentos que se enviaron pero Hacienda aún no ha dado veredicto (aceptado o rechazado).

Estados visibles

• Esperando respuesta — Enviado hace pocos minutos, en cola en Hacienda
• Tiempo excesivo — Más de X horas sin respuesta (alerta)
• Sin firmar — Falla en el firmado, no se envió
• Revisión manual — Datos inconsistentes

Acciones

• Reintentar — Vuelve a enviar el documento
• Localizar — Consulta directamente a Hacienda por el estado actual
• Ver detalle — Muestra el XML y la respuesta (si hay)

Auditoría de Ventas

Herramienta que detecta inconsistencias en las ventas procesadas. Responde preguntas como:

• ¿Hay facturas a crédito sin CxC registrada?
• ¿Hay facturas contabilizadas con cuentas contables incorrectas?
• ¿Hay facturas aplicadas sin movimiento de inventario?
• ¿Hay NC sin factura original asociada?
• ¿Hay recibos aplicados por más del saldo del documento?

Checks típicos

Periodicidad

Se recomienda correr esta auditoría al menos semanalmente, y siempre antes del cierre mensual para que el D104 y los estados financieros cuadren.

Latencia del Servidor HE-014

Mide el tiempo de respuesta entre la computadora del cliente y el servidor de FactuPOS. Sirve para saber, de forma objetiva, si el sistema "se siente lento" por culpa del internet del cliente o porque el servidor está ocupado. Está en Herramientas → Diagnóstico.

Cómo usarla

• Presione Iniciar prueba. La herramienta envía "pings" al servidor y mide cuánto tarda cada ida y vuelta.
• Modo Continuo: deja la prueba corriendo indefinidamente. Ideal para clientes que reportan que el sistema se pone lento a veces — se deja abierta y queda registrado el momento exacto del bajón.
• 10 / 25 / 50 / 100 pings: hace una cantidad fija de mediciones y se detiene sola.
• Intervalo: cada cuánto se envía un ping (250 ms a 2 s).

El veredicto

Arriba aparece un mensaje grande y a color que le dice al cliente, en palabras simples, cómo está su conexión:

Comparativo: Servidor vs Internet vs Red local

• Servidor — lo que tarda el servidor en responder (suele ser muy bajo).
• Internet (tu red) — lo que agrega la conexión a internet del cliente. Este es el número clave para saber si el problema es del cliente.
• Red local (referencia) — < 10 ms, lo que se ve desde una PC conectada por cable en la misma oficina del servidor. Es el "ideal" contra el cual comparar.

Indicadores

Historial

La herramienta guarda el historial de mediciones en el mismo navegador (se conserva aunque se cierre la página). Permite:

• Filtrar solo picos (mayores a 300 ms o errores) para ver de un vistazo a qué hora se puso lento.
• Exportar a CSV para enviar el registro a soporte.
• Limpiar el historial guardado.

Revisor de IVA vs contabilidad

Compara, mes a mes, el IVA que sale de sus documentos (ventas, compras y gastos) contra el que tiene la cuenta contable de IVA. Sirve para encontrar diferencias antes de declarar.

Está en Herramientas → Auditoría → Revisor de IVA vs contabilidad. El reporte de origen es Ventas → IVA por mes vs compras.

Qué le muestra

• Debe y Haber de la cuenta, mes a mes, en un gráfico.
• La comparación: lo que dice la cuenta contra lo que dicen los documentos, y cuánto no calza.
• Al abrir el Detalle de un mes, de qué está hecho: cuánto puso cada tipo de documento y cuáles asientos no vienen de un documento (pagos de IVA, arrastres, ajustes), con un botón para abrir el asiento completo.
• Documentos en el asiento equivocado: los que quedaron asentados en un mes distinto al de su fecha.

Corregir los que están en el mes equivocado

Un documento debe estar en un asiento del mismo mes de su fecha; distinto día está bien, distinto mes no. Cuando una factura de marzo se asienta en mayo, marzo queda corto y mayo largo.

Cada documento de esa lista trae un botón «Mover a <mes>» que lo lleva al asiento del mes que le corresponde. Si no existe asiento de ese mes para ese usuario, se crea. Se mueven todas las líneas del documento juntas, y si el documento no cuadra por sí solo el sistema se niega a moverlo. Todo queda en la bitácora.

Cómo dejar un año cuadrado

1. Empiece por Documentos en el asiento equivocado y muévalos. Eso suele resolver la mayoría de los meses.
2. Vea qué meses siguen con diferencia y abra su Detalle.
3. Compare el Haber contra su IVA de ventas y el Debe contra el de compras: eso le dice de qué lado está el problema.
4. Si falta una compra, búsquela en Compras sin contabilizar y contabilícela desde la compra.
5. Si un asiento tiene un monto que no coincide con su documento, revíselo con su contador.