Saltar a contenido

Vigilancia de parecidos

Vigilancia responde a una pregunta: ¿qué marcas se parecen a la mía? Eliges una solicitud que ya existe en INAPI, por su número, y Tarno busca sus parecidas entre las solicitudes vivas del corpus. Tú lees el resultado por cursor.

⚠ [BREAK] 2026-10-04. La vigilancia por watchlists (listas por cliente, con ítems, filtros, webhook y secreto de firma) se retiró de una vez, sin periodo de convivencia. Esta página describe el modelo que la sustituye. Qué desapareció y por qué se reemplaza: más abajo.

El esquema completo y siempre actualizado por campo vive en la referencia OpenAPI interactiva en /docs (Scalar). Esta guía explica el contrato de Vigilancia y enlaza a esa referencia — no reformula el esquema. Cuando un campo no está documentado aquí, /docs es autoritativo.

A lo largo de la guía la URL base se escribe como $TARNO_BASE_URL y la clave como $TARNO_API_KEY, y cada llamada lleva el encabezado X-API-Key — igual que en la guía de primeros pasos y la guía de autenticación.

Qué es Vigilancia

  • Vigilas una solicitud, no un nombre. Sólo se vigilan solicitudes que ya existen en INAPI, por su número (applicationNumber). Un nombre libre que todavía no es una solicitud no se vigila: para eso está la búsqueda por parecido.
  • No hay nada que configurar. La búsqueda usa los datos de la propia solicitud (su denominación, sus clases). No existen filtros, clases ni puntuación mínima por cliente: el resultado es el mismo para cualquiera que vigile esa solicitud.
  • La tabla de solicitudes vigiladas es común a todos los clientes. Si varias organizaciones vigilan la misma solicitud, la búsqueda se hace una sola vez. Lo único propio de cada organización es qué vigila. Esto tiene una consecuencia que conviene leer: no es secreta.
  • Sólo cuentan las solicitudes vivas. Una solicitud en estado terminal (rechazada, denegada, desistida, abandonada, anulada, caducado, vencida, según el estado que Tarno deriva de los actos) no entra como parecida, y tampoco se puede dar de alta para vigilarla.
  • Las marcas de Madrid (registro internacional) se vigilan y cuentan como parecidas, igual que las nacionales.
  • Una serie nueva del registro que vigilas se avisa aparte. Si vigilas una solicitud de un registro de Madrid —su número base o una de sus series—, cada una de las demás series adicionales de ese registro llega a la misma lista con relation: "series", comparta o no clase con la tuya. Cómo es.
  • Lo propio no es amenaza. Al leer, se ocultan las parecidas que tu organización también vigila.
  • No hay webhook. Las parecidas se leen por cursor con GET /watch/hits.

Son cuatro operaciones, iguales por REST y por MCP:

Operación REST MCP Scope
Vigilar una solicitud POST /watch/applications watch_application watch:write
Dejar de vigilarla DELETE /watch/applications/{applicationNumber} unwatch_application watch:write
Listar lo que vigilas GET /watch/applications list_watched_applications watch:read
Leer las parecidas GET /watch/hits list_similarity_hits watch:read

Scopes y tenencia

Vigilancia usa dos scopes, además de las mismas reglas de scopes que el resto del contrato (ver la guía de autenticación):

Scope Otorga acceso a
watch:read Lecturas: GET /watch/applications, GET /watch/hits.
watch:write Escrituras: POST /watch/applications, DELETE /watch/applications/{applicationNumber}.

Una clave sin scopes recibe los scopes de lectura base, watch:read incluido, pero no watch:write: ese se concede siempre explícitamente. Una clave con scopes no vacíos recibe solo los listados; llamar a una ruta cuyo scope requerido está ausente se rechaza con 403 forbidden nombrando el scope faltante. El scope se comprueba antes de validar la entrada: sin él, una petición mal formada responde 403, no 400.

La organización se resuelve desde la clave de API (el consumerId de la clave), nunca desde el cuerpo de la solicitud. Consecuencias:

  • Una clave sin organización (consumerId nulo) no puede usar Vigilancia → 403 forbidden (detail: API key has no owning org), aunque tenga los scopes.
  • Cada clave ve sólo lo que vigila su organización y las parecidas de eso. Dejar de vigilar algo que tu organización no vigila —lo vigile otra o no— responde un 404 uniforme.

En resumen: para usar Vigilancia una clave necesita a la vez una organización y los scopes watch:*.

Vigilar una solicitud

POST /watch/applications ≡ watch_application — scope watch:write.

Cuerpo:

Campo Tipo Notas
applicationNumber string Número de solicitud de INAPI: de 1 a 12 dígitos, o una serie adicional de un registro de Madrid (nueve dígitos, guion y el sufijo de INAPI: 991652209-2). Una serie se vigila por separado, con sus propias clases.

El cuerpo es estricto: cualquier otra clave es un 400 validation_error.

Respuesta — una WatchedApplication:

Campo Tipo Notas
applicationNumber string La solicitud vigilada.
watchedSince string (fecha-hora ISO) Desde cuándo la vigila tu organización.
baselineStatus 'pending' | 'done' Estado de la búsqueda inicial de esa solicitud.
baselineAt string (ISO) | null Cuándo terminó la búsqueda inicial; null mientras está pending.
terminalSince string (ISO) | null Desde cuándo el servicio ve la solicitud en un estado terminal; null mientras está viva. Ver cuándo termina una vigilancia.
watchEndsOn AAAA-MM-DD | null Último día de la vigilancia de una solicitud terminal (día de Chile); al día siguiente termina sola. No es un plazo legal.
watchEndBasis string | null De dónde sale ese día: appeal_close, grace_end, rejection_margin o expiry_margin.
  • 201 — la solicitud queda vigilada por tu organización.
  • 200 — tu organización ya la vigilaba: devuelve la misma vigilancia y no consume el tope diario. Excepción: si la solicitud ya está en estado terminal (aunque su vigilancia siga hasta watchEndsOn), repetir el alta responde 422 application_terminal.

Por MCP, watch_application devuelve ese mismo cuerpo y no distingue un alta nueva de una repetida: la diferencia 201 / 200 sólo existe en REST.

La llamada responde al momento: la búsqueda de parecidas no se hace dentro de la petición (ver la búsqueda inicial).

curl

curl -sS -X POST "$TARNO_BASE_URL/watch/applications" \
  -H "X-API-Key: $TARNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "applicationNumber": "1234567" }'
{
  "applicationNumber": "1234567",
  "watchedSince": "2026-10-04T15:02:11.000Z",
  "baselineStatus": "pending",
  "baselineAt": null,
  "terminalSince": null,
  "watchEndsOn": null,
  "watchEndBasis": null
}

TypeScript (fetch)

const res = await fetch(`${process.env.TARNO_BASE_URL}/watch/applications`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TARNO_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ applicationNumber: "1234567" }),
});

if (!res.ok) {
  // Problem Details (RFC 9457): { type, title, status, detail?, code, requestId, errors? }
  const problem = await res.json();
  throw new Error(`${res.status} ${problem.code}: ${problem.detail ?? problem.title} (requestId=${problem.requestId})`);
}

const watched = await res.json(); // 201 = alta nueva · 200 = ya la vigilabas

Qué se rechaza

HTTP code Cuándo
400 validation_error Un número que no son de 1 a 12 dígitos ni una serie de Madrid (991652209-2), o una clave de más en el cuerpo.
404 not_found La solicitud no existe en el corpus. detail: trademark N not found.
422 application_terminal La solicitud existe pero su estado es terminal. El estado viaja en applicationStatus (y en detail). No se vigila.
422 watch_limit_reached Tu organización ya tiene el máximo de solicitudes vigiladas activas de su plan. El máximo viaja en limit.
429 watch_daily_limit_reached Tu organización agotó las altas de hoy. Lleva limit (el tope) y resetsAt (cuándo se reabre).
503 service_unavailable No responde el almacén de vigilancias o la base donde se lee el tope del plan. Reintentable.

applicationStatus, limit y resetsAt son miembros del primer nivel del cuerpo de error, junto a code y detail — no van dentro de otro objeto. El 429 de este tope no lleva la cabecera Retry-After: el instante de reapertura es resetsAt.

{
  "type": "https://api.tarno.cl/problems/watch_daily_limit_reached",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "the daily limit of 500 new watched applications is reached; it resets at 2026-10-05T03:00:00.000Z",
  "code": "watch_daily_limit_reached",
  "requestId": "…",
  "limit": 500,
  "resetsAt": "2026-10-05T03:00:00.000Z"
}
{
  "type": "https://api.tarno.cl/problems/application_terminal",
  "title": "Business rule not satisfied",
  "status": 422,
  "detail": "application 1234567 is in a terminal status (rechazada) and cannot be watched",
  "code": "application_terminal",
  "requestId": "…",
  "applicationStatus": "rechazada"
}

Dejar de vigilar

DELETE /watch/applications/{applicationNumber} ≡ unwatch_application — scope watch:write.

Devuelve 204 No Content. Si tu organización no vigilaba esa solicitud, 404 not_found (detail: application N is not watched), la vigile otra organización o no.

Por MCP no existe una respuesta vacía, así que unwatch_application devuelve { "applicationNumber": "1234567", "watched": false }.

curl -sS -X DELETE "$TARNO_BASE_URL/watch/applications/1234567" -H "X-API-Key: $TARNO_API_KEY"

Al dejar de vigilar una solicitud, sus parecidas dejan de aparecer en tus lecturas y se libera un hueco de tu plan. El alta que hiciste sigue contando para el tope diario de ese día.

Listar lo que vigilas

GET /watch/applications ≡ list_watched_applications — scope watch:read. Lista las solicitudes que tu organización vigila ahora (las que dejaste de vigilar no aparecen).

Query Tipo Notas
cursor string Cursor opaco de keyset. Trátalo como caja negra.
limit integer Tamaño de página. Por defecto 50, máximo 200.

Respuesta: el sobre común — { results: WatchedApplication[], limit, next, hasMore, meta }, de la suscripción más antigua a la más reciente. next: null (y hasMore: false) = fin, misma semántica de keyset que en primeros pasos. Un cursor ilegible no es un error: se sirve la primera página.

Esta lista no lee el corpus, así que meta.dataAsOf es siempre null.

Cada elemento trae además terminalSince, watchEndsOn y watchEndBasis: los tres son null mientras la solicitud está viva, y anuncian el final de la vigilancia cuando su estado pasa a terminal (cómo cambia una vigilancia con el tiempo). Una vigilancia que ya terminó no aparece en esta lista.

curl -sS "$TARNO_BASE_URL/watch/applications?limit=50" -H "X-API-Key: $TARNO_API_KEY"

La búsqueda inicial

La primera vez que alguien vigila una solicitud, Tarno la cruza contra todo el corpus. Esa búsqueda tarda segundos y corre en segundo plano, de una en una:

  1. El alta responde al momento, con baselineStatus: "pending".
  2. Cuando la búsqueda termina, la solicitud pasa a baselineStatus: "done" y baselineAt trae la fecha. Lo ves en GET /watch/applications.
  3. A partir de ahí sus parecidas están en GET /watch/hits. Mientras está pending, la lista de parecidas de esa solicitud puede estar vacía: vacía y pending no significa «sin parecidas».

Si otra organización ya vigilaba la solicitud y su búsqueda inicial estaba hecha, tu alta responde con baselineStatus: "done" y las parecidas están disponibles de inmediato: no se repite la búsqueda.

Una búsqueda inicial que falla se reintenta sola, con esperas cada vez más largas (60 s, 120 s, 240 s… hasta un máximo de 6 h entre intentos). No hay un estado «fallida»: la solicitud sigue en pending hasta que la búsqueda termina. Una búsqueda en la que alguno de los canales del motor (léxico, fonético o, si está configurado, el semántico) se degradó cuenta como fallida: no se da por terminada con parecidas incompletas.

Quién va primero. Las búsquedas iniciales se hacen en serie, de una en una, y las organizaciones se turnan: la siguiente es la de la organización a la que hace más tiempo que no se le atiende una, y dentro de una organización, su alta más antigua. Así, quien da de alta 500 solicitudes de golpe no deja esperando detrás de todas ellas a quien dio de alta una. El turno se cuenta sobre todas las suscripciones de la organización, activas o retiradas: dejar de vigilar lo ya buscado no adelanta en la cola. Una búsqueda que falla también gasta el turno. Y una solicitud que vigilan varias organizaciones es una sola búsqueda que sirve a todas. Lo que esto no promete: un plazo. Con muchas altas pendientes, la tuya espera a que le llegue el turno.

La búsqueda recorre como mucho 2.000 resultados del motor por solicitud (20 páginas de 100). El motor agrupa en un solo resultado las solicitudes hermanas (misma denominación y mismo titular), y cada hermana se guarda como una parecida propia, así que las parecidas guardadas pueden ser más de 2.000.

Leer las parecidas

GET /watch/hits ≡ list_similarity_hits — scope watch:read.

Query Tipo Notas
cursor string Cursor opaco de keyset. Trátalo como caja negra.
limit integer Tamaño de página. Por defecto 50, máximo 200.
applicationNumber string Opcional. Sólo las parecidas de esa solicitud vigilada. Si tu organización no la vigila, la respuesta es 200 con una página vacía — no un 404.

Respuesta: el sobre común — { results: SimilarityHit[], limit, next, hasMore, meta }, en el orden en que tu organización pudo leer cada parecida: visibleSince ascendente y, a igualdad, id.

Esta lista es un feed, y su paginación tiene una regla propia: next viene siempre —también en la última página y con la lista vacía—, y el fin de la lectura lo marca hasMore: false, no next: null. Para la página siguiente, reenvía next sin cambios como cursor; al terminar, guarda el último next: es el cursor con el que pedir más tarde sólo lo nuevo (cómo). Un cursor ilegible no es un error: se lee desde el principio. meta.dataAsOf es la fecha del dato del corpus con que se leyó matched, como en el resto del contrato. Una página vacía no lee el corpus y lleva meta.dataAsOf: null.

curl -sS "$TARNO_BASE_URL/watch/hits?applicationNumber=1234567&limit=50" -H "X-API-Key: $TARNO_API_KEY"

Qué entra en la lista:

  • Todas las parecidas de las solicitudes que tu organización vigila, también las que se encontraron antes de que te suscribieras. Vigilar responde a «qué se parece a mi marca»; cuándo apareció cada una no cambia que sea parecida.
  • Sólo parecidas con score ≥ 0,7. El umbral es el mismo para todos los clientes y no se configura por petición. La única excepción es el aviso de serie, que no es una parecida: entra sin puntaje.
  • Entre 0,7 y 0,8, sólo si la parecida lleva una palabra de la denominación vigilada, igual o a una letra de distancia («NOMADES» → «NOMADE», «CMP» → «CMPC»). Cuentan las palabras propias de la vigilada que son poco frecuentes en sus clases (menos de 50 marcas), sin sus términos genéricos; si no tiene ninguna poco frecuente, vale cualquiera de las suyas; si sólo tiene términos genéricos, no entra nada de esa franja. Las cifras pegadas a letras se separan antes de comparar («NOMADE98» → «nomade 98»). Así no entran las que sólo comparten una palabra corriente del oficio («SL Abogados» → «Abogados Cordillera»). Desde 0,8 no cambia nada. La búsqueda de parecidas (similarTo, similarToTrademark), la ventana de oposición y la disponibilidad no aplican esta regla.
  • Si la denominación vigilada tiene 1 o 2 letras o cifras («Q», «TE», «+B», «B5»; sin contar signos ni espacios, tras quitar mayúsculas y tildes), sólo entran parecidas de 1 a 3 letras o cifras, con cualquier score: las idénticas y las cortas que suenan igual («Q» → «K», «W» → «V»). Una letra suena igual que cualquier inicial suelta de un nombre largo, y sin esta regla una sigla recibía cientos de parecidas con score 1 («TE» → «THE JUNGLE BOOK», «G» → «G T D INTERNET»). Las vigiladas de 3 caracteres o más no cambian. La búsqueda de parecidas, la ventana de oposición y la disponibilidad tampoco aplican esta regla.
  • Nunca la propia solicitud vigilada.
  • No las parecidas que tu organización también vigila (lo propio no es amenaza). Si dejas de vigilar una de ellas, vuelve a aparecer como parecida de las demás.

Cómo enterarte de parecidas nuevas

No hay aviso por webhook: lees tú, y la lista te da el cursor para hacerlo sin releerla entera.

  1. Primera lectura, sin cursor. Pagina reenviando next mientras hasMore sea true.
  2. Cuando hasMore es false, guarda ese next: es tu posición.
  3. La próxima vez, envía esa posición como cursor. Recibes sólo lo que tu organización pudo leer después. Si no hay nada, la página viene vacía y next es el mismo cursor que enviaste.

⚠ No iteres «hasta que next sea nulo»: en esta lista nunca lo es. Un cliente que lo haga se queda pidiendo la misma página vacía para siempre. El fin es hasMore: false.

Qué es «nuevo». El orden no es el de detección, sino el instante en que cada parecida pasó a ser legible para tu organización (visibleSince): el más tardío entre cuándo se detectó, cuándo empezó tu suscripción vigente a la solicitud vigilada y la última vez que dejaste de vigilar la solicitud parecida. Por eso tu cursor recoge también lo que no es nuevo para el servicio pero sí para ti:

  • las parecidas antiguas de una solicitud a la que te suscribes hoy y que otra organización vigilaba desde hace meses;
  • las que estaban ocultas por ser tuyas y reaparecen cuando dejas de vigilar esa marca (o cuando su vigilancia termina sola): llegan con su mismo id y un visibleSince nuevo;
  • las que se cerraron y vuelven: llegan con un id nuevo.

Si dejas de vigilar una solicitud y vuelves a darla de alta, es una suscripción nueva: todas sus parecidas se entregan otra vez.

Un mismo id puede llegarte más de una vez. Trata id como clave: inserta o actualiza.

Un cursor es de su filtro. El cursor que obtienes con applicationNumber=N vale para seguir leyendo con applicationNumber=N, y el que obtienes sin filtro, para seguir sin filtro. Usado con otro filtro, la lista se lee desde el principio: repite, nunca salta.

Los cursores emitidos antes del 2026-10-07 ya no se reconocen: la primera lectura con uno de ellos empieza desde el principio (una relectura completa, una sola vez).

Qué garantiza el cursor, y qué no. La lista sólo sirve parecidas ya asentadas: mientras el servicio tiene alguna operación en curso sobre la vigilancia, lo que se escribe desde que esa operación empezó espera a tu lectura siguiente. Así, una parecida que termina de guardarse tarde nunca queda por detrás del cursor que ya te llevaste: puede retrasarse —lo normal son milisegundos; unos segundos durante una tarea de mantenimiento—, no perderse. Por lo mismo, justo después de un alta la lista de esa solicitud puede venir vacía un instante: vuelve a leer con el next que recibiste. Lo que esto no cubre:

  • una operación del servicio que dure más de 60 segundos deja de retener la lista (para que una operación atascada no la congele); lo que esa operación escriba después podría quedar detrás de un cursor ya entregado. Ninguna operación normal se acerca a esa duración;
  • una corrección manual de datos hecha por el operador del servicio;
  • un cambio del umbral de score del servicio: las parecidas que pasen a superarlo no se reordenan.

Si necesitas descartar cualquiera de esos casos, una lectura sin cursor recorre siempre la lista completa.

Un cierre no se anuncia. Cuando una parecida deja de serlo (su estado pasa a terminal, o deja de parecerse) simplemente deja de salir en la lista: no hay un evento ni una fila «cerrada» que leer, y el cursor no la trae. Lo descubres con una lectura completa (sin cursor): lo que tenías guardado y ya no viene, se cerró. Si más adelante vuelve, vuelve con un id nuevo y al final de tu orden, así que tu cursor la recoge.

Forma de una parecida

Cada elemento de GET /watch/hits es una SimilarityHit:

Campo Tipo Notas
id number Identificador de la parecida mientras sigue abierta. No es el orden de la lista. Una parecida que se cierra y vuelve tiene un id nuevo.
watchedApplicationNumber string La solicitud que vigilas.
matchedApplicationNumber string La solicitud que se le parece.
relation 'series' (opcional) Sólo presente cuando la solicitud de matched es una serie adicional del mismo registro de Madrid que la solicitud vigilada, sea ésta el número base u otra serie (aviso de serie). En una parecida corriente la clave no viaja (no llega como null).
score number | null Puntaje de parecido (0..1), nunca por debajo del umbral. null sólo en un elemento con relation que el motor de parecido no encontró: no se inventa un puntaje. Sin relation es siempre un número.
signals objeto Qué vio el motor: matchedBy (los canales por los que coincide), signals (la fuerza por canal, de 0 a 1 o null) y, sólo en una hermana agrupada, representative. Ver abajo.
origin 'baseline' | 'sync' | 'series_load' Quién lo escribió: la búsqueda inicial, el motor diario (el cruce tras un sync, una parecida que vuelve o la revisión diaria), o la pasada que sigue a una carga de series de Madrid. Un aviso de serie puede llevar cualquiera de los tres.
detectedAt string (fecha-hora ISO) Cuándo se detectó. Puede ser anterior a tu alta (por qué).
visibleSince string (fecha-hora ISO, UTC, con microsegundos) Desde cuándo tu organización puede leerla: lo más tardío entre su detección, el inicio de tu suscripción vigente a la solicitud vigilada y la última vez que dejaste de vigilar la solicitud parecida. Es el orden de la lista (cómo leer lo nuevo). Nunca anterior a detectedAt.
matched BrandSummary | null La marca parecida, leída del corpus en el momento de la consulta; null si la solicitud ya no existe.

matched es la misma forma BrandSummary documentada en primeros pasos y en /docs. No es una foto congelada: trae el estado que la marca tiene hoy.

{
  "id": 4812,
  "watchedApplicationNumber": "1234567",
  "matchedApplicationNumber": "1239876",
  "score": 0.83,
  "signals": {
    "matchedBy": ["phonetic", "fuzzy"],
    "signals": { "lexical": 0.74, "semantic": null, "phonetic": 0.91 }
  },
  "origin": "baseline",
  "detectedAt": "2026-10-04T15:02:19.000Z",
  "visibleSince": "2026-10-06T09:30:00.123456Z",
  "matched": { /* BrandSummary */ }
}

signals tiene esta forma: { matchedBy: [...], signals: { canal: 0–1 }, representative?: "N" }.

  • matchedBy — los canales del motor que encontraron la parecida (exact, fuzzy, phonetic, semantic).
  • signals — la fuerza por canal (lexical, semantic, phonetic), de 0 a 1; null en un canal que no aportó.
  • representative — sólo cuando la parecida es una solicitud hermana que el motor agrupó bajo otra (misma denominación y titular): es el número de esa otra, y el score y las señales son los suyos. Si la parecida es la representante, la clave no viaja.

El esquema publica signals como un objeto abierto: el motor puede añadir claves.

Aviso directo: una serie nueva del registro que vigilas

Un registro internacional (Protocolo de Madrid) puede tener más de una serie en Chile, y cada serie adicional es una solicitud aparte con el número de la primera más un sufijo (991652209-2; ver Series de un registro de Madrid). Una serie adicional suele pedirse para otras clases, y la vigilancia busca parecidas dentro de las clases de la solicitud vigilada: por parecido, quien vigila 991652209 no se enteraría de que existe 991652209-2.

Por eso, si vigilas una solicitud de ese registro —el número base (991652209) o cualquiera de sus series (991652209-2)—, cada una de las demás series adicionales llega a GET /watch/hits como un elemento más, comparta o no clase con la tuya. El ejemplo es el de quien vigila el número base; quien vigila 991652209-2 recibe el mismo elemento con su número en watchedApplicationNumber cuando aparece 991652209-3:

{
  "id": 5120,
  "watchedApplicationNumber": "991652209",
  "matchedApplicationNumber": "991652209-2",
  "relation": "series",
  "score": null,
  "signals": {},
  "origin": "series_load",
  "detectedAt": "2026-10-12T14:03:11.000Z",
  "visibleSince": "2026-10-12T14:03:11.482913Z",
  "matched": { /* BrandSummary */ }
}

Cómo distinguirlo de una parecida:

  • relation: "series" dice que la solicitud de matched es una serie adicional del mismo registro que la vigilada: matchedApplicationNumber es el número base de la vigilada (sus nueve dígitos) + - + sufijo, y es distinto de watchedApplicationNumber. En una parecida corriente la clave no existe. No hace falta comparar los números: basta con mirar relation.
  • score es null y signals es {} cuando el motor de parecido no encontró la serie (lo normal si no comparte clase): nadie las comparó, así que no hay puntaje, y no se inventa uno.
  • Si la serie sí comparte clase y el motor también la encuentra, es el mismo elemento (un solo id), con relation: "series" y además su score y sus signals reales. Nunca hay dos elementos para la misma serie, llegue primero el aviso o la búsqueda.
  • origin dice quién escribió primero el elemento, no si es un aviso de serie ni si tiene puntaje: baseline si fue la búsqueda inicial de tu solicitud vigilada, series_load si fue la pasada que sigue a una carga de series, sync si fue el motor diario (el cruce o la revisión diaria). Un aviso puede llevar score (el motor encontró también la serie), y uno que se cerró y volvió llega con origin: "sync" y puede seguir con score: null. No deduzcas nada de origin: usa relation para saber si es un aviso de serie y score para saber si se comparó.

Qué sigue igual que en cualquier otro elemento de la lista:

  • El cursor. El aviso entra al final de tu orden (visibleSince), así que la lectura por next lo trae sin hacer nada distinto (cómo leer lo nuevo).
  • Lo propio no es amenaza. Si tu organización también vigila esa serie, el aviso se oculta.
  • Sólo solicitudes vivas. No se avisa de una serie en estado terminal, y el aviso deja de listarse si la serie pasa a terminal o deja de existir en el corpus (vuelve, con id nuevo, si revive).

Qué es distinto:

  • No se cierra por «ya no se parece». Que sea una serie de tu registro no depende del parecido: si una búsqueda posterior deja de encontrarla, el elemento sigue en la lista y sólo pierde el score (vuelve a null).

Quién lo recibe y quién no:

  • Quien vigila el número base (991652209) y quien vigila otra serie del registro (991652209-2): los dos reciben el aviso cuando aparece 991652209-3.
  • Un elemento por solicitud vigilada. Si tu organización vigila a la vez 991652209 y 991652209-2, cuando aparece 991652209-3 recibes dos elementos: uno con watchedApplicationNumber: "991652209" y otro con "991652209-2". Es lo mismo que pasa con una parecida que se parece a dos de tus solicitudes vigiladas. Con el filtro applicationNumber ves sólo los de una.
  • Nunca de la serie que ya vigilas. Quien vigila 991652209-2 no recibe aviso de 991652209-2; y si vigilas a la vez el número base y esa serie, tampoco bajo el número base (lo propio no es amenaza).
  • El número base no se avisa. Sólo son noticia las series adicionales: quien vigila 991652209-2 no recibe un aviso de que existe 991652209. Si el motor lo encuentra como parecida (comparten clase), llega como parecida corriente, con score y sin relation.

Cuándo llega, sin que tengas que hacer nada:

  • Al empezar a vigilar una solicitud del registro —el número base o una serie—: normalmente, cuando termina su búsqueda inicial ya tienes las demás series vivas del registro, compartan o no clase con la tuya (origin: "baseline"). No es una garantía ligada a baselineStatus: "done": en todo caso llegan, como muy tarde, con la revisión diaria siguiente. En particular, si vuelves a vigilar una solicitud que habías dejado de vigilar hace poco, la búsqueda no se repite (está done al momento) y las series que aparecieron entretanto llegan con la revisión diaria.
  • Cuando el servicio carga series nuevas: con la pasada que sigue a la carga (origin: "series_load") o, si no, con la revisión diaria.
  • En la revisión diaria: cualquier serie viva de tu registro que todavía no tengas en la lista —por ejemplo, una que estaba en estado terminal cuando empezaste a vigilar y después revive— (origin: "sync"). Puede tardar hasta un día; si un mismo día hubiera muchísimos avisos por escribir, el resto sale en los días siguientes.

GET /watch/hits avisa de las series vivas. La lista completa de las series de un registro, también las que están en estado terminal, es relatedSeries de la ficha.

Topes

Tope Qué limita Al superarlo
Del plan Cuántas solicitudes puede tener tu organización vigiladas a la vez (activas). 422 watch_limit_reached
Diario Cuántas altas puede hacer tu organización en un día (500 si su plan no dice otra cosa). 429 watch_daily_limit_reached
  • El tope del plan cuenta lo activo. Dejar de vigilar una solicitud libera su hueco. El número es el de tu organización (500 si no tiene otro contratado): todas sus claves de API comparten el mismo tope y el mismo recuento.
  • El tope diario cuenta altas, no lo activo. Vigilar y dejar de vigilar la misma solicitud el mismo día gasta una alta; volver a darla de alta gasta otra. Existe para que quitar y poner sin parar no agote recursos. Lo fija el plan de tu organización, como el tope del plan.
  • El día es el de Chile (America/Santiago): el contador se reinicia a la medianoche de Chile, no a la de UTC. resetsAt, en el cuerpo del 429, es ese instante (en UTC), y limit el tope. No hay cabecera Retry-After.
  • Repetir un alta que ya existe responde 200 y no gasta del tope diario (salvo si la solicitud ya es terminal: 422 application_terminal).

El tope diario y el umbral de parecido son ajustes del servicio (WATCH_DAILY_ADDS_MAX, WATCH_MIN_SCORE), iguales para todos; no se pueden cambiar por petición.

La vigilancia es global, y no es secreta entre clientes

La tabla de solicitudes vigiladas es común. Eso ahorra trabajo —una solicitud se cruza una vez aunque la vigilen diez organizaciones— y tiene un efecto que el contrato acepta a sabiendas:

Un cliente puede deducir que otra organización ya vigilaba una solicitud. Si das de alta una solicitud y la respuesta llega con baselineStatus: "done", o sus parecidas traen un detectedAt anterior a tu alta, es que alguien la vigilaba antes que tú.

Lo que no se puede saber: quién la vigila, cuántas organizaciones, ni qué más vigila nadie. Las suscripciones de otra organización nunca son legibles.

Cómo cambia una vigilancia con el tiempo

La búsqueda inicial es una foto del día del alta. Desde ahí la vigilancia se mueve sola:

El cruce diario. Cada vez que termina un sync completo del corpus, cada solicitud vigilada se compara contra las solicitudes que cambiaron desde la última vez (altas, cambios de denominación, cambios de clase) y siguen vivas. Las parecidas nuevas aparecen en GET /watch/hits con origin: "sync". Un día sin sync completo no hay cruce: esas novedades entran con el siguiente.

Cuándo deja de listarse una parecida.

  • Su estado pasa a terminal (rechazada, vencida…). El servicio lo revisa una vez al día, así que puede tardar hasta un día en desaparecer. Una rechazada con una apelación presentada no cuenta como viva: sólo manda el estado.
  • Ya no existe en el corpus, y sigue sin existir en la revisión del día siguiente: una sola ausencia no cierra nada, así que tarda entre uno y dos días (mientras tanto sale con matched: null). Si reaparece y está viva, vuelve.
  • Ya no se parece: la tuya o la otra cambió de denominación o de clases y ya no llega al umbral. (No aplica a un aviso de serie: ese sigue listado y sólo pierde el score.)

Cuándo vuelve. Si vuelve a estar viva, o vuelve a parecerse, reaparece — con un id nuevo y un detectedAt nuevo.

La búsqueda se puede repetir. Si tu solicitud vigilada cambia de denominación o de clases, o si el corpus se reprocesa en bloque, el servicio repite la búsqueda inicial de esa solicitud: baselineStatus vuelve a pending un rato y después a done. Las parecidas que ya tenías siguen legibles mientras tanto.

Cuándo termina una vigilancia. Si el estado de la solicitud que vigilas pasa a terminal, no se corta ese día: todavía puede pasarle algo. Se sigue vigilando hasta un último día, que la lista te anuncia:

watchEndBasis De dónde sale watchEndsOn
appeal_close La fecha límite para apelar el rechazo, cuando el servicio la publica como hito de la marca.
grace_end El fin del periodo de gracia de la renovación, cuando el servicio lo publica.
rejection_margin 45 días naturales tras el rechazo (o un desistimiento, abandono o anulación) sin ese hito.
expiry_margin 6 meses tras el vencimiento sin ese hito.

watchEndsOn es el último día de la vigilancia, no un plazo legal: los plazos, con su artículo, se leen en los hitos de la marca (GET /trademarks/{n} → milestones). Si la solicitud revive antes de ese día, los tres campos vuelven a null y la vigilancia sigue. watchEndsOn nunca es anterior al día en que el servicio vio la solicitud en estado terminal: si el hito o el margen ya habían pasado, ese día es el último, de modo que siempre hay al menos un día en que puedes leerlo.

Al día siguiente de watchEndsOn la vigilancia termina sola: desaparece de GET /watch/applications, sus parecidas dejan de salir en GET /watch/hits, y deja de contar para el tope de tu plan. A partir de ahí DELETE responde 404 y un alta nueva responde 422 application_terminal con su estado. Lo mismo ocurre, sin último día anunciado, si la solicitud deja de existir en el corpus y sigue sin existir en la revisión del día siguiente: una ausencia de un solo día no termina ninguna vigilancia.

Lo que nadie vigila se conserva 10 días. Cuando la última organización deja de vigilar una solicitud, el servicio la conserva 10 días con sus parecidas (y la sigue cruzando), de modo que un alta nueva en ese plazo encuentra la búsqueda ya hecha. Después se borra; un alta posterior empieza con una búsqueda inicial nueva.

Si tu organización se da de baja y vuelve. Mientras una organización está dada de baja, el servicio no vigila para ella: sus solicitudes dejan de contar para su tope y, si nadie más las vigila, dejan de buscarse y de cruzarse. Su lista se conserva. Si la organización se reactiva, la lista vuelve sola como mucho un minuto después, con el watchedSince que tenía y sin gastar el tope diario; las solicitudes que sólo ella vigilaba pasan un rato por baselineStatus: "pending" mientras se buscan de nuevo. En GET /watch/hits, todo lo que vuelve a poder leer sale después del cursor que guardó, con sus mismos id: recibirá otra vez parecidas que ya había leído, además de las nuevas. No vuelve una vigilancia que terminó por su cuenta mientras tanto. Una organización que nunca se dio de baja no nota nada de esto.

Lo que esta versión todavía no hace

  • No hay parecido por imagen (logo). La vigilancia compara sólo por texto.
  • No hay aviso por webhook ni lista de vigilancias terminadas: se lee, y el final se ve venir en watchEndsOn.

MCP

REST es equivalente a MCP: misma clave, mismos scopes, mismos esquemas, mismos códigos de error. El servidor MCP expone estas herramientas de Vigilancia:

Herramienta MCP Equivalente REST
watch_application POST /watch/applications
unwatch_application DELETE /watch/applications/{applicationNumber}
list_watched_applications GET /watch/applications
list_similarity_hits GET /watch/hits

Dos diferencias de forma, porque una herramienta MCP no tiene códigos HTTP ni respuestas vacías:

  • watch_application devuelve la misma WatchedApplication que REST y no distingue un alta nueva de una repetida (REST: 201 / 200).
  • unwatch_application devuelve { "applicationNumber": "N", "watched": false } (REST: 204 sin cuerpo).

Un rechazo llega como resultado de error con el mismo cuerpo RFC 9457 que REST —mismo code, mismo status, mismos applicationStatus / limit / resetsAt—, con requestId vacío.

El guion weekly_watch («¿qué parecidas tienen las solicitudes que vigilo?») tiene un argumento, applicationNumber, opcional. Con él, lee list_similarity_hits de esa solicitud; sin él, lee list_watched_applications (para saber qué se vigila y si su búsqueda inicial terminó) y list_similarity_hits de todas.

Consulta la guía de MCP para el endpoint, el transporte y la autenticación.

Errores

Todos los errores llevan un cuerpo RFC 9457 (application/problem+json: type, title, status, detail, code, requestId y, en un fallo de validación, errors[]) — descrito en primeros pasos. Ramifica por code.

HTTP code Cuándo
400 validation_error Entrada inválida: número de solicitud mal formado, una clave o parámetro de más.
401 unauthorized Clave ausente, malformada, desconocida o revocada.
403 forbidden Falta el scope watch:* requerido (se comprueba antes de validar la entrada), o la clave no tiene organización.
404 not_found Alta: la solicitud no existe en el corpus (trademark N not found). Baja: tu organización no la vigila (application N is not watched).
422 application_terminal La solicitud está en estado terminal y no se puede vigilar. Lleva applicationStatus.
422 watch_limit_reached Tope del plan: demasiadas solicitudes vigiladas activas. Lleva limit.
429 watch_daily_limit_reached Tope diario de altas agotado. Lleva limit y resetsAt; sin cabecera Retry-After.
503 service_unavailable El almacén de vigilancias no está disponible, o (sólo en el alta) no responde la base donde se lee el tope del plan; reintentable.

applicationStatus, limit y resetsAt son miembros del primer nivel del cuerpo. Leer las parecidas de una solicitud que tu organización no vigila no es un error: 200 con una página vacía. El status y el cuerpo de cada code son los mismos por REST y por MCP.

Qué se retiró el 2026-10-04

Las diez operaciones de watchlists dejaron de existir, en los dos transportes y sin periodo de convivencia: las rutas REST ya no existen y las herramientas ya no están en tools/list.

Retirada (MCP) Retirada (REST) Qué usar ahora
create_watchlist POST /watchlists watch_application, una llamada por solicitud
add_watchlist_item POST /watchlists/:id/items watch_application
remove_watchlist_item DELETE /watchlists/:id/items/:itemId unwatch_application
delete_watchlist DELETE /watchlists/:id unwatch_application, una por solicitud
list_watchlists GET /watchlists list_watched_applications
get_watchlist GET /watchlists/:id list_watched_applications
list_watchlist_items GET /watchlists/:id/items list_watched_applications
list_watchlist_hits GET /watchlists/:id/hits list_similarity_hits
update_watchlist PATCH /watchlists/:id — (no hay nada que configurar)
list_watchlist_deliveries GET /watchlists/:id/deliveries — (no hay webhook)

Con ellas desaparecen:

  • Las listas. No hay id de lista ni label: una organización vigila solicitudes, sin agrupar.
  • Los ítems por denominación. Sólo se vigila por número de solicitud.
  • Los filtros por cliente (minScore, niceClass, allClasses, liveOnly) y baseline: el umbral es 0,7 para todos (entre 0,7 y 0,8, con la condición de palabra; para una vigilada de 1–2 caracteres, sólo parecidas cortas), las clases son las de la propia solicitud, sólo cuentan las vivas y la búsqueda inicial se hace siempre.
  • El webhook por lista, su signingSecret, la cabecera X-Tarno-Signature de vigilancia y el registro de entregas.
  • Idempotency-Key y version en estas escrituras: repetir un alta ya es inocuo por sí mismo.
  • El snapshot congelado del hit (snapshot, hitKind, triggerHash, watchItemId, watchlistId): la marca parecida se lee del corpus al consultar (matched).
  • Los códigos de error watchlist_too_large, watchlist_retired, idempotency_conflict y concurrent_modification.

Las watchlists que existieran no se migran: no había ninguna en uso.

Ver también