API y empresas

Códigos estables para jurisdicciones: por qué el nombre visible no alcanza

Un nombre puede cambiar de abreviatura, tilde o formato. Una integración confiable separa el identificador canónico, el nivel territorial, el nombre mostrado y el organismo emisor.

Por Marco Ferreiro ·

Mapa físico de Argentina con fichas de colores que representan códigos jurisdiccionales

“Buenos Aires”, “PBA”, “Provincia de Buenos Aires” y “Bs. As.” pueden apuntar al mismo territorio en una conversación. En una API no deberían ser cuatro claves ni resolverse sólo comparando texto. Una tilde, un cambio de mayúsculas o una denominación nueva puede partir el historial de una integración.

La solución es separar identidad, presentación y contexto administrativo. El nombre se muestra; el código identifica; el nivel ubica; el organismo emite.

Cuatro conceptos que conviene separar

Un contrato robusto distingue:

También puede publicar alias de búsqueda, período de vigencia y referencias a clasificadores externos. Ninguno de esos atributos debería modificar retrospectivamente el identificador interno.

Esta separación permite cambiar “Ciudad Autónoma de Buenos Aires” por una forma corta en la interfaz sin crear una nueva jurisdicción ni perder las conciliaciones anteriores.

Qué aporta el clasificador de INDEC

INDEC mantiene códigos geográficos para el Sistema Estadístico Nacional. La codificación permite identificar provincias, departamentos o partidos y gobiernos locales dentro de un esquema definido. Los códigos deben tratarse como texto: si un valor tiene cero inicial, convertirlo a número puede destruir información.

Por ejemplo, el código de una provincia dentro de ese clasificador no es una abreviatura libre. Tiene un namespace, una estructura y una versión. Guardar sólo 6 en vez de la representación documentada puede introducir ambigüedad y romper exportaciones.

Georef ofrece una API oficial para normalizar datos geográficos y muestra respuestas con identificadores y nombres. Es una referencia útil para resolver territorios, pero no afirma qué organismo de multas tiene competencia ni qué fuente fue consultada.

Qué aporta ISO 3166-2 y qué no

ISO 3166-2 define códigos para subdivisiones de países. En Argentina, sus valores permiten referenciar provincias y la Ciudad Autónoma de Buenos Aires en un esquema internacional. Resulta práctico para intercambios con sistemas globales.

No es intercambiable con INDEC. Los códigos, propósito y mantenimiento pertenecen a namespaces diferentes. Una API puede publicar ambos:

{
  "references": {
    "indec": "valor-como-texto",
    "iso_3166_2": "AR-X"
  }
}

El ejemplo es ilustrativo, no un contrato oficial ni un código asignado a una jurisdicción real. La regla importante es conservar qué sistema originó cada valor y evitar un campo genérico llamado simplemente code.

Territorio y organismo emisor no son sinónimos

Una provincia puede contener municipios con potestades y portales propios. También puede intervenir una autoridad nacional en una ruta, según el marco aplicable. Si una integración guarda jurisdiction = provincia como única procedencia, pierde quién emitió el acta y qué canal publicó el dato.

Un modelo más expresivo vincula dos entidades:

{
  "jurisdiction_id": "jur_estable",
  "jurisdiction_level": "province",
  "issuer_id": "org_estable",
  "issuer_display_name": "Nombre visible"
}

Los valores son sintéticos. La separación permite que un organismo cambie su nombre sin convertir todas sus observaciones anteriores en registros de otra fuente.

Alias, tildes y homónimos

Los alias sirven para buscar, no para identificar. Un catálogo puede reconocer CABA, distintas capitalizaciones y denominaciones históricas, pero debería devolver siempre el mismo identificador canónico mientras la entidad sea la misma.

Un algoritmo de normalización basado sólo en quitar tildes es insuficiente. Puede juntar nombres que pertenecen a niveles diferentes o separar un municipio de la provincia homónima. Para resolverlo hacen falta, como mínimo, país, nivel y relación jerárquica.

El catálogo también debe definir qué ocurre ante una fusión, división o cambio administrativo. Reutilizar un código antiguo para una entidad nueva borra historia. Es preferible cerrar su vigencia, crear la nueva identidad y registrar la relación de sucesión.

Un catálogo sintético que resiste cambios

Una entrada de trabajo podría contener:

Campo Propósito
id Identidad interna estable
display_name Nombre actual para interfaz
level Nivel administrativo controlado
parent_id Relación jerárquica
aliases Variantes para búsqueda
valid_from / valid_to Vigencia de esa representación
external_refs Códigos con namespace y versión
issuer_ids Organismos relacionados, no presumidos

La prueba debe incluir tildes, mayúsculas, alias repetidos en niveles distintos y nombres históricos. También debería verificar que una actualización del nombre no cambie el identificador de los registros ya conciliados.

Cómo migrar desde nombres usados como clave

Primero inventariá todos los valores observados y no los sobrescribas. Después vinculá cada variante con una entidad canónica usando contexto territorial y evidencia oficial. Los casos ambiguos deben quedar pendientes de revisión, no resolverse con el primer resultado textual.

Durante la transición, una respuesta puede conservar el nombre original de la fuente junto al valor normalizado. Esto permite auditar errores:

No hace falta exponer toda la operación interna al cliente, pero sí mantener trazabilidad suficiente para explicar un cambio.

Errores que rompen la historia

Usar el nombre como clave primaria genera duplicados. Convertir códigos a números elimina ceros. Publicar un código sin namespace impide saber si viene de INDEC, ISO o un catálogo propio. Y equiparar provincia con emisor oculta la procedencia del acta.

Otro error es corregir el catálogo reescribiendo respuestas antiguas sin conservar la versión. Si una conciliación cambió, la integración necesita saber si cambió la fuente, la regla de normalización o sólo la etiqueta mostrada.

Método y límites de esta propuesta

La estructura compara documentos oficiales de INDEC, Georef e ISO y los aplica a casos sintéticos de alias y homónimos. No usa datos de personas, patentes ni actas reales. Tampoco declara que esos clasificadores definan competencia en materia de tránsito.

Un código estable evita que un cambio de texto rompa la historia; no resuelve por sí solo la cobertura ni la autoridad competente. Para una API de infracciones, el catálogo debe mantener separados territorio, organismo, fuente y versión de la regla que los relacionó.

Metodología

Alcance
Comparación de los clasificadores de INDEC, el servicio Georef e ISO 3166-2, aplicada a un catálogo sintético para una API de infracciones.
Unidad de análisis
Una jurisdicción canónica con identificador interno, nombre mostrado, nivel, alias, vigencia, referencias externas y organismos relacionados.
Cobertura
Esquemas oficiales consultados el 14 de agosto de 2026; no existe equivalencia automática entre territorio estadístico y autoridad emisora.

Limitaciones

Fuentes

Preguntas frecuentes

¿Conviene usar el nombre de una provincia como clave primaria?

No. Mayúsculas, tildes, abreviaturas y cambios de denominación pueden romper uniones. Usá un identificador estable y tratá el nombre como un atributo versionable de presentación.

¿El código de INDEC y el de ISO 3166-2 son intercambiables?

No. Pertenecen a clasificadores con alcances y formatos distintos. Pueden coexistir como referencias externas, pero una integración debe conservar el namespace y la versión de cada código.

¿Un código territorial identifica también al organismo que emitió la multa?

No necesariamente. Dentro del mismo territorio pueden intervenir autoridades nacionales, provinciales, municipales o concesionarias. El organismo emisor necesita su propio identificador y relación con el territorio.

Notas relacionadas