Guía de migración del 2026-09-23 — el corte del contrato
⭐ Esta es la guía del contrato VIGENTE. El día del corte, el prefijo
/v1deja de responder y ninguna URL vieja sobrevive: ni en el servidor, ni en el arnés de paridad, ni en los guiones de carga, ni en la documentación. Todo endpoint cambia de URL a la vez, sin redirección y sin periodo de gracia.Lo que no se repite aquí es el esquema. El inventario campo a campo, autoritativo, es la referencia OpenAPI generada de los esquemas que el servidor usa de verdad:
https://docs.tarno.cl(en el repositorio,contract/openapi.generated.yaml). Duplicarlo aquí crearía una segunda fuente que se desfasa — que es exactamente lo que esta fase entera viene a arreglar. Esta página describe la migración (el mapaviejo → nuevo), no el esquema.El registro de cada cambio, con su
[BREAK]/[BEH]/[ADD], está en el changelog del contrato. El aviso al único consumidor —la aplicación Tarno— es una carta, no varias.
En una frase
El día del corte, /v1 deja de responder y todo el contrato pasa a la vez a: rutas sin prefijo
y en inglés, nombres de campo en inglés, una forma de sobre, una paginación, un cuerpo
de error, un vocabulario de ordenación — y las etiquetas dejan de negociarse por cabecera para
venir como objeto de tres idiomas. El colapso por evento pasa a ser el defecto.
No hay redirección, no hay cabecera de versión, no hay periodo de gracia. Lo que rompe se hace una vez y se avisa una vez (la carta única).
Los tres mapas, completos
Los tres mapas están copiados del registro de contrato (CHANGELOG-CONTRACT.md, entradas
38-04..38-14 y sus retoques) — no reconstruidos del diff.
1 · Mapa de rutas — REST (vieja → nueva)
Las que desaparecen no tienen sustituta directa: caen en un filtro o en una expansión, y se indica en cada fila.
| vieja (deja de responder) | nueva | desaparición |
|---|---|---|
GET /v1/brands |
GET /trademarks |
— |
POST /v1/brands/batch |
GET /trademarks?applicationNumber=a,b,c (hasta 100) |
el lote pasa a ser un filtro |
GET /v1/brands/similar?q= |
POST /trademarks/search con similarTo |
la similitud pasa a ser un motor de búsqueda |
GET /v1/brands/{n}/similar |
POST /trademarks/search con similarToTrademark |
ídem |
GET /v1/oppositions/open |
POST /trademarks/search con oppositionWindow: "open" |
la ventana de oposición es un filtro, no una ruta |
GET /v1/brands/{n} |
GET /trademarks/{applicationNumber} |
— |
GET /v1/brands/{n}/report |
GET /trademarks/{applicationNumber}?expand=… |
⭐ el informe deja de ser una ruta: es el detalle con expand= |
GET /v1/brands/{n}/opposition |
GET /trademarks/{n}/annotations?family=opposition |
⭐ la línea de oposición siempre fue un filtro sobre las anotaciones |
| (sólo inline en la marca) | GET /annotations/{id} · POST /annotations/search · GET /trademarks/{n}/annotations |
⭐ la anotación pasa a ser recurso propio |
GET /v1/personas |
GET /parties (+ GET /parties/{id}, GET /parties/{id}/trademarks) |
— |
GET /v1/insights/filings-over-time |
GET /insights/trademarks?groupBy=filedMonth |
las 5 rutas se funden en una con groupBy |
GET /v1/insights/by-estado |
GET /insights/trademarks?groupBy=status |
ídem |
GET /v1/insights/by-class |
GET /insights/trademarks?groupBy=niceClass |
ídem |
GET /v1/insights/by-holder |
GET /insights/trademarks?groupBy=holder |
ídem |
GET /v1/insights/by-representante |
GET /insights/trademarks?groupBy=representative (+ POST /insights/trademarks/search) |
ídem |
GET /v1/feriados · GET /v1/feriados/cobertura |
GET /holidays |
la cobertura viaja siempre en meta.coverage |
GET /v1/freshness |
GET /system/freshness |
lo operativo se separa bajo /system |
GET /v1/sync-runs |
GET /system/sync-runs |
ídem |
GET /v1/watch* |
/watchlists · /watchlists/{id} · /watchlists/{id}/items · /watchlists/{id}/hits · /watchlists/{id}/deliveries |
el estilo viejo se retira entero. ⚠ Las rutas /watchlists también se retiraron, el 2026-10-04: hoy la vigilancia es /watch/applications y /watch/hits (guía) |
Rutas NUEVAS (no sustituyen a nada; nada que 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 (raíz, sin API key).
Filtros. Un solo juego en inglés, la misma forma en /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, y desde el 2026-09-23 goodsAndServices (citedNorm/article/letter son de las anotaciones: en marcas, 400). expand=parties,annotations,encumbrances,classes,norms sólo en GET /trademarks/{n}
(⛔ sin fields=). holder/representative/taxId son listas (OR dentro del parámetro).
2 · Mapa de campos — (viejo → nuevo)
Copiado de la entrada [BREAK] del 38-07 (la capa del vocabulario del cable), más los campos de
parties del 38-06.
| hoy (se retira) | a partir del 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): el derivado viaja en status (derivedStatus se retiró); el literal de INAPI en statusInapi, sólo cuando difiere; la bandera en statusStale, en todas las 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 (la persona pasa a ser una entidad con role — 38-06):
| hoy | a partir del corte |
|---|---|
tipo / tipoOrigen |
kind (natural|legal|unknown) / kindSource (tax_id|suffix|manual, ahora nullable) |
nombre |
name |
identificador |
taxId |
pais |
country |
observacion |
jurisdictionClause |
nombrePublicado |
publishedName |
revision (booleano) |
review ({ reason }, el motivo en código) |
region / comuna / regionNombre / comunaNombre |
territory ({ regionCode, regionName, communeCode, communeName, unknownCommune }) |
marcasTotal |
trademarkCount |
⚠ Lo que NO cambia de nombre, ni ahora ni en una pasada posterior:
- ~~
categoria/ambito(37D) conservan su nombre~~ — ⛔ ya no:[BREAK]del 2026-09-23. La regla del corte es que las ETIQUETAS del contrato van en inglés y los VALORES pueden ir en español; quedaban siete etiquetas en español y se renombraron a la vez, en REST y MCP:categoria/categoriaEtiqueta→category/categoryLabel,ambito/ambitoEtiqueta→scope/scopeLabel,eventoId→eventId(anotaciones),titular→holders(cada elemento del listado y la búsqueda de marcas),observacion→observation(enparties[]de la marca) yfilters.clase→filters.niceClass(vigilancia). Yparties[].kindde la marca publica ya el vocabulario de/parties(natural|legal|unknown), nojuridica/desconocido. Tabla exacta enCHANGELOG-CONTRACT.md. protectionDescriptionconserva su nombre.- Los VALORES de código se conservan en castellano.
statussigue valiendo"en_tramite",signType"mixta",classes[].status"concedida". La traducción de los códigos al inglés (pending,word,granted…) es una pasada posterior, aún no hecha. - Los literales de INAPI (códigos de sección
M5/A07T, el texto de la anotación, la grafía publicada, la cláusula de jurisdicción, el RUT) no se traducen: se traduce el nombre del campo, nunca el valor.
3 · Mapa de herramientas — MCP (viejo → nuevo)
Copiado de la entrada [BREAK] del 38-11 (nombres alineados con el manifiesto, sin alias ni
ventana) y de los planes 38-05/38-06.
| hoy (se retira) | a partir del corte |
|---|---|
search_brands / get_brands_batch |
list_trademarks (el lote es una colección con filtro) |
find_similar_brands |
search_trademarks con similarTo / similarToTrademark |
get_open_oppositions |
search_trademarks con oppositionWindow: "open" |
get_brand_detail |
get_trademark |
get_brand_report |
get_trademark con expand= |
get_brand_opposition |
list_trademark_annotations (filtro 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: las diez herramientas
*_watchlist*de la columna derecha se retiraron a su vez. Las sustituyenwatch_application,unwatch_application,list_watched_applicationsylist_similarity_hits; el mapa está en la guía de Vigilancia.
Herramientas NUEVAS (nada que migrar) — son 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_coverageestaba aquí mal listada como renombre de unlist_system_coverageque nunca existió. Es nueva: la cobertura de ingesta día a día llegó con el corte.
Aditivo: los catálogos pasan a ser recursos MCP (iris://catalogs/states, sections,
nice-classes, holidays/{year}), y hay tres guiones (availability_check, case_history,
weekly_watch) y una versión real (2026-09-23) con las cuatro reglas en las instrucciones del
servidor.
Los mapas menores, también copiados
Códigos de error (38-04)
| viejo | nuevo | dónde |
|---|---|---|
fuera_de_cobertura |
out_of_coverage |
422 en el calendario |
cobertura_no_declarada |
coverage_not_declared |
503 en el calendario |
invalid_input |
validation_error |
MCP, todas las herramientas |
invalid_input |
batch_too_large |
el tope de lote (ahora un 422, no un fallo de validación) |
Cabeceras (38-04)
| vieja | nueva | nota |
|---|---|---|
X-Request-Id |
X-Correlation-ID |
se acepta del cliente y se devuelve en TODA respuesta |
X-Quota-Limit |
RateLimit-Limit |
— |
X-Quota-Remaining |
RateLimit-Remaining |
— |
X-Quota-Reset |
RateLimit-Reset |
⛔ además cambia el VALOR: de instante absoluto a segundos que faltan |
Retry-After se conserva. ETag + If-None-Match (304) en todo objeto individual; los catálogos
declaran Cache-Control.
Tokens de sort (38-12 + retoque de 38-07)
⭐ Los tokens de ordenación se publican SÓLO en inglés. El retoque retiró los alias en español y renombró la familia de estado.
| token retirado | sustituto |
|---|---|
relevancia |
relevance |
recientes |
filedOn:desc |
antiguas |
filedOn:asc |
estado / estado:asc / estado:desc |
status / status:asc / status:desc |
fechaActualizacion:asc / fechaActualizacion:desc |
retirado sin sustituto (ordenaba por una fecha de NUESTRA tubería, no un hecho de INAPI) |
Los seis campos que sobreviven, cada uno asc|desc: status, filedOn, denomination,
expiresOn, registeredOn, publishedOn — más relevance. Un token no listado es un 400
validation_error.
Los cambios de FORMA — lo que no se migra renombrando
Estos no son equivalencias de nombre: son cambios de forma que un consumidor tiene que cablear de nuevo.
(a) El sobre — UNA forma para toda colección
📌 HISTORIA — del 2026-09-20 al 2026-09-23 hubo DOS sobres. Las colecciones de marcas (
GET /trademarks,POST /trademarks/search, el lote,GET /parties/{id}/trademarks) usaban{ items, nextCursor, dataAsOf, estimatedTotal }(el lote,{ items, notFound, dataAsOf }). Desde el[BREAK]del 2026-09-23 noche el sobre es uno, sin excepción — ver § «2026-09-23 · sobre único».
{ "results": [ /* … */ ], "limit": 20, "next": "eyJvIjoyMH0", "hasMore": true, "total": 14,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" } }
Sustituye a diez sobres, seis paginaciones y tres valores por defecto de limit en TODAS las
colecciones. Los nombres data, items, nextCursor y el array desnudo dejan de existir. Un
recurso individual responde el objeto plano, sin envoltura, con la frescura en cabeceras
(Iris-Data-As-Of, Iris-Coverage-Through).
totalsólo viaja cuando es exacto y barato; donde contar cuesta un barrido, la clave no está. La estimación de la búsqueda viaja comometa.estimatedTotal(cota inferior), nunca comototal.- ⛔ Ningún parámetro cambia el TIPO de la respuesta.
?envelope=se retira: los cuatro endpoints que devolvían un array desnudo por defecto ahora devuelven siempre el sobre, igual que el MCP. Es la primera vez que REST y MCP coinciden en esto.
(b) La paginación — un solo cursor
limit (defecto 20, máximo 100) + cursor opaco keyset. El offset se retira. Un
?offset= rezagado es un 400 validation_error que nombra el sustituto. Sobre 10 M de anotaciones
el offset es lento y miente sobre el total; el cursor se corta al llegar al tope en vez de ofrecer una
página que nadie puede defender. Un cursor emitido para otra ordenación degrada a la página uno, no
a una página falsa.
(c) La etiqueta — de cadena negociada a objeto de TRES idiomas
seccionEtiqueta/seccionActoEtiqueta/categoriaEtiqueta (hoy categoryLabel)/ambitoEtiqueta (hoy scopeLabel)/renovacion.etiqueta
eran una cadena negociada por Accept-Language. Ahora cada etiqueta es un LocalizedString con
los tres idiomas a la vez, null donde no hay traducción:
{ "code": "registered",
"label": { "es-CL": "Registrada", "en": "Registered", "pt-BR": "Registrada" },
"source": { "label": "(R) Registrada" } }
- La negociación por cabecera (
Accept-Language) se retira (un agente MCP no manda cabeceras, y una respuesta que depende de una cabecera no se cachea). - La respuesta es idéntica con cualquier
Accept-Languagey sin ninguna.
(d) El colapso por evento — pasa a ser el DEFECTO (38-08)
Antes, una anotación con copias del mismo hecho (Estado Diario y la ficha de expediente publicando lo mismo) se
devolvía una por fila salvo que pidieras ?dedupe=true. Ahora el colapso es el defecto: cada
hecho se devuelve una vez, y quien quiera ver las copias las pide con dedupe=false. El
colapso es lógico: nunca borra una fila — las copias siguen publicadas en duplicates[].
Cada anotación gana dos campos siempre presentes: versionsOfFact (cuántas filas describen este MISMO
hecho) y versionsDiffer (true cuando existe otra versión no idéntica ni contenida). El aviso es
neutral: dice QUE hay otra versión y CÓMO pedirla, nunca CUÁL la dice (la procedencia sale del
contrato). Garantía: renewals/lastRenewalOn dan lo mismo con dedupe=true y con
dedupe=false.
(e) Los errores — RFC 9457, un solo cuerpo
Content-Type: application/problem+json, el mismo cuerpo en REST, en el servicio de trabajos y en
MCP:
{ "type": "https://api.tarno.cl/problems/validation_error",
"title": "Request validation failed", "status": 400,
"detail": "`offset` fue retirado del contrato…", "code": "validation_error",
"requestId": "74c953c7-…", "errors": [ { "field": "offset", "code": "custom", "detail": "…" } ] }
code es lo que un cliente compara, y está siempre en inglés. title/detail son para humanos y
pueden cambiar sin ser un [BREAK]; cambiar un code sí lo es. requestId es el mismo valor que
X-Correlation-ID. Un 5xx no lleva detalle interno al cliente.
| estado | significa |
|---|---|
| 400 | validación — la petición está mal formada o un parámetro fuera de rango |
| 404 | no existe — el recurso no está, o no es tuyo (uniforme entre inquilinos) |
| 422 | regla de negocio — la petición es VÁLIDA y aun así no se puede atender |
(f) La semántica de «no hay valor» en la marca (38-05)
El detalle y el informe declaraban los mismos campos con dos semánticas de nulo (uno los omitía, el
otro los daba null). Gana null: los once escalares de la solicitud (registrationNumber,
status, signType, filedOn, expiresOn, publishedOn, registeredOn, translation,
imageDescription, protectionDescription, imageUrl) están siempre presentes, null cuando no
tienen valor. ⚠ La excepción se conserva: category/scope (antes categoria/ambito, y sus etiquetas) siguen
omitiéndose cuando «no lo sabemos» (el 5,5 % de las marcas).
Qué hacer: si distinguías "nroRegistro" in obj de obj.nroRegistro === null, ahora sólo ocurre
lo segundo para esos once. ?? valorPorDefecto sigue funcionando igual; Object.hasOwn(...) sobre
ellos ahora es siempre true. El centinela '0' de INAPI sigue sin publicarse (antes omitido,
ahora null).
(g) La persona pasa a ser parties — una entidad con papel (38-06)
Titular, solicitante, representante y oponente son la misma entidad con un role allí donde
interviene — y la misma parte deja de aparecer tres veces. territory se tipa (códigos CON sus
nombres, unknownCommune como campo propio; null = parte extranjera). trademarkCount no filtra:
las personas sin ninguna marca siguen saliendo con su cero delante.
2026-09-23 · sobre único — el [BREAK] que cierra los cabos del contrato
Un solo cambio incompatible, fechado el 2026-09-23 (noche), registrado en CHANGELOG-CONTRACT.md:
| antes | después |
|---|---|
marcas: { items, nextCursor, dataAsOf, estimatedTotal, facets, mode } |
el sobre común: { results, limit, next, hasMore, meta } — meta.dataAsOf, meta.coverageThrough, meta.estimatedTotal, meta.facets, meta.mode |
lote: { items, notFound, dataAsOf } |
el mismo sobre, meta.notFound, total exacto, 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 en la marca: rut/sufijo |
tax_id/suffix (como /parties) |
un parámetro desconocido se ignoraba (200) |
400 validation_error, una entrada de errors[] por clave; MCP: error de entrada |
?envelope=, expand en la lista de marcas: ignorados |
400 |
GET /trademarks/{n}: dedupe defecto false |
defecto true (también en GET /trademarks/{n}/annotations, que ahora lo acepta) |
| el lote ignoraba los demás filtros | los APLICA; meta.notFound = sólo lo que no existe; limit/cursor/sort/minScore/q/denomination/facets con el lote → 400 |
catálogos sin Cache-Control (salvo /holidays) |
Cache-Control de catálogo en /nice-classes, /sections, /legal-norms y sus objetos |
| — | filtro nuevo goodsAndServices (texto de productos y servicios) |
sort=status por el literal de INAPI |
por el status publicado (el derivado) |
Acción para el consumidor (checklist)
- Cambia la base de las URLs: quita el prefijo
/v1y aplica el mapa de rutas (§1). Sin redirección: una URL vieja responde ausencia, no un301. - Aplica el mapa de campos (§2) a todo lo que deserialices, y el de herramientas (§3) a toda llamada MCP.
- Rehace las lecturas de colección contra el sobre
results[](§a) y el cursor (§b): fueradata,items,nextCursor, el array desnudo yoffset— en TODAS las colecciones, marcas incluidas. - Deja de negociar
Accept-Language: las etiquetas vienen en un objeto de tres idiomas (§c). - Asume el colapso por defecto (§d): si necesitas las copias, pídelas con
dedupe=false. - Migra los cuerpos de error a RFC 9457 y los códigos/cabeceras de los mapas menores.
- Corrige los literales de
sorta los seis campos en inglés (§sort). - Verifica contra la referencia generada:
https://docs.tarno.cl.
Para ejecutarla con un asistente paso a paso, usa migracion-38-prompt.md.
Fuentes de los mapas: CHANGELOG-CONTRACT.md 38-04..38-14 + retoques ·
contract/openapi.generated.yaml (la referencia generada, no duplicada aquí).