Cómo Transmitir Documentos Electrónicos a Hacienda Costa Rica: Guía Técnica

La transmisión de un documento electrónico al Ministerio de Hacienda en Costa Rica no es un único POST que devuelve aprobación o rechazo. Es un flujo asincrónico con varios pasos, donde el documento se envía, se acusa recibo, y posteriormente se consulta el resultado del validador. Conocer ese flujo completo es la diferencia entre una integración estable y una que pierde documentos en limbo cuando el primer paso devuelve un acuse positivo pero el segundo nunca se consulta.

Esta guía describe paso a paso el flujo técnico de transmisión a Hacienda Costa Rica para documentos v4.4: autenticación, envío del XML firmado, recepción del acuse, consulta de estado, manejo de respuestas posibles, y patrones recomendados para asegurar que ningún documento queda sin estado resuelto.

Flujo asincrónico de transmisión

Por qué es asincrónico

Hacienda opera con un modelo asincrónico para no bloquear el lado del emisor durante la validación. Cuando su sistema envía un documento, Hacienda responde casi inmediatamente con un acuse de recibo que confirma que el documento llegó y entró en cola de validación. La aprobación o rechazo definitivo llega después y se obtiene consultando el estado por la clave del documento. Esto permite volúmenes altos sin congelar conexiones.

Pasos del flujo completo

El flujo completo tiene cinco pasos principales: autenticar contra el servidor de identidad y obtener token, construir el XML firmado v4.4 con la clave del documento, transmitir al endpoint de recepción de Hacienda, recibir acuse de recibo confirmando ingreso a cola, consultar periódicamente el estado final del documento hasta recibir respuesta de validación. Cada paso tiene posibilidades de falla específicas que conviene manejar individualmente.

Autenticación contra Hacienda

Token OAuth y credenciales

La autenticación usa OAuth contra el servidor de identidad de Hacienda. Las credenciales (client_id, client_secret, usuario, contraseña) se obtienen al habilitarse como facturador en el portal ATV. El sistema envía una solicitud al endpoint de tokens y recibe un access_token válido por un período limitado (típicamente minutos). Ese token va en el header Authorization de las llamadas posteriores.

Renovación periódica del token

El token expira tras un período configurable. La práctica recomendada es solicitar un nuevo token unos segundos antes de la expiración del actual para evitar fallos en transmisiones simultáneas. Un patrón común es mantener el token en caché con TTL menor que el de Hacienda (por ejemplo, 50 minutos si el token dura 60) y renovarlo proactivamente. Almacenar el token en código o en logs es riesgo de seguridad: debe vivir en memoria o en un secret store.

Envío del documento

Endpoint REST y formato del payload

El endpoint de recepción de Hacienda acepta POST con el XML firmado en el body. El payload va envuelto en JSON con campos específicos: clave del documento, fecha de emisión, identificación del emisor, identificación del receptor, y el XML mismo codificado en base64. El código de respuesta HTTP del endpoint es 202 (Accepted) cuando el documento entra correctamente a cola de validación.

Acuse de recibo confirma ingreso, no validez

El acuse de recibo significa que Hacienda recibió el documento y entró a su flujo de validación, no que el documento es válido. La validación real ocurre asincrónicamente y puede tardar entre segundos y horas según la carga del sistema. Tomar el acuse de recibo como aprobación final es un error común que deja documentos en limbo cuando la validación posterior rechaza.

Consulta del estado de validación

Endpoint de consulta por clave

Para conocer el estado de validación, su sistema consulta un endpoint específico de Hacienda pasando la clave del documento como parámetro. La respuesta incluye el estado actual (procesando, aceptado, rechazado) y, cuando es definitivo, el detalle del resultado: mensaje de Hacienda, errores específicos si los hubo, fecha de la decisión. La consulta es idémpotente: puede ejecutarse varias veces sin efectos colaterales.

Estados posibles devueltos

Los estados principales son: procesando (aún en cola, intentar de nuevo después), aceptado (Hacienda validó el documento y es legalmente válido), rechazado (Hacienda detectó inconsistencia y el documento no es válido), error (problema técnico, requiere reenvío). Cada estado debe disparar acciones distintas en su sistema: registrar el resultado, notificar al receptor si es aceptado, abrir incidencia si es rechazado.

Patrones recomendados de polling y manejo

Polling con backoff exponencial

Si su sistema implementa polling propio contra el endpoint de consulta, la práctica recomendada es backoff exponencial: primer intento a los 5 segundos, segundo a los 15 segundos, tercero al minuto, cuarto a los 5 minutos, hasta un límite máximo. Esto reduce la carga sobre Hacienda y respeta los rate limits sin desperdiciar recursos del lado del emisor. Para documentos que llevan horas en "procesando", convocar revisión manual.

Persistencia de la clave del documento

Inmediatamente después del acuse de recibo, su sistema debe persistir la clave del documento en la base de datos junto con el estado pendiente de validación. Si el sistema cae antes de consultar el estado final, debe poder retomar la consulta al reiniciarse. La clave es lo único que identifica el documento ante Hacienda; perderla significa documento huérfano sin forma de conocer su estado.

Reconciliación periódica

Adicional al polling activo, conviene un job programático (cada hora o cada turno) que consulte el estado de todos los documentos con estado pendiente y los actualice. Esto cubre los casos en que el polling activo se interrumpió por fallo del worker o por reinicio del servidor. La reconciliación periódica es red de seguridad, no mecanismo primario.

Preguntas frecuentes