Factura Electrónica v4.4 en Costa Rica: Todos los Cambios Técnicos que Debes Saber
Análisis técnico completo de los cambios introducidos en la versión 4.4 del XML de factura electrónica en Costa Rica respecto a v4.3.
La versión 4.4 del esquema de factura electrónica entró en vigencia en Costa Rica con cambios técnicos que no son ajustes cosméticos: introduce nuevos campos obligatorios, modifica validaciones del Ministerio de Hacienda y altera el formato de algunos identificadores fiscales clave. Si su sistema sigue construyendo XML bajo el esquema anterior, los documentos serán rechazados al transmitir y el equipo de operaciones tendrá que diagnosticar bajo la presión de una operación detenida.
Esta guía recorre uno por uno los cambios técnicos de la versión 4.4 respecto a la 4.3 anterior: campos nuevos, validaciones modificadas, ajustes en el cálculo de impuestos, formatos de identificación renovados. Al final encontrará la lista de validaciones que conviene aplicar localmente antes de transmitir para evitar rechazos masivos en producción tras la migración.
Contexto y marco normativo
Por qué v4.4 reemplaza a v4.3
El esquema v4.4 fue publicado por el Ministerio de Hacienda con el propósito de incorporar cambios surgidos de la práctica fiscal acumulada desde la entrada en operación de v4.3: refinamiento de validaciones, ajustes a campos que generaban ambigüedad en su interpretación, alineación con normas tributarias posteriores. No es una reescritura sino una evolución incremental — lo cual significa que la mayoría del código del lado del emisor sigue siendo válido con ajustes acotados.
Calendario de obligatoriedad
La transición de v4.3 a v4.4 se hizo con plazo escalonado: período de coexistencia donde Hacienda aceptaba documentos en ambos esquemas, seguido de una fecha de corte a partir de la cual solo v4.4 era válido. En 2025, la v4.4 es el único esquema vigente para emisiones nuevas. Documentos históricos emitidos bajo v4.3 mantienen su validez legal pero no se pueden retransmitir bajo el esquema antiguo.
Cambios estructurales del XML
Nuevos campos obligatorios
El esquema v4.4 incorpora campos adicionales que en v4.3 no existían o eran opcionales. Entre los más relevantes: identificación tributaria expandida del receptor, campos específicos para el tratamiento de regiones con régimen especial, indicadores que diferencian operaciones gravadas de exentas con mayor granularidad. Su sistema debe poblar estos campos antes de transmitir; ausencia o formato inválido genera rechazo sintáctico inmediato.
Campos modificados
Varios campos existentes en v4.3 cambian su formato o sus reglas de validación. La identificación tributaria, por ejemplo, pasa a aceptar formatos extendidos para receptores extranjeros. Las tarifas de IVA referencian un catálogo actualizado. Su sistema debe revisar cada uno de estos campos contra el esquema XSD oficial v4.4 para identificar qué cambia en su contexto específico.
Campos eliminados o deprecados
Algunos campos del esquema anterior fueron eliminados por redundancia o reemplazados por estructuras más expresivas. Mantener esos campos antiguos en el XML transmitido bajo v4.4 puede no generar rechazo — Hacienda suele ignorarlos — pero los datos quedan fuera del registro fiscal oficial. Conviene limpiar el código de campos legacy en lugar de transmitirlos por inercia.
Cambios en validación de impuestos
Tabla de tarifas IVA renovada
El catálogo de tarifas de IVA aplicable en v4.4 fue actualizado para reflejar normativas tributarias posteriores. Tarifas reducidas para ciertos sectores, exoneraciones específicas y operaciones gravadas con tarifas no estándar tienen códigos específicos en el catálogo vigente. Usar códigos del catálogo antiguo genera rechazo de validación de negocio. Conviene mantener el catálogo como recurso consultable y revisarlo en cada actualización de Hacienda.
Campos de exoneraciones
El tratamiento de exoneraciones en v4.4 exige declarar el código de la exoneración con mayor detalle: tipo de documento que la respalda, número de resolución, autoridad que la emitió, porcentaje aplicado. Operaciones con exoneración parcial — antes posibles con campos más simples — ahora requieren la estructura completa. El sistema emisor debe almacenar los datos de la resolución de exoneración del receptor para poder transmitirlos.
Cambios en identificación de receptores
Identificación tributaria del receptor
Los formatos aceptados para identificación del receptor en v4.4 incluyen cédula física, cédula jurídica, DIMEX, NITE y pasaporte para extranjeros. Cada formato tiene su propia validación de longitud y de dígito verificador. Validar el formato del identificador localmente antes de transmitir evita el rechazo más frecuente de la integración: receptor con identificación inválida para el tipo declarado.
Receptores del exterior
Para receptores en el exterior (operaciones de exportación), v4.4 acepta el pasaporte o el tax ID del país de residencia con el código ISO 3166-1 alfa-2 del país. La identificación local costarricense no aplica en esos casos. El sistema debe capturar el campo de país del receptor desde el primer momento y aplicar la validación correspondiente al tipo de identificación declarado.
Validaciones locales recomendadas antes de migrar
Validar XML contra XSD v4.4
Hacienda publica el XSD oficial v4.4 en su portal técnico. Validar cada documento construido localmente contra ese XSD antes de transmitir captura entre el 30% y el 50% de los rechazos potenciales. La validación toma milisegundos con xmllint o equivalente y se incorpora fácilmente al pipeline de emisión. Errores sintácticos aparecen con el path exacto del elemento problemático, lo cual acelera el diagnóstico.
Recalcular la clave del documento
La clave del documento electrónico en Costa Rica (50 caracteres) cambia su fórmula de cálculo levemente en v4.4. Si su sistema migra desde v4.3 sin actualizar el algoritmo de la clave, todos los documentos serán rechazados por inconsistencia. Conviene reescribir la función de cálculo de la clave siguiendo la especificación v4.4 vigente, no adaptar la antigua.
Verificar firma XAdES con parámetros v4.4
Los parámetros de firma XAdES en v4.4 mantienen la base de v4.3 pero ajustan algunas referencias y el conjunto de atributos firmados. Conviene validar la firma localmente con xmlsec1 contra el certificado de Hacienda Costa Rica antes de transmitir, para descartar problemas de canonicalización que en validación previa habrían generado rechazo.
Preguntas frecuentes
¿Cuál es la diferencia principal entre el esquema v4.3 y el v4.4 en Costa Rica? La diferencia principal está en el detalle de los campos, no en la arquitectura general. v4.4 incorpora identificación tributaria extendida del receptor, catálogo actualizado de tarifas IVA, mayor granularidad en exoneraciones, y campos específicos para receptores extranjeros. La arquitectura del flujo (transmisión asincrónica, firma XAdES, validación previa) se mantiene idéntica. Para un sistema que ya operaba bajo v4.3, la migración es ajuste incremental, no reescritura completa, pero los campos modificados deben revisarse cuidadosamente contra el XSD oficial.
¿Cómo puedo identificar si mi sistema está emitiendo documentos bajo el esquema v4.4 correctamente? Validando localmente el XML construido contra el XSD oficial v4.4 publicado por Hacienda. Si pasa esa validación, el documento es sintácticamente correcto. Adicional, conviene transmitir al ambiente de staging y observar si Hacienda devuelve aprobación; si rechaza, el detalle del error indica qué falta o qué está mal formado. Para confirmar que el sistema está efectivamente operando en v4.4 y no en una mezcla legacy, revisar el atributo de versión declarado en el XML transmitido y compararlo con el esperado por Hacienda.
¿Qué diferencia hay entre los campos eliminados de v4.3 y los simplemente deprecados? Los campos eliminados ya no existen en el XSD v4.4: incluir esos elementos en el XML transmitido genera rechazo sintáctico de inmediato. Los campos deprecados siguen aceptados pero ya no aportan información al registro fiscal; Hacienda los ignora y mantienen retrocompatibilidad con sistemas en transición. La práctica recomendada es eliminar ambos del código del sistema emisor: los eliminados porque generan rechazo, los deprecados porque generan ruido sin valor. Mantenerlos por inercia complica las auditorías posteriores.
¿Es posible mantener un sistema que emita tanto v4.3 como v4.4 simultáneamente? Durante el período de transición oficial entre los dos esquemas, Hacienda aceptaba ambos. Pasada la fecha de corte oficial, solo v4.4 es válido para emisiones nuevas. Técnicamente un sistema puede mantener la capacidad de leer y validar documentos históricos v4.3 (para auditorías o consultas) pero las emisiones nuevas en producción deben ser exclusivamente v4.4. Mantener código dual con flag de versión añade complejidad innecesaria una vez pasada la fecha de corte; conviene eliminar el path de v4.3 del flujo activo.
Artículos Relacionados
Los 10 tipos de comprobantes fiscales electrónicos (e-CF) en República Dominicana: cuándo usar cada uno
Referencia práctica de los 10 tipos de comprobantes fiscales electrónicos en República Dominicana: código, caso de uso, flujo de emisión (síncrono o asíncrono) e implicaciones técnicas para developers e integradores.
Observabilidad y Logging en la Integración con la API de Hacienda Costa Rica
Cómo implementar logging estructurado, métricas y alertas en su integración con la API de Hacienda Costa Rica. Guía técnica para ISVs con volumen en producción.
Exoneraciones Fiscales en Factura Electrónica de Costa Rica: Cómo Implementarlas Correctamente
Guía normativa sobre exoneraciones en factura electrónica v4.4 de Costa Rica: tipos de documento, campo Exoneracion en el XML, errores frecuentes y validación para ISVs.