Ir para o conteúdo

Vigilância de semelhantes

Vigilância responde a uma pergunta: quais marcas se parecem com a minha? Você escolhe uma solicitação que já existe no INAPI, pelo seu número, e o Tarno procura as suas semelhantes entre as solicitações vivas do corpus. Você lê o resultado por cursor.

⚠ [BREAK] 2026-10-04. A vigilância por watchlists (listas por cliente, com itens, filtros, webhook e segredo de assinatura) foi retirada de uma vez, sem período de convivência. Esta página descreve o modelo que a substitui. O que desapareceu e o que o substitui: mais abaixo.

O schema completo e sempre atualizado por campo vive na referência OpenAPI interativa em /docs (Scalar). Este guia explica o contrato de Vigilância e faz o link para essa referência — não reformula o schema. Quando um campo não está documentado aqui, /docs é autoritativo.

Ao longo do guia a URL base é escrita como $TARNO_BASE_URL e a chave como $TARNO_API_KEY, e toda chamada carrega o header X-API-Key — igual ao guia de primeiros passos e ao guia de autenticação.

O que é Vigilância

  • Você vigia uma solicitação, não um nome. Só se vigiam solicitações que já existem no INAPI, pelo seu número (applicationNumber). Um nome livre que ainda não é uma solicitação não é vigiado: para isso existe a busca por semelhança.
  • Não há nada a configurar. A busca usa os dados da própria solicitação (a sua denominação, as suas classes). Não existem filtros, classes nem pontuação mínima por cliente: o resultado é o mesmo para qualquer um que vigie essa solicitação.
  • A tabela de solicitações vigiadas é comum a todos os clientes. Se várias organizações vigiam a mesma solicitação, a busca é feita uma única vez. A única coisa própria de cada organização é o que ela vigia. Isso tem uma consequência que vale a pena ler: não é secreta.
  • Só contam as solicitações vivas. Uma solicitação em estado terminal (rechazada, denegada, desistida, abandonada, anulada, caducado, vencida, segundo o estado que o Tarno deriva dos atos) não entra como semelhante, e também não pode ser cadastrada para vigilância.
  • As marcas de Madri (registro internacional) são vigiadas e contam como semelhantes, igual às nacionais.
  • Uma série nova do registro que você vigia é avisada à parte. Se você vigia uma solicitação de um registro de Madri — o número base ou uma das suas séries —, cada uma das demais séries adicionais desse registro chega à mesma lista com relation: "series", compartilhe ou não classe com a sua. Como é.
  • O que é seu não é ameaça. Na leitura, ocultam-se as semelhantes que a sua organização também vigia.
  • Não há webhook. As semelhantes são lidas por cursor com GET /watch/hits.

São quatro operações, iguais por REST e por MCP:

Operação REST MCP Escopo
Vigiar uma solicitação POST /watch/applications watch_application watch:write
Deixar de vigiá-la DELETE /watch/applications/{applicationNumber} unwatch_application watch:write
Listar o que você vigia GET /watch/applications list_watched_applications watch:read
Ler as semelhantes GET /watch/hits list_similarity_hits watch:read

Escopos e tenancy

Vigilância usa dois escopos, além das mesmas regras de escopos do restante do contrato (veja o guia de autenticação):

Escopo Concede acesso a
watch:read Leituras: GET /watch/applications, GET /watch/hits.
watch:write Escritas: POST /watch/applications, DELETE /watch/applications/{applicationNumber}.

Uma chave sem escopos recebe os escopos de leitura base, watch:read incluído, mas não watch:write: esse é sempre concedido explicitamente. Uma chave com um array de escopos não vazio recebe somente os listados; chamar uma rota cujo escopo exigido está ausente é rejeitado com 403 forbidden nomeando o escopo faltante. O escopo é verificado antes de validar a entrada: sem ele, uma requisição malformada responde 403, não 400.

A organização é resolvida a partir da chave de API (o consumerId da chave), nunca a partir do corpo da requisição. Consequências:

  • Uma chave sem organização (consumerId nulo) não pode usar Vigilância → 403 forbidden (detail: API key has no owning org), mesmo que tenha os escopos.
  • Cada chave vê somente o que a sua organização vigia e as semelhantes disso. Deixar de vigiar algo que a sua organização não vigia —outra o vigie ou não— responde um 404 uniforme.

Em resumo: para usar Vigilância uma chave precisa ao mesmo tempo de uma organização e dos escopos watch:*.

Vigiar uma solicitação

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

Corpo:

Campo Tipo Notas
applicationNumber string Número de solicitação do INAPI: de 1 a 12 dígitos, ou uma série adicional de um registro de Madri (nove dígitos, hífen e o sufixo do INAPI: 991652209-2). Uma série é vigiada separadamente, com suas próprias classes.

O corpo é estrito: qualquer outra chave é um 400 validation_error.

Resposta — uma WatchedApplication:

Campo Tipo Notas
applicationNumber string A solicitação vigiada.
watchedSince string (data-hora ISO) Desde quando a sua organização a vigia.
baselineStatus 'pending' | 'done' Estado da busca inicial dessa solicitação.
baselineAt string (ISO) | null Quando a busca inicial terminou; null enquanto está pending.
terminalSince string (ISO) | null Desde quando o serviço vê a solicitação num estado terminal; null enquanto está viva. Ver quando uma vigilância termina.
watchEndsOn AAAA-MM-DD | null Último dia da vigilância de uma solicitação terminal (dia do Chile); no dia seguinte ela termina sozinha. Não é um prazo legal.
watchEndBasis string | null De onde sai esse dia: appeal_close, grace_end, rejection_margin ou expiry_margin.
  • 201 — a solicitação passa a ser vigiada pela sua organização.
  • 200 — a sua organização já a vigiava: devolve a mesma vigilância e não consome o limite diário. Exceção: se a solicitação já estiver em estado terminal (mesmo que a sua vigilância continue até watchEndsOn), repetir o cadastro responde 422 application_terminal.

Por MCP, watch_application devolve esse mesmo corpo e não distingue um cadastro novo de um repetido: a diferença 201 / 200 só existe em REST.

A chamada responde na hora: a busca de semelhantes não é feita dentro da requisição (veja a busca 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 = cadastro novo · 200 = você já a vigiava

O que é rejeitado

HTTP code Quando
400 validation_error Um número que não tem de 1 a 12 dígitos nem é uma série de Madri (991652209-2), ou uma chave a mais no corpo.
404 not_found A solicitação não existe no corpus. detail: trademark N not found.
422 application_terminal A solicitação existe mas o seu estado é terminal. O estado vai em applicationStatus (e em detail). Não é vigiada.
422 watch_limit_reached A sua organização já tem o máximo de solicitações vigiadas ativas do seu plano. O máximo vai em limit.
429 watch_daily_limit_reached A sua organização esgotou os cadastros de hoje. Traz limit (o limite) e resetsAt (quando reabre).
503 service_unavailable Não responde o armazém de vigilâncias ou a base onde se lê o limite do plano. Reexecutável.

applicationStatus, limit e resetsAt são membros do primeiro nível do corpo de erro, ao lado de code e detail — não vão dentro de outro objeto. O 429 deste limite não traz o cabeçalho Retry-After: o instante de reabertura é 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"
}

Deixar de vigiar

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

Devolve 204 No Content. Se a sua organização não vigiava essa solicitação, 404 not_found (detail: application N is not watched), outra organização a vigie ou não.

Por MCP não existe resposta vazia, então unwatch_application devolve { "applicationNumber": "1234567", "watched": false }.

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

Ao deixar de vigiar uma solicitação, as suas semelhantes deixam de aparecer nas suas leituras e libera-se uma vaga do seu plano. O cadastro que você fez continua contando para o limite diário desse dia.

Listar o que você vigia

GET /watch/applications ≡ list_watched_applications — escopo watch:read. Lista as solicitações que a sua organização vigia agora (as que você deixou de vigiar não aparecem).

Query Tipo Notas
cursor string Cursor opaco de keyset. Trate como caixa-preta.
limit integer Tamanho da página. Padrão 50, máximo 200.

Resposta: o envelope comum — { results: WatchedApplication[], limit, next, hasMore, meta }, da inscrição mais antiga à mais recente. next: null (e hasMore: false) = fim, mesma semântica de keyset de primeiros passos. Um cursor ilegível não é um erro: serve-se a primeira página.

Esta lista não lê o corpus, então meta.dataAsOf é sempre null.

Cada item traz também terminalSince, watchEndsOn e watchEndBasis: os três são null enquanto a solicitação está viva, e anunciam o fim da vigilância quando o seu estado passa a terminal (como uma vigilância muda com o tempo). Uma vigilância que já terminou não aparece nesta lista.

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

A busca inicial

Na primeira vez que alguém vigia uma solicitação, o Tarno a cruza contra todo o corpus. Essa busca leva segundos e corre em segundo plano, uma de cada vez:

  1. O cadastro responde na hora, com baselineStatus: "pending".
  2. Quando a busca termina, a solicitação passa a baselineStatus: "done" e baselineAt traz a data. Você vê isso em GET /watch/applications.
  3. A partir daí as suas semelhantes estão em GET /watch/hits. Enquanto está pending, a lista de semelhantes dessa solicitação pode estar vazia: vazia e pending não significa «sem semelhantes».

Se outra organização já vigiava a solicitação e a sua busca inicial estava feita, o seu cadastro responde com baselineStatus: "done" e as semelhantes ficam disponíveis de imediato: a busca não se repete.

Uma busca inicial que falha é repetida sozinha, com esperas cada vez mais longas (60 s, 120 s, 240 s… até um máximo de 6 h entre tentativas). Não há um estado «falhou»: a solicitação continua pending até a busca terminar. Uma busca em que algum canal do motor (léxico, fonético ou, se configurado, o semântico) se degradou conta como falha: não é dada por terminada com semelhantes incompletas.

Quem vai primeiro. As buscas iniciais são feitas em série, uma de cada vez, e as organizações se revezam: a seguinte é a da organização que há mais tempo não é atendida, e dentro de uma organização, o seu cadastro mais antigo. Assim, quem cadastra 500 solicitações de uma vez não deixa esperando atrás de todas elas quem cadastrou uma. A vez é contada sobre todas as inscrições da organização, ativas ou removidas: deixar de vigiar o que já foi buscado não adianta na fila. Uma busca que falha também gasta a vez. E uma solicitação vigiada por várias organizações é uma só busca que serve a todas. O que isto não promete: um prazo. Com muitos cadastros pendentes, o seu espera a sua vez.

A busca percorre no máximo 2.000 resultados do motor por solicitação (20 páginas de 100). O motor agrupa num só resultado as solicitações irmãs (mesma denominação e mesmo titular), e cada irmã é guardada como uma semelhante própria, então as semelhantes guardadas podem ser mais de 2.000.

Ler as semelhantes

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

Query Tipo Notas
cursor string Cursor opaco de keyset. Trate como caixa-preta.
limit integer Tamanho da página. Padrão 50, máximo 200.
applicationNumber string Opcional. Só as semelhantes dessa solicitação vigiada. Se a sua organização não a vigia, a resposta é 200 com uma página vazia — não um 404.

Resposta: o envelope comum — { results: SimilarityHit[], limit, next, hasMore, meta }, na ordem em que a sua organização pôde ler cada semelhante: visibleSince ascendente e, em caso de empate, id.

Esta lista é um feed, e a sua paginação tem uma regra própria: next vem sempre — também na última página e com a lista vazia — e o fim da leitura é hasMore: false, não next: null. Para a próxima página, reenvie next sem alterações como cursor; ao terminar, guarde o último next: é o cursor para pedir mais tarde só o que é novo (como). Um cursor ilegível não é um erro: a lista é lida desde o início. meta.dataAsOf é a data do dado do corpus com que matched foi lido, como no restante do contrato. Uma página vazia não lê o corpus e traz meta.dataAsOf: null.

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

O que entra na lista:

  • Todas as semelhantes das solicitações que a sua organização vigia, também as que foram encontradas antes de você se inscrever. Vigiar responde a «o que se parece com a minha marca»; quando cada uma apareceu não muda o fato de ser semelhante.
  • Só semelhantes com score ≥ 0,7. O limiar é o mesmo para todos os clientes e não se configura por requisição. A única exceção é o aviso de série, que não é uma semelhante: entra sem pontuação.
  • Entre 0,7 e 0,8, só se a semelhante tiver uma palavra da denominação vigiada, igual ou a uma letra de distância («NOMADES» → «NOMADE», «CMP» → «CMPC»). Contam as palavras próprias da vigiada que são pouco frequentes nas suas classes (menos de 50 marcas), sem os seus termos genéricos; se não tiver nenhuma pouco frequente, vale qualquer uma das suas; se só tiver termos genéricos, não entra nada dessa faixa. Os números colados a letras são separados antes de comparar («NOMADE98» → «nomade 98»). Assim não entram as que só compartilham uma palavra comum do ramo («SL Abogados» → «Abogados Cordillera»). A partir de 0,8 nada muda. A busca de semelhantes (similarTo, similarToTrademark), a janela de oposição e a disponibilidade não aplicam esta regra.
  • Se a denominação vigiada tiver 1 ou 2 letras ou números («Q», «TE», «+B», «B5»; sinais e espaços não contam, depois de tirar maiúsculas e acentos), só entram semelhantes de 1 a 3 letras ou números, com qualquer score: as idênticas e as curtas que soam igual («Q» → «K», «W» → «V»). Uma letra soa como qualquer inicial solta de um nome longo, e sem esta regra uma sigla recebia centenas de semelhantes com score 1 («TE» → «THE JUNGLE BOOK», «G» → «G T D INTERNET»). As vigiadas de 3 caracteres ou mais não mudam. A busca de semelhantes, a janela de oposição e a disponibilidade também não aplicam esta regra.
  • Nunca a própria solicitação vigiada.
  • Não as semelhantes que a sua organização também vigia (o que é seu não é ameaça). Se você deixar de vigiar uma delas, ela volta a aparecer como semelhante das demais.

Como saber de semelhantes novas

Não há aviso por webhook: você lê, e a lista entrega o cursor para fazer isso sem relê-la inteira.

  1. Primeira leitura, sem cursor. Pagine reenviando next enquanto hasMore for true.
  2. Quando hasMore for false, guarde esse next: é a sua posição.
  3. Na próxima vez, envie essa posição como cursor. Você recebe só o que a sua organização pôde ler depois. Se não houver nada, a página vem vazia e next é o mesmo cursor que você enviou.

⚠ Não itere «até next ser nulo»: nesta lista ele nunca é. Um cliente que faça isso fica pedindo a mesma página vazia para sempre. O fim é hasMore: false.

O que é «novo». A ordem não é a da detecção, mas o instante em que cada semelhante passou a ser legível para a sua organização (visibleSince): o mais tardio entre quando foi detectada, quando começou a sua inscrição vigente na solicitação vigiada e a última vez que você deixou de vigiar a solicitação semelhante. Por isso o seu cursor recolhe também o que não é novo para o serviço, mas é para você:

  • as semelhantes antigas de uma solicitação em que você se inscreve hoje e que outra organização vigiava há meses;
  • as que estavam ocultas por serem suas e reaparecem quando você deixa de vigiar essa marca (ou quando a vigilância dela termina sozinha): chegam com o mesmo id e um visibleSince novo;
  • as que foram fechadas e voltam: chegam com um id novo.

Se você deixar de vigiar uma solicitação e se inscrever de novo, é uma inscrição nova: todas as suas semelhantes são entregues outra vez.

O mesmo id pode chegar mais de uma vez. Trate id como chave: insira ou atualize.

Um cursor é do seu filtro. O cursor obtido com applicationNumber=N serve para continuar lendo com applicationNumber=N, e o obtido sem filtro, para continuar sem filtro. Usado com outro filtro, a lista é lida desde o início: repete, nunca pula.

Os cursores emitidos antes de 2026-10-07 já não são reconhecidos: a primeira leitura com um deles começa do início (uma releitura completa, uma única vez).

O que o cursor garante, e o que não. A lista só serve semelhantes já assentadas: enquanto o serviço tem alguma operação em curso sobre a vigilância, o que for escrito desde que essa operação começou espera a sua leitura seguinte. Assim, uma semelhante que termina de ser gravada tarde nunca fica atrás do cursor que você já levou: pode atrasar — o normal são milissegundos; alguns segundos durante uma tarefa de manutenção —, não se perder. Pelo mesmo motivo, logo depois de uma inscrição a lista dessa solicitação pode vir vazia por um instante: leia de novo com o next recebido. O que isso não cobre:

  • uma operação do serviço que dure mais de 60 segundos deixa de reter a lista (para que uma operação travada não a congele); o que essa operação escrever depois poderia ficar atrás de um cursor já entregue. Nenhuma operação normal chega perto dessa duração;
  • uma correção manual de dados feita pelo operador do serviço;
  • uma mudança do limiar de score do serviço: as semelhantes que passarem a superá-lo não são reordenadas.

Se você precisar descartar qualquer um desses casos, uma leitura sem cursor percorre sempre a lista completa.

Um fechamento não é anunciado. Quando uma semelhante deixa de sê-lo (o seu estado passa a terminal, ou ela deixa de se parecer) simplesmente deixa de sair na lista: não há um evento nem uma linha «fechada» para ler, e o cursor não a traz. Você descobre com uma leitura completa (sem cursor): o que tinha guardado e já não vem, fechou. Se mais adiante ela voltar, volta com um id novo e no fim da sua ordem, e o seu cursor a recolhe.

Forma de uma semelhante

Cada elemento de GET /watch/hits é uma SimilarityHit:

Campo Tipo Notas
id number Identificador da semelhante enquanto ela segue aberta. Não é a ordem da lista. Uma semelhante que fecha e volta tem um id novo.
watchedApplicationNumber string A solicitação que você vigia.
matchedApplicationNumber string A solicitação que se parece com ela.
relation 'series' (opcional) Só presente quando a solicitação de matched é uma série adicional do mesmo registro de Madri que a solicitação vigiada, seja esta o número base ou outra série (aviso de série). Em uma semelhante comum a chave não vai (não chega como null).
score number | null Pontuação de semelhança (0..1), nunca abaixo do limiar. null só em um elemento com relation que o motor de semelhança não encontrou: não se inventa uma pontuação. Sem relation é sempre um número.
signals objeto O que o motor viu: matchedBy (os canais pelos quais coincide), signals (a força por canal, de 0 a 1 ou null) e, só numa irmã agrupada, representative. Veja abaixo.
origin 'baseline' | 'sync' | 'series_load' Quem o escreveu: a busca inicial, o motor diário (o cruzamento após um sync, uma semelhante que volta ou a revisão diária), ou a passada que segue uma carga de séries de Madri. Um aviso de série pode trazer qualquer um dos três.
detectedAt string (data-hora ISO) Quando foi detectada. Pode ser anterior ao seu cadastro (por quê).
visibleSince string (data-hora ISO, UTC, com microssegundos) Desde quando a sua organização pode lê-la: o mais tardio entre a detecção, o início da sua inscrição vigente na solicitação vigiada e a última vez que você deixou de vigiar a solicitação semelhante. É a ordem da lista (como ler o que é novo). Nunca anterior a detectedAt.
matched BrandSummary | null A marca semelhante, lida do corpus no momento da consulta; null se a solicitação já não existe.

matched é a mesma forma BrandSummary documentada em primeiros passos e em /docs. Não é uma foto congelada: traz o estado que a marca tem hoje.

{
  "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 tem esta forma: { matchedBy: [...], signals: { canal: 0–1 }, representative?: "N" }.

  • matchedBy — os canais do motor que encontraram a semelhante (exact, fuzzy, phonetic, semantic).
  • signals — a força por canal (lexical, semantic, phonetic), de 0 a 1; null num canal que não contribuiu.
  • representative — só quando a semelhante é uma solicitação irmã que o motor agrupou sob outra (mesma denominação e titular): é o número dessa outra, e o score e os sinais são os dela. Se a semelhante é a representante, a chave não vai.

O schema publica signals como um objeto aberto: o motor pode acrescentar chaves.

Aviso direto: uma série nova do registro que você vigia

Um registro internacional (Protocolo de Madri) pode ter mais de uma série no Chile, e cada série adicional é uma solicitação à parte com o número da primeira mais um sufixo (991652209-2; ver Séries de um registro de Madri). Uma série adicional costuma ser pedida para outras classes, e a vigilância busca semelhantes dentro das classes da solicitação vigiada: pela semelhança, quem vigia 991652209 não saberia que existe 991652209-2.

Por isso, se você vigia uma solicitação desse registro — o número base (991652209) ou qualquer uma das suas séries (991652209-2) —, cada uma das demais séries adicionais chega a GET /watch/hits como mais um elemento, compartilhe ou não classe com a sua. O exemplo é o de quem vigia o número base; quem vigia 991652209-2 recebe o mesmo elemento com o seu número em watchedApplicationNumber quando 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 */ }
}

Como distingui-lo de uma semelhante:

  • relation: "series" diz que a solicitação de matched é uma série adicional do mesmo registro que a vigiada: matchedApplicationNumber é o número base da vigiada (os seus nove dígitos) + - + sufixo, e é diferente de watchedApplicationNumber. Em uma semelhante comum a chave não existe. Não é preciso comparar os números: basta ler relation.
  • score é null e signals é {} quando o motor de semelhança não encontrou a série (o normal se não compartilha classe): ninguém as comparou, então não há pontuação, e não se inventa uma.
  • Se a série compartilha classe e o motor também a encontra, é o mesmo elemento (um só id), com relation: "series" e além disso o seu score e os seus signals reais. Nunca há dois elementos para a mesma série, chegue primeiro o aviso ou a busca.
  • origin diz quem escreveu primeiro o elemento, não se ele é um aviso de série nem se tem pontuação: baseline se foi a busca inicial da sua solicitação vigiada, series_load se foi a passada que segue uma carga de séries, sync se foi o motor diário (o cruzamento ou a revisão diária). Um aviso pode trazer score (o motor também encontrou a série), e um que foi fechado e voltou chega com origin: "sync" e pode continuar com score: null. Não deduza nada de origin: use relation para saber se é um aviso de série e score para saber se houve comparação.

O que continua igual a qualquer outro elemento da lista:

  • O cursor. O aviso entra no fim da sua ordem (visibleSince), então a leitura por next o traz sem fazer nada diferente (como ler o que é novo).
  • O que é seu não é ameaça. Se a sua organização também vigia essa série, o aviso é ocultado.
  • Só solicitações vivas. Não se avisa de uma série em estado terminal, e o aviso deixa de ser listado se a série passa a terminal ou deixa de existir no corpus (volta, com id novo, se reviver).

O que é diferente:

  • Não é fechado por «já não se parece». Ser uma série do seu registro não depende da semelhança: se uma busca posterior deixa de encontrá-la, o elemento continua na lista e só perde o score (volta a null).

Quem recebe e quem não:

  • Quem vigia o número base (991652209) e quem vigia outra série do registro (991652209-2): os dois recebem o aviso quando aparece 991652209-3.
  • Um elemento por solicitação vigiada. Se a sua organização vigia ao mesmo tempo 991652209 e 991652209-2, quando aparece 991652209-3 você recebe dois elementos: um com watchedApplicationNumber: "991652209" e outro com "991652209-2". É o mesmo que acontece com uma semelhante que se parece com duas das suas solicitações vigiadas. Com o filtro applicationNumber você vê só os de uma.
  • Nunca da série que você já vigia. Quem vigia 991652209-2 não recebe aviso de 991652209-2; e se você vigia ao mesmo tempo o número base e essa série, também não sob o número base (o que é seu não é ameaça).
  • O número base não é avisado. Só as séries adicionais são notícia: quem vigia 991652209-2 não recebe aviso de que existe 991652209. Se o motor o encontra como semelhante (compartilham classe), chega como semelhante comum, com score e sem relation.

Quando chega, sem que você precise fazer nada:

  • Ao começar a vigiar uma solicitação do registro — o número base ou uma série —: normalmente, quando a busca inicial termina você já tem as demais séries vivas do registro, compartilhem ou não classe com a sua (origin: "baseline"). Não é uma garantia ligada a baselineStatus: "done": em todo caso elas chegam, no mais tardar, com a revisão diária seguinte. Em particular, se você volta a vigiar uma solicitação que tinha deixado de vigiar há pouco, a busca não se repete (fica done na hora) e as séries que apareceram nesse meio-tempo chegam com a revisão diária.
  • Quando o serviço carrega séries novas: com a passada que segue a carga (origin: "series_load") ou, se não, com a revisão diária.
  • Na revisão diária: qualquer série viva do seu registro que ainda não esteja na sua lista — por exemplo, uma que estava em estado terminal quando você começou a vigiar e depois revive — (origin: "sync"). Pode levar até um dia; se num mesmo dia houvesse um número muito grande de avisos por escrever, o restante sai nos dias seguintes.

GET /watch/hits avisa das séries vivas. A lista completa das séries de um registro, também as que estão em estado terminal, é relatedSeries da ficha.

Limites

Limite O que limita Ao exceder
Do plano Quantas solicitações a sua organização pode vigiar ao mesmo tempo (ativas). 422 watch_limit_reached
Diário Quantos cadastros a sua organização pode fazer num dia (500 se o plano não disser outra coisa). 429 watch_daily_limit_reached
  • O limite do plano conta o que está ativo. Deixar de vigiar uma solicitação libera a sua vaga. O número é o da sua organização (500 se não houver outro contratado): todas as suas chaves de API compartilham o mesmo limite e a mesma contagem.
  • O limite diário conta cadastros, não o que está ativo. Vigiar e deixar de vigiar a mesma solicitação no mesmo dia gasta um cadastro; cadastrá-la de novo gasta outro. Existe para que tirar e pôr sem parar não esgote recursos. Quem o fixa é o plano da sua organização, como o limite do plano.
  • O dia é o do Chile (America/Santiago): o contador reinicia à meia-noite do Chile, não à de UTC. resetsAt, no corpo do 429, é esse instante (em UTC), e limit o limite. Não há cabeçalho Retry-After.
  • Repetir um cadastro que já existe responde 200 e não gasta do limite diário (salvo se a solicitação já for terminal: 422 application_terminal).

O limite diário e o limiar de semelhança são ajustes do serviço (WATCH_DAILY_ADDS_MAX, WATCH_MIN_SCORE), iguais para todos; não podem ser alterados por requisição.

A vigilância é global, e não é secreta entre clientes

A tabela de solicitações vigiadas é comum. Isso poupa trabalho —uma solicitação é cruzada uma vez mesmo que dez organizações a vigiem— e tem um efeito que o contrato aceita conscientemente:

Um cliente pode deduzir que outra organização já vigiava uma solicitação. Se você cadastra uma solicitação e a resposta chega com baselineStatus: "done", ou as suas semelhantes trazem um detectedAt anterior ao seu cadastro, é porque alguém a vigiava antes de você.

O que não se pode saber: quem a vigia, quantas organizações, nem o que mais alguém vigia. As inscrições de outra organização nunca são legíveis.

Como uma vigilância muda com o tempo

A busca inicial é uma foto do dia da inclusão. A partir daí a vigilância se move sozinha:

O cruzamento diário. Cada vez que termina um sync completo do corpus, cada solicitação vigiada é comparada com as solicitações que mudaram desde a última vez (novas, mudanças de denominação, mudanças de classe) e continuam vivas. As semelhantes novas aparecem em GET /watch/hits com origin: "sync". Um dia sem sync completo não tem cruzamento: essas novidades entram com o seguinte.

Quando uma semelhante deixa de ser listada.

  • O seu estado passa a terminal (rejeitada, vencida…). O serviço verifica uma vez por dia, então pode levar até um dia para desaparecer. Uma rejeitada com um recurso apresentado não conta como viva: só o estado decide.
  • Ela já não existe no corpus, e continua sem existir na verificação do dia seguinte: uma única ausência não fecha nada, então leva entre um e dois dias (enquanto isso sai com matched: null). Se reaparecer e estiver viva, volta.
  • Já não se parece: a sua ou a outra mudou de denominação ou de classes e já não chega ao limiar. (Não se aplica a um aviso de série: esse continua listado e só perde o score.)

Quando volta. Se voltar a estar viva, ou voltar a se parecer, reaparece — com um id novo e um detectedAt novo.

A busca pode ser repetida. Se a sua solicitação vigiada mudar de denominação ou de classes, ou se o corpus for reprocessado em bloco, o serviço repete a busca inicial dessa solicitação: baselineStatus volta a pending por um tempo e depois a done. As semelhantes que você já tinha continuam legíveis enquanto isso.

Quando uma vigilância termina. Se o estado da solicitação que você vigia passa a terminal, ela não é cortada nesse dia: ainda pode acontecer algo com ela. Continua sendo vigiada até um último dia, que a lista anuncia:

watchEndBasis De onde sai watchEndsOn
appeal_close A data limite para recorrer da rejeição, quando o serviço a publica como marco da marca.
grace_end O fim do período de graça da renovação, quando o serviço o publica.
rejection_margin 45 dias corridos após a rejeição (ou uma desistência, abandono ou anulação) sem esse marco.
expiry_margin 6 meses após o vencimento sem esse marco.

watchEndsOn é o último dia da vigilância, não um prazo legal: os prazos, com o seu artigo, são lidos nos marcos da marca (GET /trademarks/{n} → milestones). Se a solicitação reviver antes desse dia, os três campos voltam a null e a vigilância continua. watchEndsOn nunca é anterior ao dia em que o serviço viu a solicitação em estado terminal: se o marco ou a margem já tinham passado, esse dia é o último, de modo que sempre há pelo menos um dia em que você pode lê-lo.

No dia seguinte a watchEndsOn a vigilância termina sozinha: sai de GET /watch/applications, as suas semelhantes deixam de sair em GET /watch/hits, e ela deixa de contar para o limite do seu plano. A partir daí DELETE responde 404 e uma nova inclusão responde 422 application_terminal com o seu estado. O mesmo ocorre, sem último dia anunciado, se a solicitação deixar de existir no corpus e continuar sem existir na verificação do dia seguinte: uma ausência de um único dia não termina nenhuma vigilância.

O que ninguém vigia é conservado por 10 dias. Quando a última organização deixa de vigiar uma solicitação, o serviço a conserva por 10 dias com as suas semelhantes (e continua a cruzá-la), de modo que uma nova inclusão nesse prazo encontra a busca já feita. Depois é apagada; uma inclusão posterior começa com uma busca inicial nova.

Se a sua organização for desativada e voltar. Enquanto uma organização está desativada, o serviço não vigia para ela: as suas solicitações deixam de contar para o seu limite e, se ninguém mais as vigia, deixam de ser buscadas e cruzadas. A sua lista é conservada. Se a organização for reativada, a lista volta sozinha em até um minuto, com o watchedSince que tinha e sem gastar o limite diário; as solicitações que só ela vigiava passam um tempo por baselineStatus: "pending" enquanto são buscadas de novo. Em GET /watch/hits, tudo o que ela volta a poder ler sai depois do cursor que guardou, com os mesmos id: receberá de novo semelhantes que já tinha lido, além das novas. Não volta uma vigilância que terminou por conta própria nesse meio-tempo. Uma organização que nunca foi desativada não nota nada disso.

O que esta versão ainda não faz

  • Não há semelhança por imagem (logotipo). A vigilância compara só por texto.
  • Não há aviso por webhook nem lista de vigilâncias terminadas: lê-se, e o fim é anunciado em watchEndsOn.

MCP

REST é equivalente ao MCP: mesma chave, mesmos escopos, mesmos schemas, mesmos códigos de erro. O servidor MCP expõe estas ferramentas de Vigilância:

Ferramenta 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

Duas diferenças de forma, porque uma ferramenta MCP não tem códigos HTTP nem respostas vazias:

  • watch_application devolve a mesma WatchedApplication que REST e não distingue um cadastro novo de um repetido (REST: 201 / 200).
  • unwatch_application devolve { "applicationNumber": "N", "watched": false } (REST: 204 sem corpo).

Uma recusa chega como resultado de erro com o mesmo corpo RFC 9457 de REST —mesmo code, mesmo status, mesmos applicationStatus / limit / resetsAt—, com requestId vazio.

O roteiro weekly_watch («que semelhantes têm as solicitações que vigio?») tem um argumento, applicationNumber, opcional. Com ele, lê list_similarity_hits dessa solicitação; sem ele, lê list_watched_applications (para saber o que é vigiado e se a sua busca inicial terminou) e list_similarity_hits de todas.

Veja o guia MCP para o endpoint, o transporte e a autenticação.

Erros

Todos os erros trazem um corpo RFC 9457 (application/problem+json: type, title, status, detail, code, requestId e, numa falha de validação, errors[]) — descrito em primeiros passos. Ramifique por code.

HTTP code Quando
400 validation_error Entrada inválida: número de solicitação malformado, uma chave ou parâmetro a mais.
401 unauthorized Chave ausente, malformada, desconhecida ou revogada.
403 forbidden Falta o escopo watch:* exigido (verificado antes de validar a entrada), ou a chave não tem organização.
404 not_found Cadastro: a solicitação não existe no corpus (trademark N not found). Remoção: a sua organização não a vigia (application N is not watched).
422 application_terminal A solicitação está em estado terminal e não pode ser vigiada. Traz applicationStatus.
422 watch_limit_reached Limite do plano: solicitações vigiadas ativas demais. Traz limit.
429 watch_daily_limit_reached Limite diário de cadastros esgotado. Traz limit e resetsAt; sem cabeçalho Retry-After.
503 service_unavailable O armazém de vigilâncias não está disponível, ou (só no cadastro) não responde a base onde se lê o limite do plano; reexecutável.

applicationStatus, limit e resetsAt são membros do primeiro nível do corpo. Ler as semelhantes de uma solicitação que a sua organização não vigia não é um erro: 200 com uma página vazia. O status e o corpo de cada code são os mesmos por REST e por MCP.

O que foi retirado em 2026-10-04

As dez operações de watchlists deixaram de existir, nos dois transportes e sem período de convivência: as rotas REST já não existem e as ferramentas já não estão em tools/list.

Retirada (MCP) Retirada (REST) O que usar agora
create_watchlist POST /watchlists watch_application, uma chamada por solicitação
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, uma por solicitação
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 — (não há nada a configurar)
list_watchlist_deliveries GET /watchlists/:id/deliveries — (não há webhook)

Com elas desaparecem:

  • As listas. Não há id de lista nem label: uma organização vigia solicitações, sem agrupar.
  • Os itens por denominação. Só se vigia por número de solicitação.
  • Os filtros por cliente (minScore, niceClass, allClasses, liveOnly) e baseline: o limiar é 0,7 para todos (entre 0,7 e 0,8, com a condição de palavra; para uma vigiada de 1–2 caracteres, só semelhantes curtas), as classes são as da própria solicitação, só contam as vivas e a busca inicial é sempre feita.
  • O webhook por lista, o seu signingSecret, o header X-Tarno-Signature de vigilância e o registro de entregas.
  • Idempotency-Key e version nessas escritas: repetir um cadastro já é inofensivo por si só.
  • O snapshot congelado do hit (snapshot, hitKind, triggerHash, watchItemId, watchlistId): a marca semelhante é lida do corpus ao consultar (matched).
  • Os códigos de erro watchlist_too_large, watchlist_retired, idempotency_conflict e concurrent_modification.

As watchlists que existissem não são migradas: nenhuma estava em uso.

Veja também