Observabilidad y Logging en la Integración con la API de Hacienda Costa Rica

Cuando un documento transmitido a Hacienda regresa con estado rechazado y el equipo técnico no dispone de ningún log del payload enviado, del código de respuesta ni de la clave numérica involucrada, el tiempo de diagnóstico se multiplica. En entornos de producción con decenas de miles de documentos mensuales, esa falta de visibilidad se traduce en documentos inválidos que el emisor descubre días después de que el cliente ya los recibió.

Esta guía describe cómo implementar observabilidad, logging estructurado y alertas en la integración con la API de Hacienda Costa Rica. Al terminar de leerla, usted tendrá un modelo de datos de logs, las métricas mínimas para producción y una estrategia de alertas que reduce el tiempo de detección de errores de horas a minutos.

Por qué la observabilidad es crítica en la API de Hacienda Costa Rica

El flujo asíncrono como fuente de opacidad

La API de Hacienda Costa Rica opera en dos pasos. El primer paso es la recepción: el emisor envía el XML firmado al endpoint de recepción y obtiene una respuesta HTTP 201 que confirma que el documento fue recibido. Ese 201 no indica aceptación —solo recepción. El segundo paso es la validación: Hacienda procesa el documento de forma asíncrona y emite un mensaje de respuesta que usted debe consultar mediante polling al endpoint de consulta, o recibir a través del mensaje de respuesta del receptor. Cuando la integración no registra el estado de cada etapa de este flujo, el equipo técnico opera sin visibilidad: no puede saber si el documento fue aceptado, rechazado por error de firma digital o rechazado por un campo fuera de rango del esquema v4.4.

Consecuencias operativas de no tener trazabilidad

Un ISV que no registra los payloads de request y response en cada transmisión enfrenta tres consecuencias directas. Primero, no puede reproducir el error: sin el XML original enviado ni la respuesta de Hacienda, el diagnóstico depende de una reconstrucción aproximada basada en memoria del desarrollador. Segundo, no puede auditar: si un cliente reporta que recibió un documento con datos incorrectos, el ISV no puede verificar qué fue exactamente lo que se transmitió ni cuándo. Tercero, no puede anticipar: sin métricas de tasa de rechazo, el equipo descubre los problemas cuando el volumen de documentos rechazados ya es crítico y el impacto en los clientes es visible. Estos tres déficits tienen un costo operativo medible: tiempo de resolución más largo, mayor carga de soporte y riesgo de documentos inválidos no detectados a tiempo.

Estructura de logs recomendada para cada transacción con Hacienda

Qué registrar en el request de transmisión

Cada vez que la integración envía un documento a Hacienda, el log debe capturar como mínimo: la clave numérica del documento (50 dígitos), el tipo de documento (01=factura electrónica, 03=nota débito, 04=nota crédito, 09=tiquete electrónico), el número de cédula del emisor, el monto total del documento en colones, la fecha y hora de transmisión en UTC, el endpoint utilizado, el código de respuesta HTTP recibido y el cuerpo completo de la respuesta de recepción de Hacienda. Registrar el XML firmado en su totalidad es recomendable solo si el sistema de logs garantiza cifrado at-rest, dado que el documento puede contener datos personales cubiertos por la Ley 8968 de Protección de la Persona frente al Tratamiento de sus Datos Personales. Si el cifrado no está disponible, registrar un hash SHA-256 del payload como identificador forense es suficiente para diagnóstico y trazabilidad.

Qué registrar en la consulta de estado

El polling al endpoint de consulta de estado debe generar su propio evento de log, independiente del log de transmisión. Este evento debe incluir: timestamp de la consulta en UTC, clave numérica consultada, estado devuelto por Hacienda (aceptado, rechazado, en proceso) y, en caso de rechazo, el detalle completo del mensaje de error. El campo de detalle del error es el más valioso para el diagnóstico: contiene el código específico de Hacienda que orienta la corrección, como 'ERR-001: Clave numérica duplicada' o 'ERR-054: Firma digital inválida'. El log de polling debe vincularse al log de transmisión mediante la clave numérica como identificador común, de modo que sea posible reconstruir el ciclo de vida completo de cada documento para auditoría.

Estrategia de polling y manejo del estado asíncrono

Frecuencia de consulta con backoff exponencial

Hacienda no publica un SLA oficial de validación, pero en condiciones normales los documentos son procesados entre 3 y 60 segundos. Una estrategia de polling con backoff exponencial es más eficiente que un intervalo fijo: el primer intento puede ejecutarse a los 5 segundos de la transmisión, el segundo a los 15, el tercero a los 45, y a partir del cuarto intento cada 120 segundos. Si el documento permanece en estado 'en proceso' por más de 10 minutos, la integración debe generar una alerta de revisión manual: este tiempo excede el comportamiento esperado y puede indicar un incidente del lado de Hacienda o un error de transmisión que no generó respuesta visible. El número máximo de reintentos de consulta recomendado es 10 antes de marcar el documento como 'estado indeterminado' y escalar al equipo técnico para resolución manual.

Cómo evitar documentos duplicados durante el reintento

La clave numérica de 50 dígitos en Costa Rica cumple una función de idempotencia natural: Hacienda rechaza con error cualquier documento cuya clave ya haya sido procesada, independientemente del contenido. Esto protege contra el escenario de reintento del envío: si la integración vuelve a transmitir un documento con la misma clave, Hacienda devuelve error de duplicado y no lo procesa como nuevo. El riesgo real de duplicación no está en los reintentos al mismo endpoint, sino en la generación accidental de dos registros con contenido idéntico pero claves diferentes —por ejemplo, cuando dos procesos paralelos generan la clave simultáneamente sin bloqueo. Para evitarlo, el sistema debe garantizar que la clave numérica se genere una única vez por transacción comercial y quede persistida en la base de datos antes de intentar cualquier transmisión.

Métricas mínimas para una integración en producción

Qué medir y con qué granularidad

Las métricas operativas mínimas para una integración con Hacienda en producción son cinco: tasa de aceptación (documentos aceptados sobre documentos transmitidos en un período dado), tasa de rechazo clasificada por categoría de error (firma digital, estructura del XML, clave duplicada, campo fuera de rango), latencia de validación promedio y percentil 95, volumen diario de transmisiones por tipo de documento, y número de documentos en estado 'en proceso' por más de 5 minutos. Estas métricas deben calcularse con granularidad horaria en producción para detectar anomalías rápidamente, y con granularidad diaria para reportes operativos. Cualquier sistema de observabilidad que procese logs estructurados en JSON puede alimentar estas métricas: Grafana con Prometheus, Datadog, New Relic o equivalentes que el ISV ya tenga en su stack.

Umbrales de alerta recomendados para ISVs en Costa Rica

Los umbrales deben calibrarse según el volumen operativo de cada ISV, pero hay valores de referencia razonables como punto de partida. Una tasa de rechazo superior al 2% en una ventana de 15 minutos debe generar una alerta de nivel warning: puede indicar un certificado de firma digital próximo a expirar, un cambio en el esquema del XML o un problema de codificación de caracteres. Una tasa de rechazo superior al 10% debe generar una alerta crítica: probablemente hay un error sistémico en la generación de documentos que afecta a todos los emisores activos en la plataforma. Documentos en estado 'en proceso' por más de 15 minutos también deben generar alerta, pues pueden reflejar un incidente del lado de Hacienda que conviene documentar y notificar a los clientes antes de que ellos reporten el problema directamente al soporte.

Esquema de log JSON y opciones de implementación

Campos mínimos del evento de log por transmisión

Un log estructurado en JSON por evento de transmisión debe incluir como mínimo: event_type (hacienda_transmission o hacienda_query), document_key (clave numérica de 50 dígitos), document_type (código del tipo de documento), issuer_id (cédula del emisor), total_amount (monto en la moneda del documento), transmission_timestamp (ISO 8601 UTC), http_status (código de respuesta HTTP), hacienda_status (received, accepted, rejected o processing), error_code (código de error de Hacienda cuando aplica), error_detail (descripción del error cuando aplica) y payload_hash (SHA-256 del XML enviado). Este esquema está marcado como pseudocódigo: la implementación específica depende del lenguaje, el ORM y el sistema de logs del ISV. Los campos event_type, document_key y hacienda_status son mínimos no negociables para cualquier implementación funcional.

Delegación de la observabilidad a un proveedor de API

Algunos ISVs optan por no implementar la capa de observabilidad directamente, sino por delegar la integración con Hacienda a un proveedor de API que ya exponga logs, estados de documentos y métricas a través de su propio dashboard o API de gestión. Esta aproximación reduce el tiempo de implementación y transfiere la responsabilidad de disponibilidad al proveedor. Para ISVs con volúmenes superiores a 10.000 documentos mensuales en Costa Rica, la API de facturación electrónica para Costa Rica de Alanube expone endpoints de consulta de estado y registros de eventos que permiten construir un dashboard de monitoreo sobre la actividad de transmisión. Esta opción es técnicamente válida, aunque requiere evaluar que el proveedor garantice retención de logs suficiente para auditorías fiscales —mínimo 5 años según la normativa de Hacienda Costa Rica.