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 (
consumerIdnulo) 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
404uniforme.
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 responde422 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:
- O cadastro responde na hora, com
baselineStatus: "pending". - Quando a busca termina, a solicitação passa a
baselineStatus: "done"ebaselineAttraz a data. Você vê isso emGET /watch/applications. - 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 ependingnã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 comscore1 («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.
- Primeira leitura, sem
cursor. Pagine reenviandonextenquantohasMorefortrue. - Quando
hasMoreforfalse, guarde essenext: é a sua posição. - 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 enexté 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
ide umvisibleSincenovo; - as que foram fechadas e voltam: chegam com um
idnovo.
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
scoredo 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;nullnum 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 oscoree 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 dematchedé 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 dewatchedApplicationNumber. Em uma semelhante comum a chave não existe. Não é preciso comparar os números: basta lerrelation.scoreénullesignalsé{}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), comrelation: "series"e além disso o seuscoree os seussignalsreais. Nunca há dois elementos para a mesma série, chegue primeiro o aviso ou a busca. origindiz quem escreveu primeiro o elemento, não se ele é um aviso de série nem se tem pontuação:baselinese foi a busca inicial da sua solicitação vigiada,series_loadse foi a passada que segue uma carga de séries,syncse foi o motor diário (o cruzamento ou a revisão diária). Um aviso pode trazerscore(o motor também encontrou a série), e um que foi fechado e voltou chega comorigin: "sync"e pode continuar comscore: null. Não deduza nada deorigin: userelationpara saber se é um aviso de série escorepara 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 pornexto 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
idnovo, 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 anull).
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 aparece991652209-3. - Um elemento por solicitação vigiada. Se a sua organização vigia ao mesmo tempo
991652209e991652209-2, quando aparece991652209-3você recebe dois elementos: um comwatchedApplicationNumber: "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 filtroapplicationNumbervocê vê só os de uma. - Nunca da série que você já vigia. Quem vigia
991652209-2não recebe aviso de991652209-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-2não recebe aviso de que existe991652209. Se o motor o encontra como semelhante (compartilham classe), chega como semelhante comum, comscoree semrelation.
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 abaselineStatus: "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 (ficadonena 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 do429, é esse instante (em UTC), elimito limite. Não há cabeçalhoRetry-After. - Repetir um cadastro que já existe responde
200e 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 umdetectedAtanterior 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_applicationdevolve a mesmaWatchedApplicationque REST e não distingue um cadastro novo de um repetido (REST:201/200).unwatch_applicationdevolve{ "applicationNumber": "N", "watched": false }(REST:204sem 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á
idde lista nemlabel: 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) ebaseline: 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 headerX-Tarno-Signaturede vigilância e o registro de entregas. Idempotency-Keyeversionnessas 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_conflicteconcurrent_modification.
As watchlists que existissem não são migradas: nenhuma estava em uso.
Veja também
- Autenticação e escopos —
X-API-Key,watch:read/watch:write, ciclo de vida da chave. - Conecte seu agente de IA (MCP) — as mesmas ferramentas de Vigilância via MCP.
- Busca por campos — a busca por semelhança de um nome livre (
similarTo). - Primeiros passos — URL base, paginação por keyset, envelope de erro.
- A referência OpenAPI ao vivo em
/docs— o schema autoritativo por campo.