Ir para o conteúdo

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 /v1 deja 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

  1. Abre Claude Code en la raíz del repositorio donde consumes la API de Tarno (REST api.tarno.cl y/o el servidor MCP mcp.tarno.cl).
  2. Copia todo el bloque de abajo (entre las líneas ─────) y pégalo como mensaje.
  3. 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.