Migración al contrato del 2026-09-23 — prompt para Claude Code
Este fichero contiene un prompt listo para ejecutar que migra automáticamente tu integración con la
API de Tarno (api.tarno.cl) al contrato del 2026-09-23 (el corte). Está pensado para que tú,
consumidor de la API, lo pegues en Claude Code (u otro agente) abierto en tu propio repositorio de
integración.
⚠ Esto SÍ rompe. A diferencia de la migración v1.6, aquí no hay ventana ni parámetros que «sigan funcionando»: el día del corte
/v1deja de responder y ninguna URL vieja sobrevive. Este prompt es para ejecutarlo a tiempo, con la guía completa (migracion-38.md) al lado.
Cómo usarlo
- Abre Claude Code en la raíz del repositorio donde consumes la API de Tarno (REST
api.tarno.cly/o el servidor MCPmcp.tarno.cl). - Copia todo el bloque de abajo (entre las líneas
─────) y pégalo como mensaje. - Revisa el diff que proponga, corre tus tests y haz commit.
Eres un ingeniero migrando la integración de ESTE repositorio con la API de Tarno (REST base
`https://api.tarno.cl`, servidor MCP `https://mcp.tarno.cl`) al contrato del 2026-09-23. El día del
corte, el prefijo `/v1` DEJA DE RESPONDER y todo cambia a la vez: rutas sin prefijo y en inglés, campos
en inglés, un sobre, un cursor, un cuerpo de error, un vocabulario de sort y etiquetas en tres idiomas.
OBJETIVO: dejar el código apuntando al contrato nuevo SIN cambiar la lógica de negocio, solo los nombres
de ruta/campo/herramienta/cabecera y las cuatro formas nuevas (sobre, cursor, etiqueta, colapso).
Nada de lógica nueva ni dependencias nuevas.
PASO 1 — LOCALIZAR. Busca en todo el repo:
- Peticiones HTTP a `api.tarno.cl` o a rutas `/v1/*` (brands, personas, insights, feriados, freshness,
sync-runs, watch, oppositions).
- Llamadas a herramientas MCP de Tarno: `search_brands`, `get_brands_batch`, `find_similar_brands`,
`get_open_oppositions`, `get_brand_detail`, `get_brand_report`, `get_brand_opposition`,
`search_personas`, los `insights_*`, `get_feriados`, `get_freshness`, `get_sync_runs`, `watch_*`.
- Cabeceras de API key (`x-api-key`), `X-Request-Id`/`X-Quota-*`, y construcción de query-strings.
- Tipos/interfaces/esquemas que modelan las respuestas (marcas, personas, anotaciones, gravámenes,
insights, feriados, vigilancia).
Lista los ficheros y líneas encontrados antes de tocar nada.
PASO 2 — RUTAS (REST). Aplica el mapa de rutas. ⛔ NO añadas redirección ni fallback: la URL vieja deja
de existir.
`GET /v1/brands` → `GET /trademarks`
`POST /v1/brands/batch` → `GET /trademarks?applicationNumber=a,b,c` (hasta 100)
`GET /v1/brands/similar?q=` → `POST /trademarks/search` { similarTo }
`GET /v1/brands/{n}/similar` → `POST /trademarks/search` { similarToTrademark }
`GET /v1/oppositions/open` → `POST /trademarks/search` { oppositionWindow: "open" }
`GET /v1/brands/{n}` → `GET /trademarks/{applicationNumber}`
`GET /v1/brands/{n}/report` → `GET /trademarks/{applicationNumber}?expand=parties,annotations,encumbrances,classes,norms`
`GET /v1/brands/{n}/opposition` → `GET /trademarks/{n}/annotations?family=opposition`
`GET /v1/personas` → `GET /parties`
`GET /v1/insights/{filings-over-time|by-estado|by-class|by-holder|by-representante}` →
`GET /insights/trademarks?groupBy={filedMonth|status|niceClass|holder|representative}`
`GET /v1/feriados` y `/v1/feriados/cobertura` → `GET /holidays` (la cobertura va en `meta.coverage`)
`GET /v1/freshness` → `GET /system/freshness` · `GET /v1/sync-runs` → `GET /system/sync-runs`
`GET /v1/watch*` → `/watch/applications` + `/watch/hits` (⚠ las `/watchlists` del corte se
retiraron el 2026-10-04: NO migres a ellas; la vigilancia es por solicitud, ver `watch.md#retired`)
PASO 3 — CAMPOS (respuestas y filtros). Aplica el mapa de campos. Claves en inglés:
`nroSolicitud`→`applicationNumber` · `nroRegistro`→`registrationNumber` · `denominacion`→`denomination`
· `estado`→`status` · `tipoSigno`→`signType` · `fechaPresentacion`→`filedOn` ·
`fechaPublicacion`→`publishedOn` · `fechaRegistro`→`registeredOn` · `fechaVencimiento`→`expiresOn` ·
`seccion`→`section` · `seccionNombre`→`sectionName` · `seccionEtiqueta`→`sectionLabel` ·
`seccionTipo`→`sectionFamily` · `seccionActo`→`act` · `seccionActoNombre`→`actName` ·
`seccionActoEtiqueta`→`actLabel` · `observacion`→`observation` ·
`observacionCompleta`→`observationDerived` · `personas`→`parties` ·
`personasHistoricas`→`formerParties` · `anotaciones`→`annotations` · `gravamenes`→`encumbrances` ·
`clases`→`classes` · `clasesHistoricas`→`formerClasses` · `clase`→`number` ·
`descripcion`→`goodsAndServices` · `titulares`→`holders` · `representantes`→`representatives` ·
`renovaciones`→`renewals` · `ultimaRenovacion`→`lastRenewalOn` · `ventanaOposicion`→`oppositionWindow` ·
`estadoDerivado`→`status` (⚠ desde 2026-09-23, `D11`: `derivedStatus` se retiró y el literal de INAPI
viaja en `statusInapi` sólo cuando difiere) · `estadoDesactualizado`→`statusStale` · `variantes`→`duplicates` ·
`vigencia`→`relation` · `soloVigentes`→`liveOnly` · `traduccion`→`translation` ·
`descripcionEtiqueta`→`imageDescription` · `imagenUrl`→`imageUrl` · `fecha`→`date` ·
`nombre`→`name` · `pais`→`country` · `rol`→`role` · `identificador`→`taxId`.
Para `parties` además: `tipo`→`kind` · `tipoOrigen`→`kindSource` · `observacion`→`jurisdictionClause` ·
`nombrePublicado`→`publishedName` · `revision`→`review` (objeto `{reason}`) ·
`region`/`comuna`/`regionNombre`/`comunaNombre` → `territory` (`{regionCode,regionName,communeCode,communeName,unknownCommune}`) ·
`marcasTotal`→`trademarkCount`.
⛔ NO renombres: `categoria`/`ambito` y sus etiquetas conservan su nombre; `protectionDescription`
conserva el suyo. ⛔ Los VALORES de código siguen en español (`status: "en_tramite"`, `signType:
"mixta"`, `classes[].status: "concedida"`): no traduzcas los literales.
PASO 4 — HERRAMIENTAS MCP. Aplica el mapa de herramientas (sin alias):
`search_brands`/`get_brands_batch`→`list_trademarks` · `find_similar_brands`→`search_trademarks`
(similarTo/similarToTrademark) · `get_open_oppositions`→`search_trademarks` (oppositionWindow:"open")
· `get_brand_detail`→`get_trademark` · `get_brand_report`→`get_trademark` (expand=) ·
`get_brand_opposition`→`list_trademark_annotations` (family=opposition) ·
`search_personas`→`list_parties`/`get_party`/`list_party_trademarks` · los `insights_*`→
`get_trademark_insights` (groupBy=…) · `get_feriados`/`get_feriados_cobertura`→`list_holidays` ·
`get_freshness`→`get_system_freshness` · `get_sync_runs`→`list_sync_runs` · los `watch_*`→
`watch_application`/`unwatch_application`/`list_watched_applications`/`list_similarity_hits`
(⚠ las diez `*_watchlist*` del corte se retiraron el 2026-10-04: NO migres a ellas).
⚠ Y hay **14 herramientas NUEVAS** que no migran de nada: `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`.
PASO 5 — LAS CUATRO FORMAS NUEVAS (no es renombrar, es religar):
(a) SOBRE: ⛔ HAY DOS, NO UNO (corregido 2026-09-23, medido contra produccion).
- `GET /trademarks` y `POST /trademarks/search`: `{ items, nextCursor, dataAsOf,
estimatedTotal }` (+ `facets` y `mode` en la busqueda). El lote: `{ items, notFound,
dataAsOf }`.
- TODO LO DEMAS: `{ results[], limit, next, hasMore, total?, meta }`.
Elimina `data`, el array pelado y el parametro `?envelope=`. ⛔ NO elimines
`items`/`nextCursor`: los necesitas para la lista y la busqueda de marcas. El recurso
individual es objeto plano.
(b) CURSOR: `limit` (defecto 20, máx 100) + `cursor` opaco. ELIMINA `offset` y `since` (watch).
(c) ETIQUETA: deja de leer una cadena negociada por `Accept-Language`; cada código trae
`label: { "es-CL", "en", "pt-BR" }` con los tres idiomas y `null` donde no hay. No mandes la
cabecera.
(d) COLAPSO: el colapso por evento es el DEFECTO (una fila por hecho). Para ver las copias, pide
`dedupe=false` (y lee `versionsOfFact`/`versionsDiffer`).
PASO 6 — ERRORES, CABECERAS Y SORT:
(a) ERRORES: cuerpo RFC 9457 `application/problem+json` con `code` en inglés. Migra los códigos:
`fuera_de_cobertura`→`out_of_coverage` · `cobertura_no_declarada`→`coverage_not_declared` ·
`invalid_input`→`validation_error` (MCP) o `batch_too_large` (tope de lote). 400=validación,
404=no existe, 422=regla de negocio.
(b) CABECERAS: `X-Request-Id`→`X-Correlation-ID` · `X-Quota-Limit`→`RateLimit-Limit` ·
`X-Quota-Remaining`→`RateLimit-Remaining` · `X-Quota-Reset`→`RateLimit-Reset` ⚠ y `RateLimit-Reset`
ahora es SEGUNDOS QUE FALTAN, no un instante absoluto.
(c) SORT: tokens SÓLO en inglés. `relevancia`→`relevance` · `recientes`→`filedOn:desc` ·
`antiguas`→`filedOn:asc` · `estado`→`status` (y `estado:asc|desc`→`status:asc|desc`) ·
`fechaActualizacion:*` se retira sin sustituto. Campos ordenables: `status`, `filedOn`,
`denomination`, `expiresOn`, `registeredOn`, `publishedOn` (cada uno `asc|desc`), más `relevance`.
PASO 7 — VERIFICAR. Corre los tests/typecheck del repo. Revisa que:
- No queda ninguna URL `/v1/` ni parámetro `offset`/`since`/`envelope` ni cabecera `Accept-Language`
para etiquetas.
- Los tipos de respuesta modelan `results[]` + `meta` y el objeto `label` de tres idiomas.
- El manejo de errores lee `code` (en inglés) y respeta `RateLimit-Reset` como delta.
- No queda ningún literal de sort en español.
PASO 8 — RESUMEN. Devuelve una tabla de ficheros cambiados con el mapeo aplicado por línea, y una lista
de puntos que requieran decisión humana (p. ej. una paginación con `offset` que no tiene cursor
equivalente, o un `estado`/`tipoSigno` cuyo valor exacto haya que confirmar contra la referencia).
RESTRICCIONES: no cambies la lógica de negocio ni añadas dependencias; cambios mínimos y mecánicos; no
inventes rutas, campos ni herramientas que no existan en la referencia generada (`https://docs.tarno.cl`).
Referencia rápida (para revisión humana)
La guía completa (no-prompt), en tres idiomas, es migracion-38.md (ES), junto a
migracion-38.en.md y migracion-38.pt.md. El esquema
autoritativo campo a campo es la referencia generada: https://docs.tarno.cl.