Observabilidad APIs de Facturación Electrónica LATAM

Un ISV que opera facturación electrónica en tres países simultáneamente no tiene forma de saber que su integración con la DGII de República Dominicana está fallando silenciosamente mientras el validador DIAN en Colombia responde con tiempos normales. Sin observabilidad específica para cada endpoint fiscal, los errores en producción se detectan por queja del cliente, no por el sistema de monitoreo. Y cuando la queja llega, el período de degradación ya tiene horas de antigüedad, los logs relevantes están dispersos y reconstruir la secuencia de eventos toma más tiempo del que tomó el incidente en sí.

Esta guía define qué métricas son críticas en APIs de facturación electrónica multi-país, cómo estructurar alertas por país y por autoridad fiscal, y qué patrones de logging permiten correlacionar un error del ISV con la respuesta exacta del validador. Al terminar, el equipo tendrá un baseline de observabilidad específico para entornos de facturación electrónica en LATAM, aplicable independientemente de si se usa un proveedor de API intermedio o integración directa con cada autoridad.

Por qué la observabilidad en APIs fiscales es diferente

Particularidades de los endpoints de validación fiscal

Los endpoints de los validadores fiscales tienen características que los diferencian de APIs comerciales estándar: no tienen SLA publicado, su latencia varía significativamente por horario y carga fiscal (los picos ocurren en los últimos días de cada mes y antes de cierres fiscales), su disponibilidad es distinta entre sandbox y producción, y sus mensajes de error mezclan códigos de infraestructura con códigos de negocio fiscal que requieren clasificación específica. Monitorear un validador DIAN con las mismas métricas que se monitorea un endpoint REST comercial produce falsos positivos y omite los indicadores más relevantes para la operación fiscal.

El costo de detectar degradación tarde

En facturación electrónica, una degradación de 30 minutos en el validador durante un cierre de mes puede representar cientos o miles de documentos en estado pendiente que el emisor no puede facturar, con impacto directo en flujo de caja. A diferencia de una API de pagos donde la degradación es inmediatamente visible por el usuario final, en facturación el fallo puede manifestarse como documentos en cola que nadie monitorea activamente. El tiempo entre el inicio del incidente y la primera alerta —MTTD, Mean Time to Detect— en entornos sin observabilidad específica suele superar los 45 minutos en ISVs de tamaño mediano.

Métricas críticas para monitorear APIs de facturación electrónica

Latencia por endpoint y por país

La métrica de latencia debe segmentarse al menos en tres dimensiones: país (Colombia/DIAN, República Dominicana/DGII, Costa Rica/Hacienda, Panamá/DGI), tipo de operación (transmisión, consulta de estado, habilitación) y percentil (p50, p95, p99). La mediana es útil para comparar tendencias, pero el p95 es el indicador operativo relevante: un p95 por encima de 8 segundos en transmisión indica que una fracción significativa de los documentos está experimentando esperas que activan timeouts en clientes mal configurados. Graficar la latencia por día de semana y por hora del día durante al menos cuatro semanas permite establecer el baseline de comportamiento normal para cada validador.

Tasa de rechazo y clasificación por código de error

La tasa de rechazo es la fracción de documentos transmitidos que la autoridad fiscal devuelve con error. Una tasa de rechazo alta puede indicar un bug en el generador de documentos del ISV, un cambio en el Anexo Técnico que no fue aplicado o degradación del validador que devuelve errores genéricos. Para distinguir entre estos casos, los rechazos deben clasificarse por código: errores de estructura XML (bugs del ISV), errores de firma digital (problema de certificado), errores de datos fiscales (bug de negocio) y errores de infraestructura del validador (problema del lado de la autoridad). Esta clasificación convierte una métrica agregada en señal accionable.

Disponibilidad diferenciada: sandbox vs. producción

Los ambientes de sandbox de los validadores fiscales en LATAM tienen disponibilidades históricamente menores que los de producción. Incluir el sandbox en el monitoreo es necesario para equipos de desarrollo que dependen de él para pruebas continuas, pero las alertas de sandbox no deben tener la misma severidad que las de producción. Una caída del sandbox DIAN que dura dos horas no es un incidente de producción, pero sí bloquea a los equipos de QA y debe registrarse. Mantener dashboards separados para sandbox y producción, con umbrales de alerta distintos, evita fatiga de alertas sin dejar ciegos a los equipos de desarrollo.

Arquitectura de alertas para entornos multi-país

Segmentación por autoridad fiscal

Cada autoridad fiscal debe tener su propio conjunto de alertas con parámetros calibrados para su comportamiento habitual. La DIAN colombiana y la DGII dominicana tienen patrones de latencia distintos, ventanas de mantenimiento en horarios diferentes y estructuras de error que no son comparables entre sí. Una alerta genérica de "latencia alta en facturación" que agrupa los cuatro países solo es útil si todos los países fallan al mismo tiempo; en escenarios de degradación parcial —que son los más frecuentes— la alerta genérica no dispara porque el promedio agregado no supera el umbral. La segmentación por autoridad fiscal es el primer requisito arquitectónico de un sistema de alertas efectivo para ISVs multi-país.

Umbrales de alerta recomendados por tipo de documento

Los umbrales de alerta deben diferenciarse por tipo de documento además de por país: las facturas de venta en tiempo real tienen una tolerancia de latencia mucho menor que las notas crédito o los documentos soporte que se procesan en batch nocturno. Un umbral razonable como punto de partida es: alerta de warning en p95 de latencia superior a 5 segundos, alerta crítica en p95 superior a 12 segundos o tasa de error de infraestructura del validador superior al 2% en una ventana de 5 minutos. Estos valores deben ajustarse con datos reales del entorno específico después de al menos dos semanas de operación monitoreada sin alertas.

Herramientas y stack técnico recomendado

OpenTelemetry como base de instrumentación

OpenTelemetry (OTel) es el estándar de facto para instrumentación de observabilidad en servicios distribuidos y es la base recomendada para instrumentar integraciones con validadores fiscales. Su ventaja en este contexto es la portabilidad: los datos de traces, métricas y logs se exportan a cualquier backend (Grafana, Datadog, New Relic, Prometheus) sin reescribir la instrumentación. Para una integración con validadores DIAN o DGII, el span crítico a instrumentar es el que envuelve la llamada HTTP al endpoint del validador: debe registrar la latencia total, el código de respuesta, el código de error fiscal si existe y el CUFE o identificador del documento, que actúa como clave de correlación entre el trace del ISV y el registro en el repositorio de la autoridad.

Integración con Grafana, Datadog y Prometheus

Para ISVs en etapa de crecimiento, el stack Prometheus + Grafana es la opción de menor costo de entrada: Prometheus recoge métricas de la capa de transmisión cada 15 segundos, Grafana las visualiza con dashboards por país y Alertmanager gestiona las notificaciones por severidad. Para ISVs con equipos de plataforma más maduros, Datadog ofrece correlación automática entre métricas, logs y traces sin configuración adicional, y su APM permite visualizar el trace completo de una transmisión desde el request del cliente hasta la respuesta de la autoridad fiscal. La infraestructura de facturación multi-país de Alanube expone métricas de disponibilidad y latencia por país que los ISVs integrados pueden consumir directamente via webhooks de estado, reduciendo la instrumentación necesaria en la capa del cliente.

Patrones de logging estructurado en APIs fiscales

Campos mínimos en cada log de transmisión

Un log de transmisión efectivo debe incluir como mínimo: el identificador del documento (CUFE en Colombia, NCF/e-CF en RD, número DGI en Panamá), el país y la autoridad fiscal destino, el timestamp de inicio y fin de la llamada (no solo uno), el código de respuesta HTTP y el código de error fiscal si existe, y el identificador de la organización o emisor. Con estos campos, cualquier incidente puede reproducirse y diagnosticarse con una consulta de logs sin necesidad de acceder a sistemas de negocio. Los campos de identificación del documento son especialmente críticos porque permiten correlacionar el log del ISV con el registro del repositorio de la autoridad fiscal durante una auditoría.

Correlación de trazas entre ISV y validador fiscal

La correlación entre el trace del ISV y el estado del documento en el validador fiscal requiere que el identificador del documento sea el eje de correlación, no el ID de sesión HTTP ni el trace ID de OTel. El CUFE en Colombia y el número de e-CF en República Dominicana son identificadores estables que persisten en el repositorio de la autoridad y en los logs del ISV, lo que los convierte en la clave de correlación natural para diagnósticos post-incidente. Estructurar todos los logs de transmisión alrededor de este identificador —como campo indexado de primer nivel en el sistema de logs— permite reconstruir el historial completo de cualquier documento en segundos, independientemente de cuántos servicios participaron en su generación y transmisión.

Preguntas frecuentes

¿Cuál es la métrica más importante para monitorear la salud de una integración con un validador fiscal? La tasa de error por código fiscal clasificado es la métrica con mayor señal. La latencia indica degradación del validador, pero no distingue entre un problema de infraestructura de la autoridad y un bug en el generador de documentos del ISV. La tasa de error desglosada por tipo de código —infraestructura, estructura XML, firma, datos fiscales— permite identificar inmediatamente si el problema es del lado del ISV o del validador, lo cual determina la acción correctiva. Sin esta clasificación, el diagnóstico depende de revisar cada rechazo individualmente, lo que no escala en volúmenes de producción.

¿Cómo puedo diferenciar degradación del validador fiscal de un bug en mi integración? El indicador más directo es la variación en el tipo de errores: si los rechazos son consistentemente del mismo código fiscal (error en un campo específico del XML), el problema es del ISV; si los errores son de tipo genérico de infraestructura o timeouts que no existían el día anterior, el problema es del validador. Una segunda señal es la tasa de error en el sandbox: si el sandbox no presenta errores equivalentes con los mismos documentos, el validador de producción es la fuente. Mantener un healthcheck automatizado que transmite un documento de prueba conocido contra el validador cada 5 minutos es el mecanismo más simple para detectar degradación del lado de la autoridad.

¿Qué diferencia hay entre monitorear una API fiscal y monitorear una API comercial estándar? Las APIs comerciales tienen SLA publicados, códigos de error estandarizados (HTTP semantics) y disponibilidad cercana al 99.9%. Los validadores fiscales en LATAM no tienen SLA público, mezclan códigos HTTP con códigos de error propietarios de cada autoridad y presentan variaciones de disponibilidad ligadas al calendario fiscal. Esto implica que los umbrales, la clasificación de errores y los dashboards deben construirse con conocimiento del comportamiento específico de cada validador —DIAN, DGII, Hacienda CR, DGI Panamá— y no pueden transferirse directamente desde configuraciones de monitoreo de APIs comerciales sin ajuste.

¿Es posible implementar observabilidad multi-país sin un proveedor de APM de pago? Sí. El stack Prometheus + Grafana + Alertmanager cubre las necesidades de métricas, dashboards y alertas sin costo de licencia. La instrumentación del código puede hacerse con las librerías cliente de Prometheus en cualquier lenguaje principal. La limitación respecto a soluciones de APM de pago es la ausencia de correlación automática entre métricas, logs y traces, que en stacks de código abierto requiere configuración explícita. Para ISVs con menos de 50.000 documentos diarios por país, el stack de código abierto es suficiente si se instrumenta desde el inicio; para volúmenes mayores o equipos con menor capacidad de configuración, el costo de una herramienta como Datadog se amortiza rápidamente frente al costo de incidentes no detectados.

Observabilidad en APIs de Facturación Electrónica LATAM: Métricas, Alertas y Monitoreo