Errores frecuentes de la API Hacienda Costa Rica y cómo resolverlos
Los errores api hacienda costa rica factura electrónica son los principales obstáculos al integrar el sistema de Hacienda. Sin embargo, la mayoría tienen una causa técnica específica y una solución directa. Por lo tanto, esta guía le permitirá resolver los errores más frecuentes sin necesidad de contactar soporte técnico.
La API del Ministerio de Hacienda utiliza la versión 4.4 del esquema XML desde 2024. En consecuencia, errores de versiones previas siguen apareciendo en integraciones que no han migrado correctamente. Asimismo, nuevos errores de validación surgieron con los campos adicionales de la versión 4.4.
Table of Contents
Cómo funciona la validación de Hacienda y por qué ocurren errores
La API de Hacienda valida cada comprobante en dos etapas. Sin embargo, muchos developers solo conocen la primera etapa y se sorprenden con los errores de la segunda.
- Validación estructural: Hacienda verifica que el XML cumple el esquema XSD de la versión 4.4. Por ejemplo, un campo con tipo de dato incorrecto genera error en esta etapa.
- Validación de negocio: Hacienda verifica coherencia entre los valores del comprobante. Sin embargo, esta validación puede demorar varios segundos adicionales en responder.
Adicionalmente, Hacienda responde con un mensaje XML de aceptación o rechazo. Por lo tanto, su sistema debe estar preparado para parsear la respuesta correctamente en ambos casos.
errores api hacienda costa rica factura electrónica: los más frecuentes en v4.4
Los siguientes errores representan el 80% de los rechazos reportados en integraciones con la API de Hacienda:
Error: COD-28 — Emisor no autorizado para este tipo de documento
Causa: El tipo de comprobante seleccionado no corresponde a la actividad económica registrada del emisor.
Solución: Verificar el tipo de comprobante permitido para el RUC en el ATV de Hacienda. Por ejemplo, una empresa sin actividad de exportación no puede emitir una Factura de Exportación Electrónica.
Error: COD-09 — Clave numérica ya fue utilizada
Causa: La clave numérica de 50 dígitos fue enviada en un comprobante anterior.
Solución: Implementar un contador de consecutivos persistido en base de datos. Sin embargo, nunca reiniciar el contador sin verificar cuál fue el último consecutivo aceptado por Hacienda.
Error: COD-01 — Firma digital inválida o expirada
Causa: El certificado de firma ha vencido o la firma fue generada con el algoritmo incorrecto.
Solución: Renovar el certificado en el ATV antes de su expiración. Adicionalmente, el algoritmo correcto es RSA-SHA256 con el certificado de firma del emisor.
Error: COD-17 — XML no cumple esquema XSD versión 4.4
Causa: El XML fue generado con el esquema de una versión anterior del estándar.
Solución: Descargar el XSD v4.4 oficial desde el portal de Hacienda y actualizar la referencia de esquema. Por lo tanto, ejecute pruebas de regresión completas antes de subir a producción.
Tabla de códigos de error más frecuentes
| Código | Descripción | Etapa de validación |
|---|---|---|
| COD-01 | Firma digital inválida o expirada | Estructural |
| COD-09 | Clave numérica ya utilizada | Negocio |
| COD-17 | XML no cumple XSD v4.4 | Estructural |
| COD-28 | Tipo de documento no autorizado | Negocio |
| COD-42 | Receptor no registrado en ATV | Negocio |
Sin embargo, algunos errores no devuelven un código específico. En consecuencia, revise también los logs del lado del servidor para capturar errores HTTP 500 que Hacienda no documenta.
Cómo depurar errores de validación paso a paso
Cuando reciba un error de Hacienda, siga este proceso de depuración. Por lo tanto, podrá identificar la causa raíz sin necesidad de enviar múltiples comprobantes de prueba.
- Capturar la respuesta XML completa de Hacienda. Sin embargo, no solo guarde el código de error: guarde el mensaje completo con todos sus campos.
- Identificar si es error estructural o de negocio. Por ejemplo, los errores COD-01 y COD-17 son siempre estructurales y se resuelven antes del reenvío.
- Validar el XML localmente contra el XSD v4.4. Adicionalmente, herramientas como xmllint permiten validar offline sin consumir intentos en Hacienda.
- Revisar el consecutivo y la clave numérica. Asimismo, confirme que el consecutivo no fue usado en un envío anterior, incluso si ese envío fue rechazado.
- Reenviar únicamente después de corregir el error. En consecuencia, evite reenviar el mismo comprobante sin modificaciones, ya que generará error COD-09.
Para entender mejor el funcionamiento completo de la API, revise la guía de API de facturación electrónica de Hacienda Costa Rica. Sin embargo, si ya tiene experiencia con la API, el flujo de depuración anterior aplica directamente a su integración.
Errores específicos de la versión 4.4 del esquema
La versión 4.4 introdujo campos nuevos obligatorios que no existían en versiones anteriores. Sin embargo, muchas integraciones omiten estos campos porque no generan error en el ambiente de pruebas. Por lo tanto, aparecen únicamente en producción con ciertos tipos de comprobantes.
- CodigoActividad: Código de actividad económica del emisor según el BCCR. Por ejemplo, el código 4799 corresponde a comercio al por menor no especializado.
- CondicionVenta: Debe coincidir exactamente con la condición de pago del comprobante. Adicionalmente, el valor “01” (contado) y “02” (crédito) son los más utilizados.
- PlazoCredito: Obligatorio cuando CondicionVenta es “02”. Sin embargo, el formato es texto libre en días: “30 días”, “60 días”.
Para entender todos los cambios entre versiones del esquema, consulte la guía de factura electrónica versión 4.4 en Costa Rica. Asimismo, ese artículo incluye la comparativa completa de campos entre versiones.
Preguntas frecuentes sobre errores de la API de Hacienda
¿Cuál es la diferencia entre un error estructural y uno de negocio en Hacienda?
Los errores estructurales ocurren cuando el XML no cumple el esquema XSD. Sin embargo, los errores de negocio ocurren cuando el XML es válido pero los datos son inconsistentes. Por lo tanto, primero valide el XML contra el XSD localmente antes de depurar errores de negocio.
¿Cómo puedo probar la integración sin afectar comprobantes reales?
Hacienda dispone de un ambiente de pruebas separado del productivo. Adicionalmente, las credenciales de prueba son diferentes a las de producción. Por ejemplo, puede solicitar acceso al ambiente de pruebas a través del ATV con su cédula jurídica del emisor.
¿Qué pasa si reenvío un comprobante rechazado sin corregirlo?
Hacienda genera el error COD-09 si la clave numérica ya fue usada, independientemente del resultado anterior. En consecuencia, debe generar una nueva clave numérica con el siguiente consecutivo. Como resultado, el comprobante rechazado queda en su sistema como no enviado y debe reemplazarse.
¿La API de Alanube maneja automáticamente los reintentos con Hacienda?
Sí. La API de Alanube gestiona el ciclo completo de envío, reintento y consulta de estado con Hacienda Costa Rica. Adicionalmente, devuelve los errores de Hacienda con descripción en español y acciones correctivas sugeridas. Por lo tanto, su equipo puede resolver errores sin necesidad de revisar la documentación oficial de Hacienda.
¿Necesita resolver errores de la API de Hacienda en su integración? Pruebe la API de Alanube Costa Rica con sandbox incluido: Pruebe la API de Alanube Costa Rica.
Fuentes
Ministerio de Hacienda de Costa Rica. (2024). Especificaciones técnicas del comprobante electrónico versión 4.4. Gobierno de Costa Rica. https://www.hacienda.go.cr/factura-electronica
