Integrar su sistema con Hacienda Costa Rica: guía técnica paso a paso
El servicio de recepción de comprobantes electrónicos de Hacienda Costa Rica usa un flujo de autenticación OAuth 2.0 y validación asíncrona que sorprende a la mayoría de developers en el primer intento. El documento se envía y la respuesta de aceptación llega en un segundo callback — no en la misma request. Si usted no implementa ese flujo de callback desde el principio, su sistema quedará sin saber si los comprobantes pasaron o no.
Esta guía cubre el flujo técnico completo para integrar cualquier sistema con los servicios de la ATV de Hacienda: desde la obtención del token OAuth hasta la validación del estado del comprobante con el XML de respuesta firmado de Hacienda.
Prerrequisitos
- Número de cédula jurídica o física activo en el Registro Tributario (ATV)
- Certificado de firma digital emitido por el Banco Central o el MICITT de Costa Rica (llave .p12)
- Cliente OAuth registrado en el portal de Hacienda (client_id y client_secret)
- Acceso al ambiente de pruebas:
https://api-sandbox.comprobanteselectronicos.go.cr/ - Servicio receptor de callbacks disponible en una URL pública o ngrok para pruebas
Paso 1: Obtener el token OAuth 2.0 de Hacienda
El servicio de la ATV usa el flujo client_credentials de OAuth 2.0. El token tiene una vida útil de 30 minutos:
Nota: Los ejemplos de código de esta sección están disponibles en la documentación técnica de Alanube. Puede agregarlos manualmente en el editor de WordPress.
Paso 2: Construir el XML del comprobante
El comprobante electrónico de Costa Rica es un XML con schema XSD versión 4.4 (vigente desde noviembre 2026). Debe incluir el namespace correcto y todos los campos obligatorios de la versión 4.4, incluyendo el CodigoActividad:
Nota: Los ejemplos de código de esta sección están disponibles en la documentación técnica de Alanube. Puede agregarlos manualmente en el editor de WordPress.
Paso 3: Firmar el XML con el certificado de Hacienda
El comprobante debe firmarse digitalmente con el certificado .p12 emitido por el BCCR o el MICITT. La firma usa XAdES-XL (Enveloped):
Nota: Los ejemplos de código de esta sección están disponibles en la documentación técnica de Alanube. Puede agregarlos manualmente en el editor de WordPress.
Paso 4: Enviar el comprobante a la ATV
El endpoint de recepción acepta el XML firmado codificado en Base64, junto con la clave del comprobante:
Nota: Los ejemplos de código de esta sección están disponibles en la documentación técnica de Alanube. Puede agregarlos manualmente en el editor de WordPress.
Paso 5: Recibir el callback de Hacienda
Hacienda envía el resultado de la validación a la callbackUrl que usted especificó. El servicio receptor debe estar disponible en HTTPS público. Ejemplo de handler:
Nota: Los ejemplos de código de esta sección están disponibles en la documentación técnica de Alanube. Puede agregarlos manualmente en el editor de WordPress.
💡 Con Alanube: La API de Alanube Costa Rica gestiona el callback de Hacienda internamente y expone el estado del comprobante en el endpoint GET /invoices/{id}. Su sistema no necesita mantener un servidor de callbacks público.
Tipos de comprobante electrónico en Costa Rica y cuándo usarlos
Hacienda Costa Rica define varios tipos de comprobante electrónico, cada uno con un código de tipo de documento y reglas de emisión específicas. Elegir el tipo incorrecto resulta en rechazo automático del comprobante:
| Tipo | Código | Descripción | Cuándo usarlo |
|---|---|---|---|
| Factura electrónica | 01 | Venta de bienes o servicios a contribuyentes | Receptor con cédula jurídica o física registrada |
| Tiquete electrónico | 04 | Venta al consumidor final (sin crédito fiscal) | Receptor sin cédula, ventas de mostrador, puntos de venta |
| Nota de débito | 02 | Ajuste que incrementa el monto de un comprobante anterior | Corrección de precio o cargos adicionales sobre factura emitida |
| Nota de crédito | 03 | Anulación total o parcial de un comprobante | Devoluciones, descuentos posteriores a la factura, errores en datos |
| Factura electrónica de compras | 08 | Compras a proveedores no obligados a facturar electrónicamente | Régimen Simplificado, agricultores, personas físicas exentas |
| Factura electrónica de exportación | 09 | Ventas de bienes o servicios al exterior | Receptor sin cédula costarricense, transacción en moneda extranjera |
Los comprobantes de notas de débito y crédito (tipos 02 y 03) deben referenciar el número de clave de 50 dígitos del comprobante original en el campo InformacionReferencia. Si ese campo está vacío o contiene una clave inválida, Hacienda rechaza el documento con el código de error CR-XXX correspondiente.
Manejo del estado asíncrono: consulta activa como fallback
El flujo de callback de Hacienda no garantiza entrega en todos los casos. Si el servicio receptor de su sistema estaba caído o la IP fue bloqueada temporalmente, el comprobante puede haberse procesado correctamente en Hacienda, pero su base de datos local nunca recibió la confirmación. Para estos casos, se implementa una consulta activa periódica sobre los comprobantes en estado PENDIENTE:
- Cada 15 minutos, un job de fondo busca en la base de datos local todos los comprobantes con estado
PENDIENTEque tienen más de 5 minutos de antigüedad. - Por cada comprobante pendiente, se hace una consulta
GETal endpoint de consulta de la ATV usando la clave de 50 dígitos como parámetro. - Si el campo
ind-estadode la respuesta esaceptadoorechazado, se actualiza el estado en la base de datos local igual que si hubiera llegado el callback. - Si el campo
ind-estadoesprocesando, el comprobante permanece en estadoPENDIENTEpara la siguiente iteración del job. - Comprobantes con más de 2 horas en estado
PENDIENTEse marcan comoTIMEOUTy se notifica al equipo de operaciones para revisión manual.
El endpoint de consulta de la ATV es: GET https://api.comprobanteselectronicos.go.cr/recepcion/v1/recepcion/{clave}. En el ambiente de pruebas, reemplazar el dominio por api-sandbox.comprobanteselectronicos.go.cr. La consulta requiere el mismo token OAuth con el que se envió el comprobante.
Estructura de la clave de 50 dígitos: guía de construcción
La clave de 50 dígitos es el identificador único de cada comprobante en el sistema de Hacienda. Un error en cualquiera de sus componentes resulta en el rechazo inmediato del comprobante con código error-clave. La estructura exacta es:
| Posición | Longitud | Campo | Valor / Ejemplo |
|---|---|---|---|
| 1–3 | 3 | Código de país | 506 (siempre para Costa Rica) |
| 4–9 | 6 | Fecha (ddmmaa) | 250925 para el 25 de septiembre de 2025 |
| 10–11 | 2 | Tipo de identificación del emisor | 01 cédula física, 02 jurídica, 03 DIMEX, 04 NITE |
| 12–23 | 12 | Cédula del emisor (relleno de ceros a la izquierda) | 000312345678 |
| 24–43 | 20 | Número consecutivo del comprobante | 00100001010000000128 (tipo + local + consecutivo) |
| 44 | 1 | Situación del comprobante | 1 normal, 2 contingencia, 3 sin internet |
| 45–50 | 8 | Código de seguridad aleatorio | 8 dígitos generados aleatoriamente por el emisor |
El campo Número consecutivo (posiciones 24–43) se compone a su vez de tres subcampos: tipo de comprobante (3 dígitos), número de sucursal/local (5 dígitos) y número secuencial del comprobante (10 dígitos). El tipo 001 corresponde a Factura Electrónica, 002 a Nota de Débito, 003 a Nota de Crédito y 004 a Tiquete Electrónico.
Ambientes de prueba y producción: diferencias clave
Hacienda Costa Rica mantiene dos ambientes completamente separados. Las credenciales OAuth no son intercambiables entre ambientes y los comprobantes emitidos en pruebas no tienen valor fiscal. Antes de ejecutar la migración a producción, verifique estos puntos:
| Parámetro | Ambiente de pruebas | Producción |
|---|---|---|
| URL base API | api-sandbox.comprobanteselectronicos.go.cr | api.comprobanteselectronicos.go.cr |
| URL OAuth | idp.comprobanteselectronicos.go.cr/auth/realms/rut-stag/ | idp.comprobanteselectronicos.go.cr/auth/realms/rut/ |
| Certificado .p12 | Certificado de prueba (BCCR o MICITT ambiente test) | Certificado de producción vigente |
| Cédula del emisor | Cédula de prueba registrada en ATV sandbox | Cédula jurídica o física real |
| callbackUrl | Puede ser localhost con ngrok para pruebas | URL HTTPS pública con certificado SSL válido |
| Validez fiscal | Ninguna | Plena — comprobantes registrados en Tributación |
Un error frecuente en la migración es usar el realm de sandbox (rut-stag) con las credenciales de producción: el token se genera correctamente pero la API de producción lo rechaza con 401 Unauthorized. Verificar que tanto el client_id, el client_secret y el realm del endpoint OAuth corresponden al mismo ambiente.
Errores comunes al integrar con Hacienda Costa Rica
Error: 401 — invalid_client: Client authentication failed
Causa: Las credenciales OAuth (client_id o client_secret) son incorrectas o pertenecen al ambiente equivocado.
Solución: Verificar que se usan las credenciales del ambiente correcto (sandbox vs. producción). Las credenciales son diferentes para cada ambiente.
Error: 400 — La clave del comprobante ya existe
Causa: El número de clave de 50 dígitos ya fue usado en ese ambiente.
Solución: La clave es única por comprobante. Verificar el algoritmo de generación de clave — incluye fecha, tipo de comprobante, número consecutivo y dígito verificador.
Error: Respuesta de callback "ind-estado": "rechazado" sin mensajes
Causa: El XML de respuesta está codificado en Base64 y debe decodificarse para ver los mensajes de error.
Solución: Decodificar el campo respuesta-xml del callback y parsear el XML para extraer los nodos Detalle con los errores específicos.
Error: 400 — El número consecutivo no corresponde al tipo de comprobante
Causa: Los 3 primeros dígitos del número consecutivo en el campo del XML no coinciden con el tipo de documento enviado. Por ejemplo, usar 001 (factura) pero enviar un tiquete electrónico en el campo TipoDoc.
Solución: Revisar que el subcampo de tipo en la posición 24–26 de la clave coincide con el valor del campo TipoDoc del XML. La tabla de tipos es: 001 Factura, 002 Nota Débito, 003 Nota Crédito, 004 Tiquete.
FAQ
¿Cómo se genera la clave de 50 dígitos del comprobante de Hacienda?
La clave de 50 dígitos se compone de: código de país (3), fecha (6), tipo de identificación del emisor (2), cédula del emisor (12), consecutivo del comprobante (20), situación del comprobante (1) y dígito verificador (1) calculado por módulo 10. Hacienda publica el algoritmo exacto en su documentación técnica oficial.
¿Cuánto tiempo tiene Hacienda para responder el callback?
En condiciones normales, Hacienda envía el callback en menos de 3 minutos. En períodos de alta carga (inicio y fin de mes), puede tardar hasta 30 minutos. Si no recibe el callback en 2 horas, consulte el estado directamente en el endpoint de consulta de la ATV con la clave del comprobante.
¿Qué pasa si el callbackUrl no está disponible cuando Hacienda envía la respuesta?
Hacienda reintentará el callback hasta 3 veces. Si todos los reintentos fallan, el estado del comprobante queda disponible para consulta manual en el endpoint de la ATV. Su sistema debe implementar también una consulta activa de estado como fallback para comprobantes que no reciben callback.
¿La API de Alanube Costa Rica maneja la firma digital automáticamente?
Sí. Al registrar su certificado .p12 de Hacienda en Alanube, la API firma automáticamente cada comprobante. Usted envía el payload JSON con los datos de la factura y Alanube devuelve el estado de Hacienda sin que su sistema gestione la firma XAdES. Conozca más en alanube.co.
Fuentes
- Ministerio de Hacienda de Costa Rica. (2024). Documentación API de comprobantes electrónicos v4.4. https://www.hacienda.go.cr/ATV/
- Dirección General de Tributación. (2019). Resolución DGT-R-033-2019 y versiones posteriores. https://tribunet.hacienda.go.cr/
- Banco Central de Costa Rica. (2024). Servicios de firma digital — certificados habilitados. https://www.bccr.fi.cr/
