Guia de migração de 2026-09-23 — o corte do contrato
⭐ Este é o guia do contrato VIGENTE. No dia do corte, o prefixo
/v1deixa 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 mapaantigo → 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(emparties[]da marca) efilters.clase→filters.niceClass(vigilância). Eparties[].kindda marca publica agora o vocabulário de/parties(natural|legal|unknown), nãojuridica/desconocido. Tabela exata emCHANGELOG-CONTRACT.md. protectionDescriptionconserva seu nome.- Os VALORES de código se conservam em espanhol.
statussegue 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 porwatch_application,unwatch_application,list_watched_applicationselist_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_coverageestava aqui listada como renomeação de umlist_system_coverageque 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).
totalsó viaja quando é exato e barato; onde contar custa uma varredura, a chave não está. A estimativa da busca viaja comometa.estimatedTotal(cota inferior), nunca comototal.- ⛔ 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-Languagee 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)
- Mude a base das URLs: tire o prefixo
/v1e aplique o mapa de rotas (§1). Sem redirecionamento: uma URL antiga responde ausência, não um301. - Aplique o mapa de campos (§2) a tudo o que você desserializa, e o de ferramentas (§3) a toda chamada MCP.
- Refaça as leituras de coleção contra o envelope
results[](§a) e o cursor (§b): foradata,items,nextCursor, o array pelado eoffset— em TODAS as coleções, marcas incluídas. - Pare de negociar
Accept-Language: os rótulos vêm em um objeto de três idiomas (§c). - Assuma o colapso por padrão (§d): se precisar das cópias, peça com
dedupe=false. - Migre os corpos de erro para RFC 9457 e os códigos/cabeçalhos dos mapas menores.
- Corrija os literais de
sortpara os seis campos em inglês (§sort). - 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).