Saltar a contenido

Guía de migración v1.6 — consolidación del contrato

La consolidación v1.6 del contrato /v1 ya se aplicó: la ventana de deprecación cerró y los tres parámetros deprecados fueron retirados de /v1/brands. El parámetro estado es ahora un enum validado de 14 códigos. Ya no existe el flag de contrato estricto ni las señales RFC 8594 (Deprecation/Link/Sunset): el contrato estricto pasó a ser incondicional.

Esta guía documenta el mapeo old → new que ya está en vigor. El esquema por campo autoritativo es la referencia OpenAPI en vivo en /docs; esta página describe la migración, no el esquema.

En una frase

  • Los parámetros denominacion, fechaDesde y fechaHasta fueron retirados de /v1/brands. Un request que aún los envíe no falla: Zod los descarta silenciosamente (200 con resultados más amplios), nunca un 400.
  • El parámetro estado se valida contra un vocabulario cerrado de 14 códigos: un valor fuera del vocabulario devuelve 400 validation_error de forma incondicional.
  • find-similar y oppositions pierden el filtrado por fecha (nunca tuvieron el canónico fechaPresentacion*).
  • insights conserva el filtrado por fecha bajo el canónico fechaPresentacionDesde / fechaPresentacionHasta.
  • Todo aplica idéntico en REST y en MCP (ambos comparten los mismos esquemas de @iris/core).

Tabla de mapeo old → new

# Retirado (old) Canónico (new) Superficie Resultado ahora
BR-1 denominacion nombre GET /v1/brands + tool MCP search_brands descartado por Zod (200)
BR-2 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta GET /v1/brands descartado por Zod (200)
BR-3 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta las 5 agregaciones GET /v1/insights/* + sus tools MCP descartado por Zod (200)
BR-4 estado como string libre estado validado contra el vocabulario de 14 códigos GET /v1/brands (array) + GET /v1/insights/* (escalar) 400 validation_error si está fuera del vocabulario

BR-1 — denominacion → nombre

denominacion era un alias de menor prioridad de nombre: ambos alimentaban el mismo motor de texto. El resto del contrato ya estaba estandarizado en nombre (insights, matchedFields, highlight), así que el canónico es nombre y denominacion fue retirado.

No se retira la búsqueda por campo. Se conservan intactos:

  • q — búsqueda de texto general (motor de 4 canales). Semántica propia, no afectada.
  • nombre — búsqueda de texto acotada al campo denominación. Es el canónico.

BR-2 / BR-3 — fechaDesde / fechaHasta → fechaPresentacion*

El par legacy fechaDesde / fechaHasta fue retirado. Usa el canónico fechaPresentacionDesde / fechaPresentacionHasta en /v1/brands y en las cinco agregaciones de insights, que se reconcilian internamente sobre el rango fecha_presentacion.

BR-4 — estado a vocabulario cerrado

estado se valida contra los 14 códigos del ciclo de vida del trámite (orden de ciclo de vida):

en_tramite, observacion_de_fondo, publicada, oposicion, concedida, registrada,
esperando_renovacion, rechazada, denegada, desistida, abandonada, anulada, caducado, vencida

En /v1/brands, estado es multivaluado (array): cualquier elemento fuera del vocabulario dispara 400 validation_error. En insights es escalar. Dentro del vocabulario → 200.

find-similar y oppositions — sin filtrado por fecha

Los endpoints GET /v1/brands/similar, GET /v1/brands/{nro}/similar y GET /v1/oppositions/open nunca tuvieron el canónico fechaPresentacion*; sólo exponían el legacy fechaDesde / fechaHasta. Al retirarse el legacy, pierden el filtrado por fecha por completo (decisión aceptada). Añadir el canónico ahí es un paso aditivo futuro (backlog). denominacion no existía en find-similar/insights, así que su retirada se acota naturalmente a /v1/brands.

Drop silencioso de los parámetros retirados

Los parámetros retirados no producen un 400: las querystrings no son .strict(), así que Zod descarta un denominacion / fechaDesde / fechaHasta rezagado y sirve el request con los demás filtros (200, resultados potencialmente más amplios). Los consumidores ya migraron, por lo que este comportamiento no expone datos nuevos ni rompe la neutralidad del corpus.

Acción para el consumidor

  1. Usa nombre en vez de denominacion.
  2. Usa fechaPresentacionDesde / fechaPresentacionHasta en vez de fechaDesde / fechaHasta en /v1/brands y en insights.
  3. Asegura que cualquier estado que envíes esté en el vocabulario de 14 códigos (de lo contrario, 400 validation_error).

Para el detalle por campo siempre vigente, consulta la referencia OpenAPI en /docs y el Versionado y obsolescencia.