Checklist técnico para evaluar un proveedor de facturación electrónica en Costa Rica

Cuando un ISV en Costa Rica integra facturación electrónica por primera vez, el primer obstáculo suele ser el mismo: el formato XML-CR tiene particularidades que ningún proveedor documenta completamente — la clave numérica de 50 dígitos, la firma digital con el certificado del Ministerio de Hacienda, los plazos de transmisión y los métodos de consulta ante el ATV. Quienes eligen proveedor solo por precio descubren esas brechas en producción.

Este checklist le ofrece 8 criterios técnicos para evaluar cualquier proveedor de API de facturación electrónica en Costa Rica antes de iniciar la integración. Cada criterio incluye una prueba concreta que usted puede ejecutar con acceso al sandbox del proveedor.

Criterio 1 — Soporte para XML-CR versión 4.4 y actualizaciones de Hacienda

El Ministerio de Hacienda de Costa Rica ha publicado varias versiones del esquema XML-CR. La versión 4.4 introdujo cambios en campos obligatorios y en la estructura de algunos comprobantes. Un proveedor que no esté actualizado a la versión vigente genera documentos que Hacienda puede rechazar durante la validación. Verificar explicitamente cuál versión del esquema está implementando el proveedor antes de iniciar el sandbox.

Verificación mínima de versión y cobertura

Antes de evaluar el sandbox:
☐ El proveedor implementa XML-CR versión 4.4 (la versión vigente al 2026)
☐ Soporte para Factura Electrónica (FE), Tiquete Electrónico (TE) y Nota de Crédito (NCE)
☐ Soporte para Nota de Débito Electrónica (NDE) si el caso de uso lo requiere
☐ El proveedor tiene historial documentado de actualizaciones al esquema
☐ El changelog del proveedor incluye las fechas de implementación de cada versión XML-CR

Criterio 2 — Generación y validación de la clave numérica

La clave numérica de 50 dígitos es el identificador único de cada comprobante en Costa Rica. Su estructura combina el código del país, el día, mes y año, el cédula del emisor, el número consecutivo y otros campos definidos por Hacienda. Una clave mal formada causa rechazo inmediato durante la validación en el ATV. El proveedor debe generar la clave internamente y exponerla en la respuesta de la API.

Prueba de validación de clave numérica

// Respuesta esperada de emisión exitosa en Costa Rica
{
  "invoiceId": "FE-001-001-000000001",
  "claveNumerica": "<50 dígitos exactos según esquema Hacienda>",
  "status": "aceptado",
  "haciendaResponse": {
    "ind-estado": "aceptado",
    "mensaje-hacienda": "Comprobante aceptado"
  },
  "xmlFirmadoUrl": "https://...",
  "pdfUrl": "https://..."
}
// Red flag: claveNumerica ausente, de longitud distinta a 50 caracteres,
// o respuesta de Hacienda ausente en la respuesta de la API

Criterio 3 — Firma digital y certificado de Hacienda

En Costa Rica, el comprobante electrónico debe estar firmado con el certificado digital del emisor, emitido por la infraestructura de llave pública del MICITT y reconocido por el Ministerio de Hacienda. El proveedor debe gestionar esa firma de forma transparente para el ISV. Verificar cómo el proveedor gestiona los certificados de sus clientes: si los custodia de forma segura, si el proceso de renovación está documentado y si hay alertas cuando el certificado esté próximo a vencer.

Qué verificar sobre la firma digital

Checklist de firma digital:
☐ El proveedor acepta el certificado digital del emisor (PKCS#12 / .p12)
☐ El certificado se almacena de forma segura (HSM o equivalente)
☐ Hay alertas automáticas cuando el certificado está próximo a vencer
☐ El proveedor documenta el proceso de renovación del certificado
☐ El XML firmado está disponible para descarga o consulta del ISV

Criterio 4 — Transmisión al ATV y plazo de validación

El Administrador Tributario Virtual (ATV) del Ministerio de Hacienda es el sistema de recepción de comprobantes electrónicos en Costa Rica. La norma establece que el comprobante debe transmitirse al ATV dentro de los plazos definidos por Hacienda. Un proveedor que no transmite en tiempo, que no gestiona reintentos cuando el ATV está lento, o que no notifica al ISV cuando un comprobante no fue transmitido a tiempo, genera riesgo fiscal para el emisor.

Criterio 5 — Mensajes de error de Hacienda traducidos a errores accionables

Hacienda Costa Rica devuelve mensajes de error con códigos específicos cuando rechaza un comprobante. Los proveedores maduros traducen esos mensajes a errores propios con el campo afectado identificado; los menos desarrollados reenvían el XML de respuesta de Hacienda sin procesar. La diferencia impacta directamente el tiempo que el equipo tarda en diagnosticar y corregir un rechazo en producción.

Criterio 6 — Webhooks y notificación de cambios de estado

Costa Rica usa un modelo de validación que en algunos casos puede ser asíncrono — el ATV puede tardar en devolver la respuesta definitiva. Sin webhooks nativos, usted debe implementar polling para consultar el estado de cada comprobante. A escala, el polling genera carga innecesaria y puede producir inconsistencias en la gestión de estados. Verificar que el proveedor ofrezca webhooks con firma para notificar cambios de estado del comprobante.

Criterio 7 — Historial de actualizaciones y SLA normativo

El Ministerio de Hacienda de Costa Rica ha publicado múltiples versiones del esquema XML-CR y de las resoluciones de facturación electrónica. Cada actualización puede implicar cambios en campos obligatorios, en la estructura del XML o en los plazos de transmisión. Un proveedor que no tiene un SLA claro de implementación normativa expone a sus clientes a rechazos durante el período de transición entre versiones.

Preguntar explícitamente: ¿en cuántos días implementó el proveedor el último cambio del Ministerio de Hacienda? ¿Los clientes reciben notificación antes de que entre en vigor el cambio? ¿El proveedor tiene un changelog público con fechas de implementación? Un proveedor maduro responde esas preguntas con evidencia documentada, no con generalidades.

Criterio 8 — Documentación y tiempo al primer comprobante funcional

El esquema XML-CR tiene detalles que no son obvios sin documentación clara: la estructura de la clave numérica, el proceso de firma con el certificado del emisor, la transmisión al ATV y la gestión del estado del comprobante. Un proveedor con buena DX debe ofrecer acceso al sandbox sin pasar por el equipo comercial, ejemplos de código funcionales para los tipos de comprobante más comunes y una guía de onboarding que cubra el ciclo completo.

Para comparar cómo se aplican estos criterios en los otros mercados de la región, consultar la guía 5 criterios técnicos para elegir una API de facturación en LATAM.

Preguntas frecuentes

¿Cuál es la diferencia entre la clave numérica y el número consecutivo del comprobante en Costa Rica?

El número consecutivo es la secuencia interna del emisor para identificar el comprobante dentro de su sistema (por ejemplo, FE-001-001-000000001). La clave numérica de 50 dígitos es el identificador global que Hacienda usa para registrar el comprobante en el ATV — incluye código de país, fecha, cédula del emisor, tipo de comprobante, número consecutivo y un componente de seguridad. Ambos identificadores son obligatorios y deben incluirse en el XML del comprobante. Un proveedor que no genera la clave numérica correctamente produce documentos que Hacienda rechaza de forma automática.

¿Cómo puedo verificar que el proveedor transmite correctamente al ATV en el sandbox?

La verificación más confiable es emitir un comprobante en el sandbox y revisar la respuesta: debe incluir el campo ind-estado de Hacienda con el valor “aceptado” o “aceptado-parcial”, y la clave numérica del comprobante. Si la respuesta de la API no incluye el ind-estado de Hacienda, el sandbox no está transmitiendo al ATV de pruebas de Hacienda — está simulando la respuesta localmente, lo que significa que los errores reales del ATV aparecerán por primera vez en producción.

¿Qué diferencia hay entre un comprobante aceptado y uno aceptado-parcial en Hacienda?

Hacienda Costa Rica puede devolver tres estados para un comprobante: aceptado (documento validado completamente), aceptado-parcial (documento con observaciones no bloqueantes que igualmente queda registrado) y rechazado (documento inválido que no queda registrado). El estado aceptado-parcial es el más problemático porque el comprobante es válido legalmente pero tiene campos con advertencias que pueden volverse rechazos cuando Hacienda endurezca las validaciones. El proveedor debe notificar los tres estados de forma distinta al ISV.

¿Es posible usar la misma API para emitir comprobantes en Costa Rica y en otros países de Centroamérica sin adaptar el código?

Depende del proveedor. Los que ofrecen una API multi-país gestionan internamente las diferencias entre el esquema XML-CR de Costa Rica y los esquemas de los demás países — el ISV envía los campos del comprobante y el proveedor construye el documento según el estándar local. Los que no tienen esa abstracción requieren payloads completamente distintos por país. Antes de integrar un proveedor multi-país, verificar en el sandbox si la API abstrae las diferencias entre Costa Rica y los demás mercados, o si delega esa complejidad al ISV.

Este checklist es la aplicación Costa Rica de los 5 criterios técnicos generales para LATAM. La documentación técnica oficial del sistema ATV está disponible en el Ministerio de Hacienda de Costa Rica.