API y empresas

Detectar una regresión de cobertura

Menos resultados puede significar menos infracciones o una fuente que dejó de contestar. La diferencia no aparece en el código de estado: hay que buscarla por fuente y con casos de resultado conocido.

Foto de Marco FerreiroMarco FerreiroAutor en multas.ar
4 min de lectura
Mostrador de una oficina pública con una hilera de ventanillas de madera: unas pocas abiertas y la mayoría con la persiana baja, bajo luz natural lateral.
Mostrador de una oficina pública con una hilera de ventanillas de madera: unas pocas abiertas y la mayoría con la persiana baja, bajo luz natural lateral.

Una integración puede seguir funcionando y devolver menos de lo que devolvía la semana pasada. No hay error, no hay alerta, no hay reclamo: las consultas responden rápido y los reportes salen limpios. Lo que cambió es cuántas fuentes contestaron de verdad, y eso no aparece en el código de estado.

Llamamos regresión de cobertura a la caída sostenida en el conjunto de fuentes que respondieron con datos utilizables, no explicada por un cambio real en la calle. No es lo mismo que una baja en la cantidad de infracciones: una jurisdicción puede haber emitido menos actas ese mes. La regresión está del lado del proceso de consulta, no del hecho.

La dificultad es que se disfraza de buena noticia. Menos resultados se lee como menos deuda.

Por qué el código de estado no la detecta

Según la semántica de HTTP, un código 2xx informa que la solicitud fue recibida, entendida y aceptada; no describe cuánto del universo consultado quedó cubierto. Una lista vacía dentro de un 200 es una respuesta correcta. Si un adaptador degradó a “sin resultados” porque cambió un selector, una sesión o un límite del portal, el transporte no tiene nada que reportar.

Por eso el resultado necesita dos planos separados: los hallazgos y el estado de cada fuente consultada. Cuando parte del trabajo falla, conviene que ese detalle sea legible por máquina —el formato estándar de detalles de problema para APIs HTTP admite miembros de extensión donde enumerar qué fuentes no respondieron— y no un texto libre en un campo de observaciones. Cómo se transmite eso al consumidor está en cobertura de una API.

La señal es por fuente, nunca agregada

El total es el peor indicador posible: una fuente grande que crece tapa a tres chicas que se apagaron. La unidad de vigilancia es la fuente, y para cada una conviene registrar consultas intentadas, respuestas utilizables, fallos por tipo y la última vez que devolvió un resultado completo.

Las recomendaciones públicas sobre nombres y etiquetas de métricas advierten que cada combinación de valores de etiqueta crea una serie nueva. La etiqueta útil acá es el código estable de la fuente y el tipo de resultado; la patente, el CUIT o el identificador del cliente no van en etiquetas.

Comparar contra la serie histórica de esa misma fuente rinde más que contra un umbral fijo: los portales tienen ritmo propio por día de semana, horario y calendario administrativo. Una caída a cero fuera de una ventana de mantenimiento conocida es sospechosa aunque el promedio general no se mueva.

Canarios: casos con resultado esperado

Un panel muestra que algo bajó; un canario muestra qué se rompió. Se mantiene un conjunto chico y estable de consultas por fuente cuyo resultado esperado ya fue verificado, y se corren de forma programada. La aserción no es un monto ni una cantidad exacta —eso cambia legítimamente—, sino la forma: que la fuente conteste, que los campos obligatorios estén presentes, que los identificadores tengan la estructura conocida.

Un canario armado con datos de personas reales envejece mal y expone lo que no hace falta exponer. Conviene usar vehículos propios, casos ya cerrados o fixtures acordados, y revisar el conjunto cuando la jurisdicción cambia algo de verdad.

Confirmar antes de declarar

Antes de anunciar una regresión revisamos lo barato primero: credenciales vencidas, cuota agotada, bloqueo por ritmo de consultas, cambio de dominio o de certificado, una ventana de mantenimiento publicada. Después reproducimos la consulta a mano contra el canal oficial, desde otra red o identidad, para separar “la fuente cambió” de “dejó de atendernos a nosotros”.

También hay que delimitar el alcance: si se perdió la fuente entera, una jurisdicción dentro de ella, un tipo de acta o sólo las consultas por documento. Una regresión mal delimitada lleva a rehacer trabajo que estaba bien.

Mientras el caso está abierto, el valor seguro es fallar cerrado: marcar el resultado como parcial, no convertir la ausencia en “sin infracciones” y congelar los agregados derivados de esa ventana.

Cerrar el caso con fecha

La cobertura no es una propiedad fija del servicio sino una observación con fecha. El vocabulario de calidad de datos del W3C propone justamente expresarla así, como mediciones asociadas a una métrica y una dimensión, en vez de como una etiqueta permanente del conjunto. Guardar cuándo fue la última consulta con cobertura completa permite después decir qué período hay que reprocesar.

El cierre incluye tres cosas: reprocesar la ventana afectada, avisar a quien recibió reportes hechos con datos incompletos y sumar al canario el caso que se escapó. Sin ese último paso, la misma regresión vuelve a pasar sin ruido.

Para revisar hoy: qué fuentes tienen métrica propia, cuál es la fecha de última cobertura completa de cada una, y qué hace tu integración cuando el resultado llega incompleto.

Metodología

Alcance
Detección, confirmación y cierre de caídas silenciosas de cobertura en una integración que consulta varias fuentes de infracciones; no cubre el diseño de cada adaptador ni el análisis jurídico de un acta.
Unidad de análisis
Una fuente consultada y el estado de sus consultas en una ventana comparable de su propia serie histórica.
Cobertura
Aplica a integraciones cuyas fuentes tienen disponibilidad y formato fuera de su control. Se apoya en la semántica HTTP, en el formato estándar de detalles de problema y en prácticas públicas de métricas y calidad de datos.

Limitaciones

  • Los umbrales, las ventanas de comparación y la frecuencia de los canarios dependen del ritmo de cada fuente y no pueden fijarse de forma universal.
  • Un canario confirma que la fuente responde para los casos elegidos; no prueba que el resto del universo consultable siga cubierto.
  • La nota describe criterios de detección y no evalúa herramientas de monitoreo ni configuraciones de proveedores concretos.

Fuentes

Preguntas frecuentes

¿Menos resultados significa que hay una regresión de cobertura?

No por sí solo. Una jurisdicción puede haber emitido menos actas en ese período. Se habla de regresión cuando cae qué fuentes respondieron con datos utilizables, medido por fuente y contra su propia serie, no cuando baja el total de infracciones encontradas.

¿Un código 200 garantiza que se consultaron todas las fuentes?

No. Un 2xx informa sobre la solicitud, no sobre el alcance de la búsqueda. Una lista vacía dentro de una respuesta exitosa es válida, así que el estado de cada fuente consultada tiene que viajar como dato aparte del resultado.

¿Conviene armar los canarios con patentes reales?

Es preferible evitarlo. Los casos de control se arman mejor con vehículos propios, expedientes ya cerrados o fixtures acordados, y conviene revisarlos cuando el caso cambia por motivos legítimos, para que la alerta no se dispare por un dato que envejeció.

¿Qué hacemos con los reportes emitidos durante una regresión?

Conviene marcarlos como parciales, guardar la fecha de la última consulta con cobertura completa y reprocesar esa ventana cuando la fuente vuelve. Si alguien tomó una decisión con un reporte incompleto, el aviso forma parte del cierre.

Notas relacionadas