Ir para o conteúdo

Guia de migração v1.6 — consolidação do contrato

A consolidação v1.6 do contrato /v1 já foi aplicada: a janela de descontinuação fechou e os três parâmetros descontinuados foram removidos de /v1/brands. O parâmetro estado é agora um enum validado de 14 códigos. O flag de contrato estrito e os sinais RFC 8594 (Deprecation/Link/Sunset) não existem mais: o contrato estrito passou a ser incondicional.

Este guia documenta o mapeamento old → new que já está em vigor. O schema por campo autoritativo é a referência OpenAPI ao vivo em /docs; esta página descreve a migração, não o schema.

Em uma frase

  • Os parâmetros denominacion, fechaDesde e fechaHasta foram removidos de /v1/brands. Um request que ainda os envie não falha: o Zod os descarta silenciosamente (200 com resultados mais amplos), nunca um 400.
  • O parâmetro estado é validado contra um vocabulário fechado de 14 códigos: um valor fora do vocabulário retorna 400 validation_error de forma incondicional.
  • find-similar e oppositions perdem o filtro por data (nunca tiveram o canônico fechaPresentacion*).
  • insights mantém o filtro por data sob o canônico fechaPresentacionDesde / fechaPresentacionHasta.
  • Tudo se aplica identicamente em REST e MCP (ambos compartilham os mesmos schemas de @iris/core).

Tabela de mapeamento old → new

# Removido (old) Canônico (new) Superfície Resultado agora
BR-1 denominacion nombre GET /v1/brands + tool MCP search_brands descartado pelo Zod (200)
BR-2 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta GET /v1/brands descartado pelo Zod (200)
BR-3 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta as 5 agregações GET /v1/insights/* + suas tools MCP descartado pelo Zod (200)
BR-4 estado como string livre estado validado contra o vocabulário de 14 códigos GET /v1/brands (array) + GET /v1/insights/* (escalar) 400 validation_error se fora do vocabulário

BR-1 — denominacion → nombre

denominacion era um alias de menor prioridade de nombre: ambos alimentavam o mesmo motor de texto. O resto do contrato já estava padronizado em nombre (insights, matchedFields, highlight), então o canônico é nombre e denominacion foi removido.

A busca por campo NÃO é removida. Estes permanecem intactos:

  • q — busca de texto geral (motor de 4 canais). Semântica própria; não afetada.
  • nombre — busca de texto restrita ao campo denominación. O canônico.

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

O par legado fechaDesde / fechaHasta foi removido. Use o canônico fechaPresentacionDesde / fechaPresentacionHasta em /v1/brands e nas cinco agregações de insights, que são reconciliados internamente sobre o intervalo fecha_presentacion.

BR-4 — estado para vocabulário fechado

estado é validado contra os 14 códigos do ciclo de vida do trâmite (ordem de ciclo de vida):

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

Em /v1/brands, estado é multivalorado (array): qualquer elemento fora do vocabulário dispara 400 validation_error. Em insights é escalar. Dentro do vocabulário → 200.

find-similar e oppositions — sem filtro por data

Os endpoints GET /v1/brands/similar, GET /v1/brands/{nro}/similar e GET /v1/oppositions/open nunca tiveram o canônico fechaPresentacion*; só expunham o legado fechaDesde / fechaHasta. Com o legado removido, eles perdem o filtro por data por completo (uma decisão aceita). Adicionar o canônico ali é um passo aditivo futuro (backlog). denominacion nunca existiu em find-similar/insights, então sua remoção fica naturalmente restrita a /v1/brands.

Descarte silencioso dos parâmetros removidos

Os parâmetros removidos não produzem um 400: as querystrings não são .strict(), então o Zod descarta um denominacion / fechaDesde / fechaHasta retardatário e serve o request com os demais filtros (200, resultados potencialmente mais amplos). Os consumidores já migraram, então esse comportamento não expõe dados novos nem quebra a neutralidade do corpus.

Ação do consumidor

  1. Use nombre em vez de denominacion.
  2. Use fechaPresentacionDesde / fechaPresentacionHasta em vez de fechaDesde / fechaHasta em /v1/brands e em insights.
  3. Garanta que qualquer estado que você envie esteja no vocabulário de 14 códigos (caso contrário, 400 validation_error).

Para o detalhe por campo sempre atual, consulte a referência OpenAPI em /docs e o Versionamento e descontinuação.