Llave criptográfica Hacienda Costa Rica: errores y soluciones
Su sistema envía el XML al ATV de Hacienda y recibe un error de firma. El documento está bien formado, el XML cumple el esquema v4.4, pero la respuesta sigue siendo rechazado. En el 70% de los casos, el problema no está en la estructura del XML sino en la llave criptográfica: el archivo .p12, su PIN, o cómo se está usando para firmar con XAdES-XL.
Esta guía cubre los errores más frecuentes relacionados con la llave criptográfica de Hacienda Costa Rica, su diagnóstico y la solución técnica para cada uno. Incluye verificación del archivo .p12, manejo correcto del PIN, y los requisitos de firma XAdES-XL que exige el esquema v4.4.
Qué es la llave criptográfica de Hacienda
La llave criptográfica de Hacienda Costa Rica es un archivo en formato PKCS#12 (.p12 o .pfx) que contiene dos componentes inseparables: el certificado digital del emisor (con su clave pública) y la clave privada con la que se firman los documentos electrónicos. Hacienda la emite a través del portal ATV una vez que el contribuyente completa el proceso de habilitación para facturación electrónica. Sin este archivo, ningún documento puede ser firmado con XAdES-XL y por tanto no puede ser aceptado por el ATV.
Error 1: PIN incorrecto al cargar el .p12
Error: java.security.UnrecoverableKeyException: Get Key failed: Given final block not properly padded (Java) / OpenSSL: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt (Python)
Causa: El PIN del archivo .p12 no coincide con el que se usó al generarlo en el portal de Hacienda. Esto es común cuando se trabaja con múltiples contribuyentes o cuando el archivo fue regenerado y el PIN fue actualizado en el sistema pero no en todas las instancias del servidor.
Solución:
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.
Error 2: Certificado vencido
Error: Hacienda responde: cod-respuesta: 02 — Certificado digital vencido o no vigente
Causa: Los certificados de Hacienda tienen vigencia de 1 a 2 años. Una vez vencidos, Hacienda rechaza todos los documentos firmados con ese certificado, incluyendo los emitidos con fecha anterior al vencimiento si no han sido enviados aún.
Diagnóstico:
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.
Para renovar el certificado, el contribuyente debe ingresar al portal del ATV de Hacienda con su identificación tributaria y solicitar la regeneración de la llave criptográfica. El proceso toma menos de 10 minutos y genera un nuevo archivo .p12 con un nuevo PIN.
Error 3: Firma XAdES-XL incompleta o inválida
Error: Hacienda responde: cod-respuesta: 04 — Firma digital no válida o estructura inválida
Causa: El esquema v4.4 de Hacienda requiere firma XAdES-XL (nivel XL = Extended Long-term), que incluye no solo la firma básica sino también el sello de tiempo (timestamp) del servidor TSA y las respuestas OCSP del estado del certificado. Sistemas que implementan solo XAdES-BES (básico) son rechazados bajo v4.4.
Diferencia entre niveles XAdES:
| Nivel XAdES | Componentes incluidos | Requerido por Hacienda CR |
|---|---|---|
| XAdES-BES | Firma + hash del documento + info del firmante | No (insuficiente para v4.4) |
| XAdES-T | XAdES-BES + sello de tiempo (TSA) | No (insuficiente) |
| XAdES-XL | XAdES-T + respuesta OCSP + CRL del certificado | ✅ Sí — obligatorio en v4.4 |
La implementación de XAdES-XL requiere realizar dos llamadas adicionales durante la firma: una al servidor TSA de Hacienda para obtener el sello de tiempo, y una al servicio OCSP para verificar el estado del certificado. Ambas respuestas deben embeberse en el XML firmado en los nodos xades:UnsignedSignatureProperties.
Error 4: Encoding del PIN con caracteres especiales
Error: El PIN funciona en el sistema de pruebas pero falla en producción, o funciona en Linux pero no en Windows.
Causa: Algunos PINs de Hacienda incluyen caracteres especiales (!, @, #, ñ, ü) que se codifican diferente según el sistema operativo o el framework usado para leer las variables de entorno.
Solución:
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.
Error 5: Archivo .p12 corrupto o con formato incorrecto
Error: SSLError: [SSL: PEM_LIB] PEM lib (_ssl.c:4065) o Error loading PKCS#12 data
Causa: El archivo .p12 fue transferido a través de un canal que modificó el contenido binario (ej: un correo electrónico que lo convirtió a texto, FTP en modo ASCII en lugar de binario).
Verificación: Un archivo .p12 válido siempre empieza con los bytes 30 82 (en hexadecimal). Si el archivo tiene una cabecera de texto o comenzó con algo diferente durante la transferencia, está corrupto y debe descargarse nuevamente desde el portal ATV de Hacienda.
FAQ
¿Dónde se obtiene la llave criptográfica en Hacienda Costa Rica?
La llave criptográfica se obtiene en el portal ATV de Hacienda (atv.hacienda.go.cr), en la sección “Factura Electrónica” → “Gestión de Llave Criptográfica”. El contribuyente ingresa con su cédula (persona física) o cédula jurídica (persona jurídica) y PIN del ATV. El proceso genera el archivo .p12 y un PIN asociado que debe conservarse de forma segura — Hacienda no lo almacena.
¿Cómo manejar múltiples contribuyentes con llaves diferentes?
Cuando el sistema maneja emisión para múltiples contribuyentes (modelo SaaS o ISV), cada contribuyente tiene su propio archivo .p12 y PIN. La recomendación técnica es almacenar cada archivo en un sistema de secretos (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) usando el NIT o cédula del contribuyente como identificador, y cargarlo en memoria solo durante el proceso de firma — nunca escribirlo a disco temporal. La rotación de certificados debe monitorearse por contribuyente con alertas a 30 y 7 días antes del vencimiento.
¿Qué pasa si se pierde el PIN de la llave criptográfica?
Si se pierde el PIN, el archivo .p12 es irrecuperable — no hay forma de extraer la clave privada sin el PIN correcto. El contribuyente debe ingresar al ATV de Hacienda y generar una nueva llave criptográfica, lo que invalida la anterior. Los documentos ya firmados con la llave anterior siguen siendo válidos, pero todos los nuevos documentos deben firmarse con el nuevo archivo .p12.
¿La API de Alanube gestiona la firma XAdES-XL por el emisor?
Sí. El sistema emisor envía a Alanube el payload JSON del documento y las credenciales de la llave criptográfica de forma segura. Alanube gestiona la firma XAdES-XL completa, incluyendo la obtención del sello de tiempo del servidor TSA de Hacienda y la validación OCSP del certificado. El emisor no necesita implementar la firma localmente. Más información en alanube.co.
Fuentes
- Ministerio de Hacienda de Costa Rica. (2024). Resolución MH-DGT-RES-0027-2024 — Comprobantes electrónicos versión 4.4. Hacienda. https://www.hacienda.go.cr/contenido/12626-comprobantes-electronicos
- Ministerio de Hacienda de Costa Rica. (2023). Manual técnico para desarrolladores — Versión 4.4. Dirección General de Tributación.
- ETSI. (2021). XAdES digital signatures — ETSI EN 319 132-1. European Telecommunications Standards Institute.
