Filtro por jurisdicción en consultas masivas

Una consulta masiva rara vez necesita todo. Una flota que opera en dos provincias no gana nada preguntando en todas. El filtro por jurisdicción parece el parámetro más inocente del contrato: una lista de códigos y listo.

El problema es que ese parámetro cambia el significado de la respuesta. Recortar el alcance de la búsqueda y recortar la salida de una búsqueda completa producen cuerpos idénticos y consecuencias distintas. Si el contrato no dice cuál de las dos cosas hizo, quien consume el resultado no puede saber qué mide lo que recibió.

Filtro de alcance y filtro de presentación

Un filtro de alcance se aplica antes de buscar: define a qué fuentes se les pregunta. Reduce trabajo, tiempo y cantidad de datos puestos en circulación, y cambia la cobertura de lo que se devuelve. Un filtro de presentación se aplica después: se consultó todo y se muestra un subconjunto. No ahorra nada y, si una fuente excluida falló, esa falla ocurrió igual.

Los dos son legítimos; dejarlo implícito no. La respuesta debería declarar cuál se aplicó: de eso depende si un incidente en una fuente excluida afecta al resultado.

Cómo se declara el filtro en el contrato

La especificación OpenAPI permite describir un parámetro de consulta con valores múltiples y fijar su serialización —repetir el nombre, separar por comas— junto con el vocabulario aceptado. Sin esa declaración, dos bibliotecas arman la misma lista de forma diferente y una termina pidiendo una jurisdicción que el servidor no reconoce.

El vocabulario tiene que ser un catálogo cerrado y versionado, no texto libre; por qué el nombre visible no alcanza como clave está desarrollado en códigos estables para jurisdicciones.

Falta una decisión más: la jerarquía. El clasificador geográfico oficial ordena el territorio en dos niveles —provincia, y departamento, partido o comuna según el caso— y el código de abajo arrastra el de la provincia, así que expandir es mecánicamente posible. Lo que el clasificador no dice es qué pediste: si una provincia alcanza sólo a la autoridad de ese nivel o a todo lo que hay debajo. Y como el filtro nombra territorios, no organismos, bajo un mismo código pueden convivir una autoridad provincial, una municipal y una concesionaria.

En un envío masivo falta decidir si el filtro es del lote o de cada fila. Uno global es más simple; uno por fila permite pedir distinto para un vehículo radicado en otra provincia, y entonces tiene que viajar con la fila y volver en su estado por ítem.

Un código desconocido no se descarta en silencio

Un lote con un código mal tipeado termina mal si el servidor lo ignora: la consulta corre con un alcance más chico, devuelve menos y parece completa.

La semántica de HTTP prevé rechazar una solicitud que el servidor no puede procesar por un error atribuible al cliente. Para ese rechazo, RFC 9457 define un formato estándar de detalles de problema con miembros de extensión, donde caben los valores exactos que fallaron. Eso permite corregir sin adivinar cuál de los códigos del lote estaba mal.

Hay un caso intermedio: el código existe y es válido, pero no está cubierto para esa consulta o para esa cuenta. No es un error de sintaxis, así que puede aceptarse la consulta e informar esa jurisdicción como omitida, con su motivo, dentro del alcance efectivo.

Un vacío bajo un filtro no es “sin infracciones”

El filtro entra en el cuerpo de la respuesta como contexto obligatorio. Sin él, un cero es indistinguible de un cero real.

Una respuesta útil separa cuatro conjuntos: jurisdicciones pedidas, consultadas, omitidas —con motivo— y sin cerrar. Quien lee sólo la lista de actas puede llegar a “no tiene multas” desde un alcance que su propio equipo recortó tres capas más arriba. Cuando una jurisdicción incluida en el filtro no responde ya no hay recorte deliberado sino una consulta parcial, y se informa como tal.

Los campos derivados heredan el problema, aunque no como en una consulta parcial: ahí el denominador es desconocido y conviene retirarlos; bajo un filtro deliberado se conoce, y un total o un conteo valen dentro de ese alcance. Esa acotación viaja junto al número, no en la documentación.

Qué verificar antes de confiar en un filtro

Probá el contrato con tres casos y mirá la respuesta, no la documentación:

pedí una jurisdicción y confirmá que el alcance efectivo vuelve en el cuerpo;
mandá un código inválido y verificá que el rechazo lo nombra, en lugar de devolver un resultado más chico;
revisá que la versión del catálogo de jurisdicciones viaje con el resultado.

Queda un riesgo que ninguna prueba puntual muestra: un filtro guardado congela un alcance. Una consulta programada que fija un conjunto de jurisdicciones sigue preguntando por ese mismo conjunto cuando la cobertura crece, y nadie recibe un aviso porque técnicamente nada falló. Si el valor por defecto es “todas las cubiertas”, el alcance se amplía solo, y también cambia sin que nadie lo decida. Ninguna opción es mala: las dos necesitan revisión periódica y una fecha visible de última revisión.

Metodología

Alcance: Diseño del parámetro de jurisdicción en una consulta masiva de infracciones y de cómo la respuesta comunica el alcance aplicado. No cubre el modelo interno del catálogo de organismos ni la política de reintentos.
Unidad de análisis: Una solicitud masiva con un conjunto declarado de jurisdicciones y el alcance efectivo que devuelve su respuesta.
Cobertura: Semántica HTTP para el rechazo de solicitudes, formato estándar de detalles de problema, descripción de parámetros de consulta en OpenAPI y estructura por niveles del clasificador geográfico oficial.

Limitaciones

Es un patrón de integración, no un estándar oficial de respuesta para infracciones de tránsito.
El clasificador oficial consultado ordena divisiones político-administrativas; no declara qué autoridad de tránsito tiene competencia en cada una, así que un filtro territorial no selecciona por sí solo un conjunto de fuentes.
El vocabulario de jurisdicciones y su cobertura cambian con el tiempo, así que cualquier filtro guardado exige revisión periódica.

Fuentes

OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el 2026-08-29)
RFC 9110 — HTTP Semantics — RFC Editor (consultada el 2026-08-29)
RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el 2026-08-29)
Códigos geográficos del Sistema Estadístico Nacional — Instituto Nacional de Estadística y Censos (consultada el 2026-08-29)

Preguntas frecuentes

¿Filtrar por jurisdicción hace que la consulta salga más rápido?

Sólo si el filtro se aplica antes de consultar las fuentes. Si el sistema busca en todo y recorta la salida, el tiempo y el trabajo son los mismos: cambia lo que ves, no lo que se hizo. Por eso conviene que la respuesta declare cuál de las dos operaciones se aplicó.

Si filtro por una provincia, ¿entran también los municipios de esa provincia?

Depende de lo que defina el contrato, no del clasificador. El clasificador geográfico oficial baja hasta departamento, partido o comuna —no hasta el municipio— y su código de nivel inferior arrastra el de la provincia, así que expandir es posible, pero nadie declara por vos si corresponde. Pedí que ese comportamiento esté escrito y que la respuesta devuelva la lista expandida que efectivamente se consultó.

¿Qué debería pasar con un código de jurisdicción mal escrito dentro de un lote?

Lo peor es ignorarlo en silencio, porque la consulta corre con un alcance más chico y parece completa. Conviene rechazarlo con un error que nombre el valor exacto, o aceptarlo e informarlo como jurisdicción omitida con su motivo dentro del alcance efectivo.

¿Cero resultados bajo un filtro significa que el vehículo no tiene multas?

No. Significa que no se encontraron infracciones en las jurisdicciones consultadas. Cualquier lectura más amplia depende de una cobertura que el propio filtro recortó, y por eso el alcance efectivo debería acompañar siempre al resultado.

Filtrar por jurisdicción en una consulta masiva