Saltar a contenido

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 /v1 deja 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 mapa viejo → 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 (en parties[] de la marca) y filters.clase → filters.niceClass (vigilancia). Y parties[].kind de la marca publica ya el vocabulario de /parties (natural|legal|unknown), no juridica/desconocido. Tabla exacta en CHANGELOG-CONTRACT.md.
  • protectionDescription conserva su nombre.
  • Los VALORES de código se conservan en castellano. status sigue 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 sustituyen watch_application, unwatch_application, list_watched_applications y list_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_coverage estaba aquí mal listada como renombre de un list_system_coverage que 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).

  • total sólo viaja cuando es exacto y barato; donde contar cuesta un barrido, la clave no está. La estimación de la búsqueda viaja como meta.estimatedTotal (cota inferior), nunca como total.
  • ⛔ 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-Language y 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)

  1. Cambia la base de las URLs: quita el prefijo /v1 y aplica el mapa de rutas (§1). Sin redirección: una URL vieja responde ausencia, no un 301.
  2. Aplica el mapa de campos (§2) a todo lo que deserialices, y el de herramientas (§3) a toda llamada MCP.
  3. Rehace las lecturas de colección contra el sobre results[] (§a) y el cursor (§b): fuera data, items, nextCursor, el array desnudo y offset — en TODAS las colecciones, marcas incluidas.
  4. Deja de negociar Accept-Language: las etiquetas vienen en un objeto de tres idiomas (§c).
  5. Asume el colapso por defecto (§d): si necesitas las copias, pídelas con dedupe=false.
  6. Migra los cuerpos de error a RFC 9457 y los códigos/cabeceras de los mapas menores.
  7. Corrige los literales de sort a los seis campos en inglés (§sort).
  8. 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í).