Facturación electrónica en Costa Rica vía API: guía técnica para ISVs

Por Ing. Carlos Méndez | 4 de septiembre de 2026

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.

El equipo de desarrollo lleva tres semanas intentando emitir su primer comprobante electrónico en Costa Rica. Ya obtuvo las credenciales de ATV, descargó el XSD de Hacienda y leyó la Resolución DGT-R-48-2016. Pero cada vez que envía el XML firmado, el sistema responde con un código de error sin mayor explicación. El ambiente de pruebas ATVCERT devuelve errores distintos a los de producción, y la documentación oficial no cubre los casos borde que el sistema encuentra en la práctica.

Esta guía cubre la arquitectura técnica completa del sistema de comprobantes electrónicos de Hacienda Costa Rica: tipos de documentos, estructura del XML, flujo de firma XAdES-BES, autenticación OAuth con ATV, diferencias entre ATVCERT y producción, y los criterios que un ISV debe evaluar antes de elegir un proveedor de API. Al terminar, usted tendrá un mapa técnico completo del sistema y las preguntas exactas que debe hacerle a cualquier proveedor.

Marco regulatorio: Hacienda y el sistema de comprobantes electrónicos

La facturación electrónica en Costa Rica es administrada por el Ministerio de Hacienda a través de la Dirección General de Tributación (DGT). El sistema fue establecido por la Resolución DGT-R-48-2016 y ha sido actualizado con múltiples reformas que modificaron los XSD, los tipos de comprobantes válidos y los requisitos de firma digital.

Resolución DGT-R-48-2016 y esquemas vigentes

La versión 4.3 del XSD es la vigente a 2026. Los ISVs que trabajen con esquemas anteriores (4.1 o 4.2) recibirán rechazo automático en ATV. Hacienda publica los XSD actualizados en su portal, pero no notifica activamente a los desarrolladores sobre cambios de versión — es responsabilidad del proveedor o del ISV mantenerse al día con los esquemas vigentes.

Obligatoriedad y plazos para 2026

Para 2026, prácticamente todos los contribuyentes del régimen tradicional están obligados a emitir comprobantes electrónicos. Los del Régimen Simplificado tienen condiciones específicas. El cumplimiento depende del sector económico y el código CIIU del contribuyente. Un ISV que integra clientes de múltiples sectores debe validar la condición de cada uno antes de activar la emisión.

Tipos de comprobantes electrónicos en Costa Rica

El sistema de Hacienda reconoce seis tipos de comprobantes electrónicos, cada uno con su propio XSD y sus propias reglas de negocio. La selección incorrecta del tipo tiene consecuencias tributarias directas para el receptor.

La distinción entre FE y TE es crítica: una Factura Electrónica puede ser utilizada por el receptor para crédito fiscal, mientras que el Tiquete Electrónico no. Un ISV que emita TE cuando debería emitir FE genera un problema tributario para el cliente receptor. La lógica de selección de tipo debe estar validada en la capa de negocio, no solo en la interfaz.

Arquitectura de la API ATV: flujo técnico de emisión

La Administración Tributaria Virtual (ATV) de Hacienda expone una API REST para recepción y consulta de comprobantes. El flujo de emisión tiene cuatro etapas obligatorias: autenticación OAuth 2.0, construcción del XML según XSD v4.3, firma digital XAdES-BES y envío a ATV. Un error en cualquier etapa invalida el comprobante.

Flujo completo de emisión de una Factura Electrónica

# Flujo de emisión — Costa Rica ATV (pseudocódigo)

1. POST /token  (OAuth2 client_credentials, expira en 5 min)
   → access_token

2. Construir XML según XSD v4.3 de Hacienda
   → Validar contra XSD antes de firmar

3. Firmar XML con XAdES-BES
   → Certificado BCCR o PSC autorizado
   → Firma incrustada en el cuerpo del XML

4. Codificar XML firmado en Base64

5. POST /recepcion
   Body: { clave, fecha, emisor{tipo,numero}, receptor{tipo,numero},
           comprobanteXml: "<base64>", callbackUrl }
   → HTTP 201: aceptado para procesamiento asíncrono

6. GET /comprobante/{clave}   (polling o callback)
   → estado: aceptado | rechazado | en_proceso
   → detalleMensaje: descripción del resultado de Hacienda

Endpoints ATV: producción y certificación

Los dos ambientes usan URLs base y servidores de autenticación distintos. El token OAuth expira en 5 minutos — un ISV que reutilice tokens sin validar la expiración encontrará errores 401 intermitentes bajo carga. La gestión del ciclo de vida del token debe estar en la capa de infraestructura, no en la lógica de negocio.

# PRODUCCIÓN
OAuth:  https://idp.comprobanteselectronicos.go.cr/auth/realms/rut/protocol/openid-connect/token
API:    https://api.comprobanteselectronicos.go.cr/recepcion/v1/

# CERTIFICACIÓN (ATVCERT)
OAuth:  https://idp-stag.comprobanteselectronicos.go.cr/auth/realms/rut-stg/protocol/openid-connect/token
API:    https://api-sandbox.comprobanteselectronicos.go.cr/recepcion-sandbox/v1/

# Endpoints principales
POST /recepcion              → Enviar comprobante
GET  /comprobante/{clave}    → Consultar estado
POST /recepcionTerceros      → Enviar como tercero autorizado

Requisitos técnicos de integración para ISVs

Certificado digital y firma XAdES-BES

Costa Rica exige firma digital XAdES-BES sobre el XML del comprobante. El certificado debe ser emitido por el Banco Central de Costa Rica (BCCR) u otro prestador de servicios de certificación autorizado. La cédula jurídica del emisor debe coincidir exactamente con la información del certificado — una discrepancia genera rechazo inmediato sin código de error descriptivo en todos los casos.

Para ISVs que gestionan múltiples emisores, la administración de certificados es uno de los puntos de mayor complejidad operativa: cada empresa requiere su propio certificado con su propia fecha de vencimiento. Un proveedor de API que no ofrezca gestión centralizada de certificados obliga al ISV a implementar esta lógica internamente, incluyendo alertas de vencimiento y renovación.

Estructura XML: campos críticos del XSD v4.3

El XSD de Costa Rica define validaciones estrictas de formato. Los campos que generan mayor porcentaje de rechazos en producción son: la Clave (50 dígitos con estructura compuesta), el CodigoActividad (4 dígitos CIIU), las fechas en ISO 8601 con zona horaria -06:00, y los montos con exactamente 5 decimales.

<!-- Estructura base FE v4.3 — Costa Rica (pseudocódigo) -->
<FacturaElectronica
  xmlns="https://tribunet.hacienda.go.cr/docs/esquemas/2017/v4.3/facturaElectronica">
  <Clave>50600000000031010000010001000000000100100001082</Clave>
  <!-- Estructura clave: País(3)+Fecha(8)+Cédula(12)+Consecutivo(20)+Situación(1)+Seguridad(8) -->
  <CodigoActividad>6201</CodigoActividad>
  <NumeroConsecutivo>00100001010000000001</NumeroConsecutivo>
  <FechaEmision>2026-09-04T09:00:00-06:00</FechaEmision>
  <Emisor>
    <Nombre>Empresa Ejemplo S.A.</Nombre>
    <Identificacion><Tipo>02</Tipo><Numero>3101000001</Numero></Identificacion>
    <NombreComercial>Ejemplo Tech</NombreComercial>
    <Ubicacion>...</Ubicacion>
    <CorreoElectronico>facturacion@empresa.cr</CorreoElectronico>
  </Emisor>
  <Receptor>...</Receptor>
  <CondicionVenta>01</CondicionVenta>
  <MedioPago><Codigo>01</Codigo></MedioPago>
  <DetalleServicio>...</DetalleServicio>
  <ResumenFactura>
    <CodigoTipoMoneda><CodigoMoneda>CRC</CodigoMoneda><TipoCambio>1.00000</TipoCambio></CodigoTipoMoneda>
    <TotalServGravados>100000.00000</TotalServGravados>
    <TotalImpuesto>13000.00000</TotalImpuesto>
    <TotalComprobante>113000.00000</TotalComprobante>
  </ResumenFactura>
</FacturaElectronica>

ATVCERT vs producción: diferencias técnicas que afectan el desarrollo

El ambiente de certificación ATVCERT no replica el comportamiento de producción con fidelidad completa. Hay validaciones que solo se ejecutan en producción, tiempos de respuesta asíncronos distintos, y códigos de error que no aparecen en ATVCERT aunque sí ocurren con datos reales de producción.

Las credenciales de ATVCERT se solicitan de manera separada en el portal de Hacienda. Intentar usar credenciales de producción en el endpoint de certificación devuelve un error 401 que puede confundirse con un problema de configuración del cliente OAuth. Los certificados usados en certificación tampoco son válidos en producción.

Criterios técnicos para evaluar proveedores de API en Costa Rica

Un proveedor de API intermediario reduce la complejidad de mantener la integración directa con ATV. Los criterios que determinan la idoneidad para producción son: gestión de certificados por emisor sin administración manual del ISV; sandbox que refleje el comportamiento de producción; renovación automática del token OAuth; soporte para todos los tipos de comprobante (FE, FEE, TE, NC, ND, TEC); webhooks de confirmación de estado; SLA documentado con métricas de uptime verificables; y soporte para consultas retroactivas.

Para ISVs que necesitan operar en múltiples países, además de Costa Rica, es relevante evaluar si el proveedor ofrece cobertura multi-país bajo una sola API. Esto reduce la superficie de integración y el costo de mantenimiento a largo plazo. La API de facturación electrónica para Costa Rica de Alanube cubre todos los tipos de comprobante vigentes, gestiona el ciclo de vida de certificados por emisor y expone webhooks en tiempo real.

Preguntas frecuentes

¿Cuál es la diferencia entre una Factura Electrónica y un Tiquete Electrónico en Costa Rica?

La Factura Electrónica (FE) identifica al receptor con cédula jurídica o física y le permite usar el documento como crédito fiscal ante Hacienda. El Tiquete Electrónico (TE) se emite a consumidor final sin identificación completa del receptor y no otorga derecho a crédito fiscal. Emitir TE a un contribuyente registrado que necesita crédito fiscal puede causarle problemas en auditorías tributarias.

¿Cómo puedo obtener credenciales para el ambiente ATVCERT de Hacienda Costa Rica?

Las credenciales de ATVCERT se solicitan en el portal ATV del Ministerio de Hacienda (https://www.hacienda.go.cr) con firma digital del representante legal. Son credenciales separadas de las de producción y no son intercambiables. El proceso puede tomar varios días hábiles dependiendo de la validación de Hacienda.

¿Qué diferencia hay entre el certificado del BCCR y el de un prestador de servicios de certificación autorizado?

El Banco Central de Costa Rica (BCCR) es la entidad raíz de la infraestructura de certificación digital del país. Los prestadores de servicios de certificación (PSC) autorizados emiten certificados bajo esa jerarquía. Ambos son técnicamente válidos para firmar comprobantes electrónicos con XAdES-BES. La diferencia práctica está en el proceso de obtención, el costo anual y la disponibilidad de renovación en línea.

¿Es posible emitir comprobantes electrónicos en Costa Rica sin gestionar la firma digital directamente?

Sí. Un proveedor de API intermediario puede gestionar la firma digital en nombre del emisor, siempre que el emisor ceda las credenciales de su certificado al proveedor bajo un acuerdo contractual. Esta arquitectura reduce la complejidad técnica del ISV, pero requiere evaluar la política de custodia de certificados del proveedor — un certificado comprometido permite emitir facturas fraudulentas a nombre del emisor.

Sobre el autor

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.