Cambios en Anexos v4.4 de Hacienda Costa Rica 2026

Cambios en los Anexos v4.4 de Hacienda: guía técnica para developers

Si su sistema emite facturas electrónicas en Costa Rica, el Ministerio de Hacienda activará en noviembre de 2026 la versión 4.4 del esquema XML. Los Anexos — los documentos complementarios que acompañan cada comprobante electrónico — incorporan campos nuevos y validaciones modificadas que, si no se implementan a tiempo, provocarán rechazos en la ATV y bloquearán la emisión de documentos para sus clientes.

Esta guía analiza los cambios técnicos concretos de la versión 4.4 en los Anexos, el impacto en la estructura XSD, los nuevos campos obligatorios y el proceso de validación en el ambiente de pruebas de Hacienda. El objetivo es que usted pueda planificar e implementar la transición antes de la fecha límite.

Qué son los Anexos en la factura electrónica de Costa Rica

En el esquema de facturación electrónica de Costa Rica, los Anexos son secciones del XML que amplían la información del comprobante principal. No son archivos separados sino nodos dentro del mismo documento XML firmado digitalmente que usted envía a la ATV para su validación.

Los Anexos incluyen información sobre: actividad económica del emisor, referencias a comprobantes anteriores (en notas de crédito y débito), datos de transporte cuando aplica, y detalles de retención de impuestos. La Resolución DGT-R-033-2019 y sus actualizaciones posteriores establecen el esquema técnico vigente, que la versión 4.4 modifica en varios puntos clave.

Resumen de cambios en la versión 4.4

Impacto técnico para su sistema de integración

1. Validador XSD local: Descargue el nuevo XSD desde el sitio oficial de Hacienda y reemplace el archivo en su servicio de validación antes del 15 de octubre para tener margen de pruebas.

2. Constructor de XML: Si su servicio construye el XML manualmente, agregue el campo CodigoActividad a la plantilla del nodo Emisor. Si usa un ORM o mapper, agregue el atributo al modelo y a las reglas de serialización.

3. Almacenamiento de actividad económica: Asegúrese de que el código CIIU v4 de cada empresa emisora esté almacenado en su base de datos. Si maneja múltiples emisores (ISV o SaaS multi-tenant), este dato debe ser configurable por tenant.

⚠️ Nota normativa: Hacienda no ha anunciado un período de coexistencia entre v4.3 y v4.4. A partir de la fecha de activación, todos los documentos deben cumplir el nuevo esquema. Planifique la transición con al menos 3 semanas de margen para pruebas.

Cómo validar su implementación en el ambiente de pruebas

1. Acceda al endpoint sandbox de la ATV
2. Envíe un documento de prueba con el campo CodigoActividad presente
3. Verifique que el campo estadoComprobante sea aceptado
4. Pruebe un documento sin CodigoActividad para confirmar el rechazo
5. Valide una nota de crédito con dos referencias simultáneas

💡 Con Alanube: La API de Alanube Costa Rica gestiona la actualización de esquema de forma transparente. Al activarse la versión 4.4, los documentos se emitirán automáticamente bajo el nuevo esquema sin cambios en su integración existente.

Errores frecuentes durante la transición a v4.4

Error: XSD-VALIDATION-001: Element 'Emisor': Missing child element(s). Expected is 'CodigoActividad'
Causa: El campo CodigoActividad no está presente en el nodo Emisor.
Solución: Agregar el código CIIU v4 correspondiente desde el Registro Único Tributario.

Error: XSD-VALIDATION-045: Element 'Identificacion/Numero': Invalid format
Causa: La cédula física incluye puntos o guiones. La v4.4 valida estrictamente el formato numérico sin separadores.
Solución: Limpiar el campo al construir el XML: eliminar cualquier carácter no numérico.

Error: ATV-ERR-023: TipoCambio requerido cuando CodigoMoneda != CRC
Causa: El documento incluye moneda USD pero omite el campo TipoCambio.
Solución: Agregar el tipo de cambio del BCCR del día de emisión.

FAQ

¿Cuándo entra en vigor obligatoriamente la versión 4.4 en Costa Rica?

Hacienda ha establecido noviembre de 2026 como fecha de activación obligatoria. Se recomienda completar la migración antes del 15 de octubre para disponer de al menos tres semanas de pruebas con el ambiente de producción.

¿Cómo puedo obtener el código CIIU v4 de mi empresa?

Usted puede consultar el código CIIU de la empresa en el portal de ATV de Hacienda bajo la sección “Consulta de Contribuyentes”. El código tiene seis dígitos y corresponde a la actividad económica principal registrada.

¿Qué pasa si mi sistema sigue enviando documentos en v4.3 después de la fecha límite?

La ATV rechazará todos los documentos con el esquema anterior. Los comprobantes rechazados no tienen validez tributaria, lo que puede derivar en sanciones según el artículo 83 del Código de Normas y Procedimientos Tributarios de Costa Rica.

¿La API de Alanube gestiona automáticamente la transición entre versiones de esquema?

Sí. Cuando Hacienda activa una nueva versión del esquema, Alanube actualiza el proceso de construcción y firma del XML de forma transparente. El payload que usted envía al endpoint de Alanube no cambia.

Si su equipo necesita prepararse para la transición, consulte la documentación técnica de Alanube Costa Rica.

Fuentes

• Ministerio de Hacienda de Costa Rica. (2024). Especificaciones técnicas para comprobantes electrónicos versión 4.4. DGT. https://tribunet.hacienda.go.cr/FormatosCodigosHacienda/
• Dirección General de Tributación. (2019). Resolución DGT-R-033-2019. Ministerio de Hacienda.
• Banco Central de Costa Rica. (2026). Indicadores Económicos. BCCR. https://gee.bccr.fi.cr/