Ir para o conteúdo

Guia de migração de 2026-09-23 — o corte do contrato

⭐ Este é o guia do contrato VIGENTE. No dia do corte, o prefixo /v1 deixa de responder e nenhuma URL antiga sobrevive: nem no servidor, nem no arnês de paridade, nem nos scripts de carga, nem na documentação. Todo endpoint muda de URL de uma vez, sem redirecionamento e sem período de carência.

O que NÃO se repete aqui é o esquema. O inventário campo a campo, autoritativo, é a referência OpenAPI gerada a partir dos esquemas que o servidor realmente usa: https://docs.tarno.cl (no repositório, contract/openapi.generated.yaml). Duplicá-lo aqui criaria uma segunda fonte que se desatualiza — que é exatamente o que esta fase inteira existe para corrigir. Esta página descreve a migração (o mapa antigo → novo), não o esquema.

O registro de cada mudança, com seu [BREAK]/[BEH]/[ADD], está no changelog do contrato. O aviso ao único consumidor — o aplicativo Tarno — é uma carta, não várias.

Em uma frase

No dia do corte, /v1 deixa de responder e todo o contrato passa de uma vez a: rotas sem prefixo e em inglês, nomes de campo em inglês, uma forma de envelope, uma paginação, um corpo de erro, um vocabulário de ordenação — e os rótulos deixam de ser negociados por cabeçalho e passam a vir como objeto de três idiomas. O colapso por evento passa a ser o padrão.

Sem redirecionamento, sem cabeçalho de versão, sem período de carência. O que quebra é feito uma vez e avisado uma vez (a carta única).

Os três mapas, completos

Os três mapas estão copiados do registro de contrato (CHANGELOG-CONTRACT.md, entradas 38-04..38-14 e seus retoques) — não reconstruídos do diff.


1 · Mapa de rotas — REST (antiga → nova)

As que desaparecem não têm substituta direta: caem em um filtro ou em uma expansão, indicado em cada linha.

antiga (deixa de responder) nova desaparecimento
GET /v1/brands GET /trademarks —
POST /v1/brands/batch GET /trademarks?applicationNumber=a,b,c (até 100) o lote vira um filtro
GET /v1/brands/similar?q= POST /trademarks/search com similarTo a similaridade vira um motor de busca
GET /v1/brands/{n}/similar POST /trademarks/search com similarToTrademark idem
GET /v1/oppositions/open POST /trademarks/search com oppositionWindow: "open" a janela de oposição é um filtro, não uma rota
GET /v1/brands/{n} GET /trademarks/{applicationNumber} —
GET /v1/brands/{n}/report GET /trademarks/{applicationNumber}?expand=… ⭐ o relatório deixa de ser uma rota: é o detalhe com expand=
GET /v1/brands/{n}/opposition GET /trademarks/{n}/annotations?family=opposition ⭐ a linha de oposição sempre foi um filtro sobre as anotações
(só inline na marca) GET /annotations/{id} · POST /annotations/search · GET /trademarks/{n}/annotations ⭐ a anotação vira recurso próprio
GET /v1/personas GET /parties (+ GET /parties/{id}, GET /parties/{id}/trademarks) —
GET /v1/insights/filings-over-time GET /insights/trademarks?groupBy=filedMonth as 5 rotas se fundem em uma com groupBy
GET /v1/insights/by-estado GET /insights/trademarks?groupBy=status idem
GET /v1/insights/by-class GET /insights/trademarks?groupBy=niceClass idem
GET /v1/insights/by-holder GET /insights/trademarks?groupBy=holder idem
GET /v1/insights/by-representante GET /insights/trademarks?groupBy=representative (+ POST /insights/trademarks/search) idem
GET /v1/feriados · GET /v1/feriados/cobertura GET /holidays a cobertura viaja sempre em meta.coverage
GET /v1/freshness GET /system/freshness o operacional se separa sob /system
GET /v1/sync-runs GET /system/sync-runs idem
GET /v1/watch* /watchlists · /watchlists/{id} · /watchlists/{id}/items · /watchlists/{id}/hits · /watchlists/{id}/deliveries o estilo antigo é retirado por inteiro. ⚠ As rotas /watchlists também foram retiradas, em 2026-10-04: hoje a vigilância é /watch/applications e /watch/hits (guia)

Rotas NOVAS (não substituem nada; nada a migrar): GET /sections · GET /sections/{code} · GET /legal-norms · GET /legal-norms/{id} · GET /nice-classes · GET /system/coverage · GET /system/vigilance-horizon · GET /system/me · GET /health (raiz, sem API key).

Filtros. Um único conjunto em inglês, a mesma forma em /trademarks, /trademarks/search e /insights: q, applicationNumber, niceClass, status, signType, holder, representative, taxId, filedFrom/filedTo, expiresFrom/expiresTo, registeredFrom/registeredTo, publishedFrom/publishedTo, relation=current|former|all, similarTo, similarToTrademark, oppositionWindow, facets, e desde 2026-09-23 goodsAndServices (citedNorm/article/letter são das anotações: em marcas, 400). expand=parties,annotations,encumbrances,classes,norms só em GET /trademarks/{n} (⛔ sem fields=). holder/representative/taxId são listas (OR dentro do parâmetro).


2 · Mapa de campos — (antigo → novo)

Copiado da entrada [BREAK] do 38-07 (a camada do vocabulário do fio), mais os campos de parties do 38-06.

hoje (se retira) a partir do corte
nroSolicitud / nroRegistro applicationNumber / registrationNumber
denominacion denomination
estado / tipoSigno status / signType
fechaPresentacion / fechaPublicacion / fechaRegistro / fechaVencimiento filedOn / publishedOn / registeredOn / expiresOn
seccion / seccionNombre / seccionEtiqueta / seccionTipo section / sectionName / sectionLabel / sectionFamily
seccionActo / seccionActoNombre / seccionActoEtiqueta act / actName / actLabel
observacion / observacionCompleta observation / observationDerived
personas / personasHistoricas / anotaciones / gravamenes parties / formerParties / annotations / encumbrances
clases / clasesHistoricas / clase / descripcion classes / formerClasses / number / goodsAndServices
titulares / representantes holders / representatives
renovaciones / ultimaRenovacion renewals / lastRenewalOn
ventanaOposicion oppositionWindow
estadoDerivado / estadoDesactualizado ⚠ desde 2026-09-23 (D11): o derivado viaja em status (derivedStatus foi retirado); o literal do INAPI em statusInapi, só quando difere; a bandeira em statusStale, em todas as vistas
fecha / nombre / pais / rol / identificador date / name / country / role / taxId
variantes duplicates
vigencia / soloVigentes relation / liveOnly
traduccion / descripcionEtiqueta / imagenUrl translation / imageDescription / imageUrl
feriado fecha / nombre / tipo / origen date / name / type / origin

parties (a pessoa vira uma entidade com role — 38-06):

hoje a partir do corte
tipo / tipoOrigen kind (natural|legal|unknown) / kindSource (tax_id|suffix|manual, agora nullable)
nombre name
identificador taxId
pais country
observacion jurisdictionClause
nombrePublicado publishedName
revision (booleano) review ({ reason }, o motivo em código)
region / comuna / regionNombre / comunaNombre territory ({ regionCode, regionName, communeCode, communeName, unknownCommune })
marcasTotal trademarkCount

⚠ O que NÃO muda de nome, nem agora nem em uma passada posterior:

  • ~~categoria / ambito (37D) conservam seu nome~~ — ⛔ não mais: [BREAK] de 2026-09-23. A regra do corte é que os RÓTULOS do contrato (nomes de campo) vão em inglês e os VALORES podem ficar em espanhol; restavam sete rótulos em espanhol e foram renomeados de uma vez, em REST e MCP: categoria/categoriaEtiqueta → category/categoryLabel, ambito/ambitoEtiqueta → scope/scopeLabel, eventoId → eventId (anotações), titular → holders (cada item da listagem e da busca de marcas), observacion → observation (em parties[] da marca) e filters.clase → filters.niceClass (vigilância). E parties[].kind da marca publica agora o vocabulário de /parties (natural|legal|unknown), não juridica/desconocido. Tabela exata em CHANGELOG-CONTRACT.md.
  • protectionDescription conserva seu nome.
  • Os VALORES de código se conservam em espanhol. status segue valendo "en_tramite", signType "mixta", classes[].status "concedida". A tradução dos códigos para o inglês (pending, word, granted…) é uma passada posterior, ainda não feita.
  • Os literais do INAPI (códigos de seção M5/A07T, o texto da anotação, a grafia publicada, a cláusula de jurisdição, o RUT) não se traduzem: traduz-se o nome do campo, nunca o valor.

3 · Mapa de ferramentas — MCP (antigo → novo)

Copiado da entrada [BREAK] do 38-11 (nomes alinhados com o manifesto, sem alias e sem janela) e dos planos 38-05/38-06.

hoje (se retira) a partir do corte
search_brands / get_brands_batch list_trademarks (o lote é uma coleção com filtro)
find_similar_brands search_trademarks com similarTo / similarToTrademark
get_open_oppositions search_trademarks com oppositionWindow: "open"
get_brand_detail get_trademark
get_brand_report get_trademark com expand=
get_brand_opposition list_trademark_annotations (family=opposition)
search_personas list_parties + get_party + list_party_trademarks
insights_filings_over_time get_trademark_insights (groupBy=filedMonth)
insights_by_estado get_trademark_insights (groupBy=status)
insights_by_class get_trademark_insights (groupBy=niceClass)
insights_by_holder get_trademark_insights (groupBy=holder)
insights_by_representante get_trademark_insights (groupBy=representative)
get_feriados / get_feriados_cobertura list_holidays
get_freshness / get_sync_runs get_system_freshness / list_sync_runs
watch_register create_watchlist
watch_list list_watchlists
watch_get get_watchlist
watch_patch update_watchlist
watch_delete delete_watchlist
watch_list_hits list_watchlist_hits
watch_list_deliveries list_watchlist_deliveries
watch_list_items list_watchlist_items
watch_add_item add_watchlist_item
watch_remove_item remove_watchlist_item

⚠ 2026-10-04: as dez ferramentas *_watchlist* da coluna da direita foram retiradas por sua vez. São substituídas por watch_application, unwatch_application, list_watched_applications e list_similarity_hits; o mapa está no guia de Vigilância.

Ferramentas NOVAS (nada a migrar) — são 14: explain_section_code · get_annotation · get_legal_norm · get_party · get_section · get_system_coverage · get_system_me · get_vigilance_horizon · list_legal_norms · list_nice_classes · list_party_trademarks · list_sections · search_annotations · search_trademark_insights.

⚠ get_system_coverage estava aqui listada como renomeação de um list_system_coverage que nunca existiu. É nova: a cobertura de ingestão dia a dia chegou com o corte.

Aditivo: os catálogos passam a ser recursos MCP (iris://catalogs/states, sections, nice-classes, holidays/{year}), e há três prompts (availability_check, case_history, weekly_watch) e uma versão real (2026-09-23) com as quatro regras nas instruções do servidor.


Os mapas menores, também copiados

Códigos de erro (38-04)

antigo novo onde
fuera_de_cobertura out_of_coverage 422 no calendário
cobertura_no_declarada coverage_not_declared 503 no calendário
invalid_input validation_error MCP, todas as ferramentas
invalid_input batch_too_large o teto de lote (agora um 422, não uma falha de validação)

Cabeçalhos (38-04)

antigo novo nota
X-Request-Id X-Correlation-ID aceito do cliente e devolvido em TODA resposta
X-Quota-Limit RateLimit-Limit —
X-Quota-Remaining RateLimit-Remaining —
X-Quota-Reset RateLimit-Reset ⛔ também muda o VALOR: de instante absoluto para segundos restantes

Retry-After é conservado. ETag + If-None-Match (304) em todo objeto individual; os catálogos declaram Cache-Control.

Tokens de sort (38-12 + retoque do 38-07)

⭐ Os tokens de ordenação são publicados SÓ em inglês. O retoque retirou os alias em espanhol e renomeou a família de estado.

token retirado substituto
relevancia relevance
recientes filedOn:desc
antiguas filedOn:asc
estado / estado:asc / estado:desc status / status:asc / status:desc
fechaActualizacion:asc / fechaActualizacion:desc retirado sem substituto (ordenava por uma data do NOSSO pipeline, não um fato do INAPI)

Os seis campos que sobrevivem, cada um asc|desc: status, filedOn, denomination, expiresOn, registeredOn, publishedOn — mais relevance. Um token não listado é um 400 validation_error.


As mudanças de FORMA — o que não se migra renomeando

Estas não são equivalências de nome: são mudanças de forma que um consumidor tem que religar.

(a) O envelope — UMA forma para toda coleção

📌 HISTÓRIA — de 2026-09-20 a 2026-09-23 houve DOIS envelopes. As coleções de marcas (GET /trademarks, POST /trademarks/search, o lote, GET /parties/{id}/trademarks) usavam { items, nextCursor, dataAsOf, estimatedTotal } (o lote, { items, notFound, dataAsOf }). Desde o [BREAK] de 2026-09-23 à noite o envelope é um só, sem exceção — veja § «2026-09-23 · envelope único».

{ "results": [ /* … */ ], "limit": 20, "next": "eyJvIjoyMH0", "hasMore": true, "total": 14,
  "meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" } }

Substitui dez envelopes, seis paginações e três padrões de limit em TODAS as coleções. Os nomes data, items, nextCursor e o array pelado deixam de existir. Um recurso individual responde o objeto plano, sem envelope, com a frescura em cabeçalhos (Iris-Data-As-Of, Iris-Coverage-Through).

  • total só viaja quando é exato e barato; onde contar custa uma varredura, a chave não está. A estimativa da busca viaja como meta.estimatedTotal (cota inferior), nunca como total.
  • ⛔ Nenhum parâmetro muda o TIPO da resposta. ?envelope= se retira: os quatro endpoints que devolviam um array pelado por padrão agora devolvem sempre o envelope, igual ao MCP. É a primeira vez que REST e MCP coincidem nisso.

(b) A paginação — um único cursor

limit (padrão 20, máximo 100) + cursor opaco keyset. O offset se retira. Um ?offset= atrasado é um 400 validation_error que nomeia o substituto. Sobre 10 M de anotações o offset é lento e mente sobre o total; o cursor é cortado no teto em vez de oferecer uma página que ninguém pode defender. Um cursor emitido para outra ordenação degrada para a página um, não para uma página falsa.

(c) O rótulo — de cadeia negociada a objeto de TRÊS idiomas

seccionEtiqueta/seccionActoEtiqueta/categoriaEtiqueta (hoje categoryLabel)/ambitoEtiqueta (hoje scopeLabel)/renovacion.etiqueta eram uma cadeia negociada por Accept-Language. Agora cada rótulo é um LocalizedString com os três idiomas de uma vez, null onde não há tradução:

{ "code": "registered",
  "label": { "es-CL": "Registrada", "en": "Registered", "pt-BR": "Registrada" },
  "source": { "label": "(R) Registrada" } }
  • A negociação por cabeçalho (Accept-Language) se retira (um agente MCP não manda cabeçalhos, e uma resposta que depende de um cabeçalho não se cacheia).
  • A resposta é idêntica com qualquer Accept-Language e sem nenhum.

(d) O colapso por evento — passa a ser o PADRÃO (38-08)

Antes, uma anotação com cópias do mesmo fato (Estado Diario e a ficha de processo publicando o mesmo) era devolvida uma por linha salvo se você pedisse ?dedupe=true. Agora o colapso é o padrão: cada fato é devolvido uma vez, e quem quiser ver as cópias as pede com dedupe=false. O colapso é lógico: nunca apaga uma linha — as cópias seguem publicadas em duplicates[].

Cada anotação ganha dois campos sempre presentes: versionsOfFact (quantas linhas descrevem este MESMO fato) e versionsDiffer (true quando existe outra versão não idêntica nem contida). O aviso é neutro: diz QUE há outra versão e COMO pedi-la, nunca QUAL a diz (a proveniência sai do contrato). Garantia: renewals/lastRenewalOn são iguais com dedupe=true e com dedupe=false.

(e) Os erros — RFC 9457, um único corpo

Content-Type: application/problem+json, o mesmo corpo em REST, no serviço de trabalhos e no MCP:

{ "type": "https://api.tarno.cl/problems/validation_error",
  "title": "Request validation failed", "status": 400,
  "detail": "`offset` foi retirado do contrato…", "code": "validation_error",
  "requestId": "74c953c7-…", "errors": [ { "field": "offset", "code": "custom", "detail": "…" } ] }

code é o que um cliente compara, e está sempre em inglês. title/detail são para humanos e podem mudar sem ser um [BREAK]; mudar um code é. requestId é o mesmo valor que X-Correlation-ID. Um 5xx não leva detalhe interno ao cliente.

estado significa
400 validação — a requisição está malformada ou um parâmetro fora de faixa
404 não existe — o recurso não está, ou não é seu (uniforme entre inquilinos)
422 regra de negócio — a requisição é VÁLIDA e ainda assim não pode ser atendida

(f) A semântica de «sem valor» na marca (38-05)

O detalhe e o relatório declaravam os mesmos campos com duas semânticas de nulo (um os omitia, o outro os dava null). Vence null: os onze escalares do pedido (registrationNumber, status, signType, filedOn, expiresOn, publishedOn, registeredOn, translation, imageDescription, protectionDescription, imageUrl) estão sempre presentes, null quando não têm valor. ⚠ A exceção é conservada: category/scope (antes categoria/ambito, e seus rótulos) seguem sendo omitidos quando «não sabemos» (5,5 % das marcas).

O que fazer: se você distinguia "nroRegistro" in obj de obj.nroRegistro === null, agora só ocorre o segundo para esses onze. ?? valorPadrao segue funcionando; Object.hasOwn(...) sobre eles agora é sempre true. O sentinela '0' do INAPI segue sem ser publicado (antes omitido, agora null).

(g) A pessoa vira parties — uma entidade com papel (38-06)

Titular, solicitante, representante e oponente são a mesma entidade com um role onde intervém — e a mesma parte deixa de aparecer três vezes. territory se tipa (códigos COM seus nomes, unknownCommune como campo próprio; null = parte estrangeira). trademarkCount não filtra: as pessoas sem nenhuma marca seguem saindo com seu zero.


2026-09-23 · envelope único — o [BREAK] que fecha as pontas soltas do contrato

Uma única mudança incompatível, datada de 2026-09-23 (noite), registrada em CHANGELOG-CONTRACT.md:

antes depois
marcas: { items, nextCursor, dataAsOf, estimatedTotal, facets, mode } o envelope comum: { results, limit, next, hasMore, meta } — meta.dataAsOf, meta.coverageThrough, meta.estimatedTotal, meta.facets, meta.mode
lote: { items, notFound, dataAsOf } o mesmo envelope, meta.notFound, total exato, next: null
facets.clase · facets.estado meta.facets.niceClass · meta.facets.status
matchedFields[].field: nombre/titular/representante/rut denomination/holder/representative/taxId
highlight.field: "nombre" highlight.field: "denomination"
kindSource na marca: rut/sufijo tax_id/suffix (como em /parties)
um parâmetro desconhecido era ignorado (200) 400 validation_error, uma entrada de errors[] por chave; MCP: erro de entrada
?envelope=, expand na lista de marcas: ignorados 400
GET /trademarks/{n}: dedupe padrão false padrão true (também em GET /trademarks/{n}/annotations, que agora o aceita)
o lote ignorava os demais filtros ele os APLICA; meta.notFound = só o que não existe; limit/cursor/sort/minScore/q/denomination/facets com o lote → 400
catálogos sem Cache-Control (exceto /holidays) Cache-Control de catálogo em /nice-classes, /sections, /legal-norms e seus objetos
— filtro novo goodsAndServices (texto de produtos e serviços)
sort=status pelo literal do INAPI pelo status publicado (o derivado)

Ação para o consumidor (checklist)

  1. Mude a base das URLs: tire o prefixo /v1 e aplique o mapa de rotas (§1). Sem redirecionamento: uma URL antiga responde ausência, não um 301.
  2. Aplique o mapa de campos (§2) a tudo o que você desserializa, e o de ferramentas (§3) a toda chamada MCP.
  3. Refaça as leituras de coleção contra o envelope results[] (§a) e o cursor (§b): fora data, items, nextCursor, o array pelado e offset — em TODAS as coleções, marcas incluídas.
  4. Pare de negociar Accept-Language: os rótulos vêm em um objeto de três idiomas (§c).
  5. Assuma o colapso por padrão (§d): se precisar das cópias, peça com dedupe=false.
  6. Migre os corpos de erro para RFC 9457 e os códigos/cabeçalhos dos mapas menores.
  7. Corrija os literais de sort para os seis campos em inglês (§sort).
  8. Verifique contra a referência gerada: https://docs.tarno.cl.

Para executá-la com um assistente passo a passo, use migracion-38-prompt.md.


Fontes dos mapas: CHANGELOG-CONTRACT.md 38-04..38-14 + retoques · contract/openapi.generated.yaml (a referência gerada, não duplicada aqui).