Documentos Electronicos - Hacienda AY-023

Descripcion General

FactuPOS genera, firma y envia documentos electronicos al Ministerio de Hacienda de Costa Rica, cumpliendo con la normativa de facturacion electronica v4.4. El sistema procesa ventas (facturas, tiquetes, notas de credito/debito, exportaciones), compras y confirmaciones de aceptacion/rechazo.

Todo el flujo se gestiona a traves de la tabla fac_bitacora en la base de datos facturacostarica, donde cada documento avanza por etapas hasta recibir respuesta de Hacienda.

Tipos de Documento

El sistema soporta los siguientes tipos de documento electronico:

Flujo de Procesamiento

Cada documento electronico pasa por 5 etapas secuenciales. Desde el panel administrativo se controla cada paso:

Estados del Documento

Estructura de la Clave (50 digitos)

Cada documento tiene una clave unica de 50 digitos que lo identifica ante Hacienda:

Estructura del Consecutivo (20 digitos)

El consecutivo identifica la sucursal, terminal, tipo y numero secuencial:

Generacion XML - Ventas (01, 02, 03, 04, 09)

La funcion _generarXmlVenta() construye el XML para todos los tipos de venta. Los datos provienen de:

Estructura XML de una Factura

El XML sigue esta estructura principal:

Diferencias por tipo de documento

Linea de Detalle

Cada linea del documento contiene: codigo CABYS, codigo comercial, cantidad, unidad de medida, detalle, precios e impuestos.

Codigos de Tarifa IVA

Bloque de Exoneracion

Si el cliente tiene exoneracion activa (tabla ClienteExoneracion), cada linea con ArticuloIvaExonerado > 0 incluye el bloque:

El IVA neto de cada linea se calcula como: Impuesto - IvaAsumido - IvaExonerado.

Generacion XML - Compras (Tipo 08)

La funcion _generarXmlCompra() genera el XML de FacturaElectronicaCompra para proveedores en regimen simplificado.

Siempre incluye bloque InformacionReferencia:

Notas de Credito y Debito - Referencia

Las NC (tipo 03) y ND (tipo 02) requieren obligatoriamente el bloque InformacionReferencia que apunta a la factura original.

Busqueda de la clave original (3 niveles)

Tipos de referencia NC/ND

Confirmaciones (MensajeReceptor - Tipo 05)

Cuando se recibe una compra electronica, el sistema genera un MensajeReceptor para confirmar la aceptacion o rechazo ante Hacienda.

Formato del consecutivo de confirmacion

Procesamiento Post-Respuesta

Una vez que Hacienda responde (estado 4 o 5), el sistema ejecuta acciones segun el tipo:

Ventas aceptadas (tipos 01, 02, 03, 04, 09)

• Inserta el XML firmado y respuesta en XmlDocumentos
• Actualiza CodRespuesta = '4' en XmlDocumentos
• Encola email al cliente (si no es generico SN)
• Copia al emisor (param 74), agente (param 318), respaldo (param 149)
• Elimina registro de fac_bitacora

Ventas rechazadas

• Mismo flujo pero con CodRespuesta = '5'
• El email incluye el motivo del rechazo de Hacienda
• Auto-nula (2026-04-20): Tras marcar VentaMadre.Estado = 5, el sistema ejecuta automáticamente el runner ejecutarRechazadaANula() — mismo flujo que el trigger de VE-030 al abrir una factura rechazada. Borra rastro (cierre de caja, CxC, inventario, ContaDiario), encola email "RECHAZADA A NULA", imprime ESC/POS y deja el documento en Estado = 3 (Nula). Idempotente: si ya está en 3, omite.
• Notificación a cola 301 (2026-04-20): Envía un ticket corto a la cola de impresión 301 vía WebSocket con encabezado "DOCUMENTO RECHAZADO POR HACIENDA" + tipo / número / fecha / cliente / motivo. Esto alerta al usuario del rechazo sin depender de que alguien abra VE-030 manualmente. Requiere cliente Python FactuPOS_Print con la cola 301 registrada.

Confirmaciones aceptadas (tipo 05)

• Inserta confirmacion tipo 05 en XmlDocumentos
• Actualiza CodRespuesta = '4' en el documento original
• Actualiza CompraMadre.CompraMadreEstado = '1' (Aceptada)
• Encola email al proveedor con confirmacion

Confirmaciones rechazadas (tipo 05)

• Inserta con CodRespuesta = '5'
• Actualiza CompraMadre.CompraMadreEstado = '5' (Rechazada)
• Email de notificacion con motivo del rechazo en rojo

Condicion y Medio de Pago

Condicion de venta

Medios de pago

Tipos de Identificacion

Resumen de Factura

El bloque ResumenFactura acumula los totales del documento:

Parametros de Empresa Relevantes

Tablas y Vistas Involucradas

Base de datos: facturacostarica

Base de datos de la empresa

Base de datos: dbcontrol

Archivos del Sistema

Generacion de XML

Procesamiento de respuestas

Emails

Backup de XMLs

Los XMLs se respaldan automaticamente en disco para recuperacion:

/mnt/backupxml/{servidor}/{base_datos}/{anio-mes}/

Nomenclatura: FA_COMPRA_{XML|MSG}_{tipo}_{consecutivo}.txt

Errores Comunes de Hacienda

Interfaz del módulo (actualizada 2026-05-12)

La pantalla de Documentos Procesados (HA-001) usa el estándar visual FLAT de FactuPOS — barra de título azul marino #0047AB, encabezados de tabla gris oscuro con texto blanco, letra de datos a 16 px, esquinas suaves y alto contraste. Los cambios visibles para el usuario son:

Ver XML → ahora abre una página de detalle (HA-002)

El botón Ver XML (ícono </> en la columna de acciones) y el doble clic sobre una fila ya no abren una ventana emergente pequeña: ahora abren una página completa en una pestaña nueva con todo el detalle del documento, más grande y cómoda de leer. En esa página hay tres pestañas:

• Detalle — datos del documento: consecutivo, tipo, fecha, estado, total, emisor, receptor, mensaje de Hacienda y clave de 50 dígitos. Si es una confirmación (tipo 05), también muestra los datos del documento original confirmado.
• XML Firmado — el XML enviado a Hacienda, con sangría y letra grande (16 px). Botón Descargar XML para guardarlo como archivo .xml.
• XML Respuesta — el XML de respuesta de Hacienda (aceptación o rechazo). También se puede descargar.

Desde esa página: Descargar XML guarda el XML de la pestaña activa, Imprimir XML abre el diálogo de impresión del navegador con solo el contenido, y Volver cierra la pestaña. Atajos: Esc cierra, ← / → cambian de pestaña.

Estado como punto de color

La columna "Estado" con badge de texto se reemplazó por un punto de color al inicio de cada fila (más compacto y fácil de escanear). Los colores son:

La leyenda de colores se muestra permanentemente en la cinta de totales (abajo), junto al contador de documentos y los totales monetarios.

Filtros con auto-envío

Al cambiar cualquier filtro (Desde, Hasta, Grupo, Tipo, Estado, Consec, Buscar) el listado se recarga automáticamente — ya no es necesario tocar el botón "Refrescar". El botón Refrescar queda como respaldo manual.

• Selects y checkboxes: envían al instante del cambio.
• Campos de texto: envían con retardo de 350 ms tras dejar de escribir, o al presionar Enter.
• Fechas (Flatpickr): envían al elegir una fecha del calendario.

Formato de fechas

Los campos "Desde" y "Hasta" ahora muestran siempre DD/MM/YYYY (formato Costa Rica) independientemente del idioma del navegador. El sistema guarda internamente YYYY-MM-DD para la consulta SQL.

Botón Imprimir → reporte paginado (Paged.js)

Los botones separados "PDF" y "Ver" se unificaron en un único botón Imprimir. Al presionarlo:

1. Abre una nueva pestaña con una vista paginada estilo revista (hojas tamaño carta apaisadas).
2. La primera página lleva logo y datos de la empresa; el resto tiene encabezado compacto.
3. Cada hoja numera automáticamente (Pág. X / Y).
4. Desde esa vista el usuario decide imprimir en papel o guardar como PDF usando Ctrl+P del navegador.

Los colores del reporte impreso también siguen el estándar Banking Bold (encabezados en azul corporativo).

Botón Salir

El botón Salir ahora solo cierra la pestaña — no cierra la sesión. Si la pestaña no puede cerrarse (porque el navegador no lo permite), redirige al Menú Principal. Para cerrar sesión completamente, use el botón Logout del encabezado general del sistema.

Detección automática de móvil

Cuando se abre el módulo desde un teléfono o tablet (detección por User-Agent), el sistema redirige a una versión móvil optimizada (archivo documentos_procesados_movil.php) si existe. Si no hay versión móvil, se muestra el escritorio. Para forzar la vista de escritorio desde un móvil, añadir ?desktop=1 a la URL.

Impuesto de Servicio en el XML (cargo 10% restaurantes) — 2026-05-15

Las facturas y tiquetes generados desde SAC Táctil (módulo restaurante) cuando aplican el cargo de servicio del 10% ahora incluyen correctamente el bloque <OtrosCargos> en el XML enviado a Hacienda v4.4.

Qué cambió

Antes de este fix, el TotalImpuestoServicio quedaba guardado en VentaMadre pero no se reflejaba en el XML. Resultado: el TotalComprobante del XML era menor que el de la factura física por la diferencia del 10% — Hacienda recibía un monto incoherente con lo que veía el cliente.

Estructura correcta del XML (v4.4)

El bloque <OtrosCargos> se emite al nivel del documento, entre </DetalleServicio> y <ResumenFactura>. Dentro de <ResumenFactura> aparece solo el total agregado:

</DetalleServicio>

<OtrosCargos>
    <TipoDocumentoOC>06</TipoDocumentoOC>   <!-- 06 = Servicio o propina legal -->
    <Detalle>Impuesto de Servicio</Detalle>
    <PorcentajeOC>10.00</PorcentajeOC>
    <MontoCargo>523.58</MontoCargo>
</OtrosCargos>

<ResumenFactura>
    ...
    <TotalImpuesto>680.65</TotalImpuesto>
    <TotalImpAsumEmisorFabrica>0.00</TotalImpAsumEmisorFabrica>
    <TotalOtrosCargos>523.58</TotalOtrosCargos>     <!-- suma de todos los OtrosCargos -->
    <MedioPago>...</MedioPago>
    <TotalComprobante>6440.00</TotalComprobante>  <!-- incluye servicio -->
</ResumenFactura>

Validaciones del esquema Hacienda v4.4

• El bloque OtrosCargos NO va dentro de ResumenFactura. Si se coloca ahí, Hacienda rechaza con: Invalid content was found starting with element 'OtrosCargos'. One of '{TotalIVADevuelto, TotalOtrosCargos, MedioPago, TotalComprobante}' is expected.
• El elemento se llama <PorcentajeOC> (con "OC" al final), NO <Porcentaje>. Si se usa el nombre legacy, Hacienda rechaza con: Invalid content was found starting with element 'Porcentaje'. One of '{PorcentajeOC, MontoCargo}' is expected.
• TotalComprobante debe sumar el cargo de servicio: TotalVentaNeta + TotalImpuesto + TotalOtrosCargos − TotalIVADevuelto.

Códigos TipoDocumentoOC válidos

Para SAC restaurante se usa 06. Otros códigos válidos en v4.4: 01–05 = costos de envío/seguro/otros; 06 = Servicio o propina legal; 07–13 = aportes a planes/contribuciones; 99 = otros cargos.

Cálculo del porcentaje

El sistema calcula automáticamente el porcentaje del servicio sobre la base imponible (suma de ArticuloVentaSubTotal3 de las líneas, equivalente al total antes de IVA y servicio). Para el típico 10% sobre 5,235.77 → cargo de 523.58 → porcentaje calculado: 10.00%.

Si tengo una factura SAC vieja rechazada por este bug

1. Entrar al módulo Documentos Hacienda (panel admin).
2. Buscar el documento por consecutivo o clave.
3. Botón Generar XML — esto borra el registro viejo de fac_bitacora y arma un XML nuevo con el cargo de servicio.
4. Firmar y Enviar de nuevo a Hacienda.

Si el documento ya fue aceptado por Hacienda con el monto incorrecto (sin el servicio en el XML), no se puede regenerar — hay que emitir una Nota de Crédito que la anule y emitir una factura nueva con el cargo correcto.

Archivo modificado

/api/hacienda/generar/xml_builder.php función _generarXmlVenta() — para tipos 01 (FE), 02 (ND), 03 (NC), 04 (TE), 09 (Export).