Facturación electrónica 4.4 Costa Rica: guía técnica

Facturación electrónica 4.4 en Costa Rica: cambios, requisitos y errores frecuentes

La facturación electrónica 4.4 en Costa Rica debe abordarse como un problema fiscal y de integración, no únicamente como una actualización de XML. Para un software SaaS, POS, ERP o integrador, el reto consiste en conservar la trazabilidad de cada operación, aplicar correctamente las reglas tributarias y procesar las respuestas de Hacienda sin confundir una solicitud recibida con un comprobante aceptado.

Esta guía utiliza la versión 4.4 como marco documental de trabajo. La resolución técnica consultada indica que los comprobantes deben cumplir los formatos y especificaciones de los “Anexos y Estructuras” publicados por el Ministerio de Hacienda, y que los cambios de versión deben comunicarse mediante resolución general publicada en La Gaceta. (Resolución General sobre disposiciones técnicas

1. ¿Qué debe modelar una integración 4.4?

La arquitectura no debería tratar todos los documentos como una sola factura con variaciones. En el contrato operativo de AFECR se distinguen, entre otros, estos tipos:

FE (01): Factura Electrónica.
ND (02): Nota de Débito Electrónica.
NC (03): Nota de Crédito Electrónica.
TE (04): Tiquete Electrónico.
FEC (08): Factura Electrónica de Compra.
FEE (09): Factura Electrónica de Exportación.
REP (10): Recibo Electrónico de Pago.
Recepción y Mensaje Receptor: documentos y confirmaciones relacionados con la recepción del comprobante.

En la práctica, esto exige separar tres conceptos: el documento comercial, el estado de procesamiento y la respuesta del receptor. Un ERP puede haber creado una factura internamente, pero eso no significa que Hacienda la haya aceptado. De igual forma, una respuesta HTTP 202 solo indica que la solicitud fue recibida para procesamiento; no equivale a aceptación por parte del Ministerio de Hacienda.

2. CAByS: no es un texto decorativo

El código CAByS debe asociarse al bien o servicio que realmente se está vendiendo. La documentación oficial de Hacienda identifica el catálogo como un recurso consultable y expone una API pública para buscar por código o descripción. (Documentación de la API de Hacienda

Un error frecuente es guardar CAByS únicamente en la interfaz del POS y no en el maestro de productos. El resultado es que una sucursal puede emitir con un código distinto a otra, o que una actualización del catálogo obligue a corregir datos manualmente en cientos de artículos.

Una implementación más resistente debería:

1. Mantener CAByS como dato versionado del producto o servicio.

2. Registrar quién aprobó la clasificación y cuándo.

3. Permitir excepciones para combos, surtidos o paquetes cuando la estructura lo requiera.

4. Validar el código antes de generar el XML.

5. Guardar el CAByS utilizado en el comprobante emitido, sin sobrescribir el histórico.

6. Evitar consultas repetitivas a Hacienda mediante caché y sincronización controlada.

La actualización del catálogo requiere especial atención: el comunicado oficial sobre CAByS 2025 informó una actualización publicada el 1 de abril de 2025 y describió un período de transición entre versiones. Para una operación actual, la fecha y versión aplicables deben confirmarse contra la comunicación primaria vigente antes de automatizar una migración. (Comunicado oficial sobre CAByS 2025

3. IVA: separar tarifa, condición y cálculo

El IVA no debe representarse como un único porcentaje global de la factura. La estructura técnica contempla códigos de tarifa y reglas diferenciadas. En el material oficial de la versión 4.4 aparecen, entre otros, códigos para tarifa general del 13 %, tarifas reducidas, tarifa 0 % y tarifa exenta. Cada código tiene un uso específico; no son intercambiables. (Anexos y estructuras de comprobantes electrónicos

Por ejemplo, una venta exenta no debe modelarse simplemente como “IVA cero” si la operación exige identificar una tarifa exenta y su fundamento. Del mismo modo, la tarifa 0 % puede tener consecuencias distintas de una exoneración, especialmente para el tratamiento del crédito fiscal.

Recomendación de diseño:

Calcular impuestos por línea.
Conservar la base imponible, tarifa, código de impuesto y monto.
Agrupar los totales por impuesto y tarifa.
Validar que los totales del comprobante coincidan con la suma de las líneas y los medios de pago.
Tratar las exoneraciones como datos estructurados, no como texto libre.

4. Notas de crédito y débito: corregir con referencia

Una nota no debería utilizarse como sustituto de una edición directa de la factura original. La estructura de información de referencia exige identificar el documento relacionado, el tipo de referencia, la fecha, la razón y la clave o consecutivo correspondiente cuando aplica.

Casos habituales:

Anular una factura completa por devolución.
Corregir una diferencia de precio.
Ajustar una cantidad.
Aplicar un crédito posterior relacionado con la operación original.
Sustituir un comprobante rechazado, cuando la regla aplicable así lo permita.

El error más costoso es emitir la NC o ND sin conservar la relación con la factura de origen. También es riesgoso permitir que el usuario cambie libremente la referencia luego de generado el XML. La aplicación debe validar que el documento exista, que corresponda al emisor y que el monto del ajuste sea compatible con la operación original.

5. Recibos electrónicos de pago

El REP debe modelarse como un documento relacionado con una operación de crédito, no como una factura simplificada. La documentación técnica establece que la información de referencia del recibo puede relacionarse con comprobantes como FE, NC, ND, TE y FEC, según las reglas del esquema. (Estructura técnica disponible en el SCIJ

Un flujo recomendable es:

1. Emitir la factura con la condición de venta que corresponda.

2. Registrar en el ERP la cuenta por cobrar y el saldo pendiente.

3. Aplicar el pago recibido, total o parcial, en el módulo financiero.

4. Generar el REP con referencia exacta al comprobante relacionado.

5. Procesar la respuesta de Hacienda y actualizar el estado del recibo.

No conviene generar un REP únicamente porque el usuario presionó “registrar pago”. Primero debe existir una transacción financiera confirmada y una regla clara para pagos parciales, múltiples facturas o diferencias de redondeo.

6. Errores frecuentes al integrar con Hacienda

Confundir transporte con aceptación

Guardar HTTP 202 como “aceptado” rompe la trazabilidad. AFECR puede recibir y procesar estados mediante webhooks firmados e idempotencia, pero el sistema cliente debe conservar el estado fiscal real y actualizarlo únicamente con la respuesta correspondiente.

Firmar antes de completar el XML

La firma debe ejecutarse sobre el documento final. Cambiar después un correo, total, impuesto o referencia invalida la integridad del comprobante.

Generar consecutivos desde varias cajas sin coordinación

En una jerarquía Integrador > Empresa > Sucursal > Terminal, el diseño debe definir quién controla numeración, configuración y credenciales. No se debe permitir que dos terminales produzcan el mismo consecutivo por una condición de carrera.

Exponer la clave API

La clave de AFECR debe permanecer en backend. Nunca debe enviarse al navegador, aplicación móvil, código JavaScript público ni dispositivo POS sin una capa segura de intermediación.

Reintentar sin idempotencia

Ante un timeout, repetir la emisión sin una clave idempotente puede duplicar documentos. El integrador debe registrar el identificador interno de la operación, la solicitud enviada, la respuesta y el estado final.

Suponer que un PDF contiene toda la API

Un PDF o payload exportado no necesariamente representa todos los endpoints de la versión vigente. Antes de desarrollar, confirme el contrato de integración, los tipos documentales y el comportamiento de consulta, recepción, webhooks y reintentos.

7. Checklist técnico antes de salir a producción

[ ] Cada producto y servicio tiene CAByS revisado.
[ ] Las tarifas de IVA se calculan por línea.
[ ] Exoneraciones y autorizaciones se almacenan estructuradamente.
[ ] FE, NC, ND, TE, FEC, FEE y REP tienen reglas separadas.
[ ] Las notas validan referencia, montos y documento de origen.
[ ] Los consecutivos son únicos por el ámbito definido.
[ ] La clave API solo existe en backend.
[ ] Los reintentos utilizan idempotencia.
[ ] HTTP 202 no se marca como aceptación fiscal.
[ ] Se procesan webhooks firmados y se verifica su autenticidad.
[ ] Se guardan XML, respuestas, estados y fechas de procesamiento.
[ ] Existen pruebas para rechazos, timeouts, duplicados y pagos parciales.
[ ] La versión documental y las fuentes normativas se revisan antes de cada cambio.

Conclusión

La versión 4.4 debe implementarse como un conjunto de reglas de negocio, estructuras fiscales y estados operativos. El valor de una integración no está solo en generar un XML válido, sino en poder explicar qué ocurrió con cada documento, por qué se aplicó una tarifa, cuál producto usó determinado CAByS y cómo se corrigió una operación sin perder la trazabilidad.

AFECR puede encajar cuando un producto SaaS, POS, ERP o integrador necesita centralizar esta infraestructura bajo una jerarquía operativa definida y con mecanismos de webhooks firmados e idempotencia. Para revisar el contrato técnico, consulte la documentación para desarrolladores de AFECR. También puede consultar la API de facturación electrónica para SaaS.

Fuentes y fecha de consulta

Consulta realizada el 13 de octubre de 2026. Este artículo utiliza como marco documental la versión 4.4 y no afirma reformas, plazos o fechas posteriores que no estén respaldados en las fuentes primarias enlazadas.

¿Desea integrar facturación electrónica en su software?

Conozca la infraestructura de AFECR y su documentación para desarrolladores.

Explorar AFECR →

Facturación electrónica 4.4 en Costa Rica: guía práctica para integrar CAByS, IVA y comprobantes