Factura electrónica versión 4.4 Costa Rica: qué cambió y cómo migrar su integración
La factura electrónica versión 4.4 de Costa Rica es el esquema XSD vigente definido por el Ministerio de Hacienda para todos los comprobantes electrónicos. Si su integración todavía usa una versión anterior del esquema, los documentos emitidos pueden ser rechazados por el sistema ATV sin que el error sea inmediatamente evidente. Esta guía cubre exactamente qué cambió en la factura electrónica versión 4.4 de Costa Rica, qué campos e integraciones se ven afectados, y cómo migrar sin interrumpir la operación.
Índice de contenidos
- Qué es la versión 4.4 y por qué el Ministerio de Hacienda la introdujo
- Cambios técnicos principales respecto a versiones anteriores
- Campos nuevos obligatorios en la versión 4.4
- Cambios en el cálculo del IVA y los descuentos
- Errores frecuentes en la migración a la versión 4.4
- Cómo verificar que su integración cumple con la versión 4.4
- Cómo Alanube gestiona las actualizaciones de esquema
Qué es la versión 4.4 y por qué el Ministerio de Hacienda la introdujo
La factura electrónica versión 4.4 de Costa Rica es la versión más reciente del esquema XML que define la estructura de los comprobantes electrónicos en el sistema de facturación electrónica costarricense. El Ministerio de Hacienda publica y actualiza este esquema a través de resoluciones técnicas que definen campos obligatorios, tipos de datos, validaciones y la clave numérica de 50 dígitos.
La versión 4.4 fue introducida para incorporar nuevos requerimientos de información fiscal que el Ministerio de Hacienda necesita para el control tributario, particularmente relacionados con la actividad económica del emisor y el tratamiento de descuentos en la base imponible del IVA. Su implementación es obligatoria — el ATV rechaza documentos en esquemas anteriores.
Cambios técnicos principales respecto a versiones anteriores
Los cambios de la factura electrónica versión 4.4 de Costa Rica respecto a la versión 4.3 afectan principalmente tres áreas del esquema:
| Área | Versión 4.3 | Versión 4.4 |
|---|---|---|
| Sección del emisor | Cédula, nombre, provincia, cantón | Agrega código de actividad económica obligatorio |
| Cálculo de descuentos | Descuento sobre precio bruto | Descuento afecta la base imponible del IVA por ítem |
| Clave numérica | 50 dígitos con validación básica en ATV | Validación más estricta de duplicados en ATV |
| Medios de pago | Lista de códigos de medio de pago | Códigos actualizados — algunos deprecados |
Campos nuevos obligatorios en la versión 4.4
El cambio que más rechazos genera al migrar a la factura electrónica versión 4.4 de Costa Rica es la ausencia del campo CodigoActividad en la sección del emisor. Este campo contiene el código de actividad económica del emisor según el catálogo del Ministerio de Hacienda, y es obligatorio en todos los tipos de comprobante:
<Emisor>
<Nombre>Empresa Ejemplo SA</Nombre>
<Identificacion>
<Tipo>02</Tipo>
<Numero>3456789012</Numero>
</Identificacion>
<CodigoActividad>620900</CodigoActividad> <!-- NUEVO en 4.4 -->
<NombreComercial>Empresa Ejemplo</NombreComercial>
<Ubicacion>...</Ubicacion>
<Telefono>...</Telefono>
<CorreoElectronico>facturacion@empresa.com</CorreoElectronico>
</Emisor>El código de actividad económica del emisor se obtiene del registro tributario en el Ministerio de Hacienda. Si el emisor tiene varias actividades registradas, debe usarse el código de la actividad principal o la actividad correspondiente al bien o servicio que se está facturando.
Cambios en el cálculo del IVA y los descuentos
En versiones anteriores a la 4.4, el descuento se reportaba sobre el precio bruto y el IVA se calculaba después. En la factura electrónica versión 4.4 de Costa Rica, el IVA debe calcularse sobre el monto neto por ítem (precio bruto menos descuento). Para una integración que no haya actualizado esta lógica, el total del IVA calculado puede no coincidir con el que valida el ATV, generando rechazo.
El cálculo correcto en la factura electrónica versión 4.4 de Costa Rica es:
// Versión 4.3 (incorrecta en 4.4):
baseImponible = precioUnitario × cantidad
iva = baseImponible × tarifa
descuentoTotal = descuento × cantidad
// Versión 4.4 (correcta):
montoNeto = (precioUnitario - descuento) × cantidad
baseImponible = montoNeto
iva = baseImponible × tarifaCon la API de Alanube, este cálculo se gestiona automáticamente en la capa del proveedor. El developer envía el precio unitario y el descuento por ítem, y Alanube calcula la base imponible y el IVA según el esquema vigente.
Errores frecuentes en la migración a la versión 4.4
Error: ATV rechaza el documento con “campo CodigoActividad faltante o inválido”.
Causa: el código de actividad económica no está incluido en la sección del emisor, o el código no corresponde a una actividad registrada en el Ministerio de Hacienda para ese contribuyente.
Solución: obtener el código de actividad del registro tributario del emisor y verificar que esté activo. El código tiene 6 dígitos y corresponde al catálogo de actividades del CIIU adaptado por Hacienda.
Error: ATV rechaza el documento con “inconsistencia en el total del IVA”.
Causa: la lógica de cálculo sigue usando la fórmula de versiones anteriores donde el IVA se calculaba sobre el precio bruto antes del descuento.
Solución: actualizar el cálculo para aplicar el descuento por ítem antes de calcular la base imponible del IVA.
Error: ATV rechaza la clave numérica como duplicada aunque es un documento nuevo.
Causa: el consecutivo no está siendo gestionado de forma centralizada y dos instancias del sistema generaron la misma clave.
Solución: garantizar que el consecutivo se genere desde un punto centralizado con control de concurrencia. Alanube gestiona esto internamente.
Cómo verificar que su integración cumple con la versión 4.4
Antes de emitir documentos en producción con el esquema 4.4, verificar estos puntos:
- El campo
CodigoActividadestá presente y válido en la sección del emisor. - El descuento por ítem se aplica antes del cálculo del IVA, no después.
- Los códigos de medio de pago usados corresponden al catálogo de la versión 4.4 — algunos códigos de versiones anteriores fueron deprecados.
- La clave de 50 dígitos se genera con el algoritmo actualizado — el tipo de comprobante en la posición correcta de la clave.
- El ATV del Ministerio de Hacienda devuelve estado de aceptación (no solo recepción) para los documentos de prueba.
Cómo Alanube gestiona las actualizaciones de esquema
Cuando el Ministerio de Hacienda publica una nueva versión del esquema, Alanube actualiza la capa de construcción del XML en su infraestructura. Las integraciones existentes que usan la API de Alanube no requieren cambios en el código del sistema del contribuyente para estar compatibles con el nuevo esquema.
Esto significa que la obligación de seguir la factura electrónica versión 4.4 de Costa Rica — y cualquier versión futura que publique Hacienda — recae sobre Alanube, no sobre el equipo de desarrollo del contribuyente. Para explorar la integración con el esquema 4.4 vigente, el Sandbox de Alanube para Costa Rica está disponible sin contrato previo.
Preguntas frecuentes sobre la factura electrónica versión 4.4 de Costa Rica
¿Cuándo fue obligatorio migrar a la versión 4.4 de la factura electrónica en Costa Rica?
El Ministerio de Hacienda estableció la versión 4.4 como esquema obligatorio mediante resolución técnica. Las integraciones que no hayan migrado generan rechazos en ATV. Para verificar la resolución vigente, consultar el portal del Ministerio de Hacienda directamente.
¿El código de actividad económica cambia si el emisor tiene varias actividades registradas?
La recomendación del Ministerio de Hacienda es usar el código de la actividad económica que corresponde al bien o servicio que se está facturando en ese documento específico. Si el sistema del contribuyente no diferencia por actividad, puede usarse el código de la actividad principal registrada en el RUT.
¿La versión 4.4 afecta también a los tiquetes electrónicos o solo a las facturas?
La factura electrónica versión 4.4 de Costa Rica aplica a todos los tipos de comprobante electrónico: facturas (tipo 01), tiquetes (tipo 02), notas de débito (tipo 03), notas de crédito (tipo 04), notas de despacho (tipo 05) y comprobantes de exportación (tipo 06).
¿Cómo sé si mi integración actual está en versión 4.3 o 4.4?
El atributo xmlns del elemento raíz del XML identifica la versión del esquema. Si la integración genera el XML directamente, buscar la declaración de namespace en el documento raíz. Si usa un proveedor como Alanube, el esquema vigente se gestiona automáticamente en la capa del proveedor.
Migre a la versión 4.4 sin interrumpir su operación
Con el Sandbox de Alanube para Costa Rica puede probar la migración a la versión 4.4 antes de activarla en producción, verificando cada tipo de comprobante con los casos de prueba del Ministerio de Hacienda.
Solicite acceso al Sandbox de Alanube para Costa Rica →
Fuentes
Ministerio de Hacienda de Costa Rica. (2023). Esquema XSD versión 4.4 de Comprobantes Electrónicos. https://www.hacienda.go.cr
Ministerio de Hacienda de Costa Rica. (2023). Resolución técnica de Comprobantes Electrónicos. https://www.hacienda.go.cr
