Busca por campos
Este guia documenta a superfície de busca field-scoped de GET /trademarks (no MCP, a mesma
pergunta faz-se com search_trademarks): a lista de parâmetros, a semântica AND entre campos, a regra q + campos, a
normalização de RUT e a ordenação configurável com sort=.
O schema completo, sempre atualizado e por campo, vive na referência OpenAPI interativa em
https://api.tarno.cl/docs(Scalar). Este guia explica a semântica da busca combinada e aponta para essa referência — não reformula o schema. A referência é autoritativa quando um campo não está documentado aqui.
Ao longo do guia a URL base é https://api.tarno.cl e cada chamada leva o cabeçalho X-API-Key — como
em primeiros passos e autenticação. Usa o escopo brands:read.
O que este guia cobre
GET /trademarks é uma única rota que combina livremente:
- Busca por texto —
qranqueia pelos canais de denominação (exact / fuzzy / fonético / semântico, fundidos por RRF). - Filtragem por campos — predicados exatos, de intervalo e de pessoa (
niceClass,status,applicationNumber,holder,taxId, …) que restringem o resultado.
Todos os parâmetros presentes combinam-se com AND. A resposta é uma página por keyset — o envelope
{ results[], limit, next, hasMore, total, meta } de primeiros passos.
Já tem uma lista de números de depósito? Use
GET /trademarks?applicationNumber=a,b,c(até 100, uma unidade de cota) em vez de N chamadas ao detalhe. As marcas voltam na ordem do pedido, commeta.notFound= os números que não existem. Os demais filtros se aplicam ao lote (uma marca que existe e não casa simplesmente não aparece; não está emnotFound). O lote não pagina nem ordena:limit,cursor,sort,minScore,q,denominationoufacetscomapplicationNumbersão um400.
Parâmetros
Todos opcionais. Um parâmetro multivalorado se repete (?niceClass=9&niceClass=25) e faz OR dentro
do campo; campos distintos fazem AND entre si.
| Param | Tipo | Multivalor | Notas |
|---|---|---|---|
q |
string | não | Texto livre (FTS espanhol + fuzzy + fonético + semântico, RRF). Até 256 caracteres (mais ⇒ validation_error); o mesmo limite vale para similarTo. |
denomination |
string | não | Texto sobre a denominação, mesmo motor que q. Até 512 caracteres (q aceita 256). |
applicationNumber |
string | sim | Número de depósito, match exato. Cada número, até 17 caracteres (12 dígitos, hífen e um sufixo de série de até 4). |
registrationNumber |
string | não | Número de registro, match exato. Até 17 caracteres. |
holder |
string | sim | Substring sobre o titular, insensível a acentos/maiúsculas. Um valor é um nome inteiro, com suas vírgulas («PEPSICO, INC.»); vários, repetindo o parâmetro (veja Nomes de parte). Até 20 valores de 2 a 256 caracteres, com pelo menos uma letra ou dígito (outra coisa ⇒ validation_error); o mesmo limite vale para representative e taxId. |
representative |
string | sim | Substring sobre o representante. Mesmas regras que holder: uma vírgula não separa valores. |
taxId |
string | sim | RUT normalizado (veja RUT); match exato contra titular e representante. Vários, repetindo o parâmetro: uma vírgula não separa valores. |
party |
string | sim | Parte por id interno (o id de GET /parties?q=) e papel: <id>:holder ou <id>:representative. Vários valores somam-se (OR); ver Partes por id. Até 20 valores. |
includeApplicationNumber |
string | sim | Pedidos que se somam à carteira (OR com os filtros de parte); os demais filtros continuam a aplicar-se a eles. Ver Carteira à mão. Até 500. |
excludeApplicationNumber |
string | sim | Pedidos que se retiram sempre (AND NOT), mesmo quando casam. Ver Carteira à mão. Até 500. |
relation |
enum | não | current (padrão) · former · all — restringe holder/representative/taxId/party à titularidade atual, anterior ou ambas. |
niceClass |
integer | sim | Classe de Nice, 1–45. Até 45 valores. |
status |
string | sim | Código de status (catálogo controlado). Casa com o status publicado, que é o derivado (D11): uma marca que o INAPI ainda chama en_tramite mas que já tem número de registro volta com status=registrada, e o literal do INAPI em statusInapi. Até 14 valores (os códigos do catálogo). |
signType |
string | sim | Código de tipo de sinal. Até 14 valores (os códigos do catálogo) de até 20 caracteres (o mais longo, combinacion_de_color). |
goodsAndServices |
string | não | ⭐ Texto de produtos e serviços das classes da marca, por palavras, sem acentos nem maiúsculas (calzado encontra «Calzados»). Não é igualdade; basta que uma classe case. 2–200 caracteres. -palavra exclui, mas é preciso ao menos uma palavra que deva aparecer: só palavras vazias (de la) ou só exclusões (-calzado) é um 400 validation_error. |
filedFrom / filedTo |
YYYY-MM-DD |
não | Intervalo de data de depósito (filedOn). |
milestoneFrom / milestoneTo |
YYYY-MM-DD |
não | ⭐ Marcas com algum marco no intervalo (ver Marcos): sem milestoneKind, qualquer um dos quatro — vencimento, fechamento da oposição, abertura da renovação ou fim da graça. milestoneFrom > milestoneTo é 400 invalid_range. |
milestoneKind |
enum | sim | Restringe o filtro de marcos a esses tipos: expiry, opposition_close, renewal_window_open e/ou grace_end. Outro valor —também appeal_close, publicado mas não filtrável— é 400. Exige milestoneFrom e/ou milestoneTo (sem intervalo é 400 validation_error). |
renewalStatus |
enum | sim | ⭐ Só as marcas cujo renewalStatus (ver Marcos), avaliado na data da resposta, é um de not_due · window_open · grace · lapsed · renewed_expiry_pending. É o mesmo valor que cada marca devolvida traz; as de renewalStatus: null não saem por nenhum. Outro valor é 400. |
liveOnly |
boolean | não | Só marcas vivas: exclui as que estão em um status terminal (rechazada, denegada, desistida, abandonada, anulada, caducado, vencida). Uma marca sem status conhecido é mantida. Ausente = sem filtro. Escreve-se true ou false; qualquer outro valor (yes, 1, vazio) ⇒ 400 validation_error. |
sort |
enum | não | Ordem (veja Ordem). relevance (padrão) · filedOn:desc/:asc · denomination:asc/:desc · status:asc/:desc (pelo status publicado, o derivado). |
limit |
integer | não | Tamanho da página. Padrão 20, máximo 100. |
cursor |
string | não | Cursor keyset opaco. |
Um sort fora do enum, um parâmetro malformado ou um valor acima do seu limite (mais valores ou mais caracteres que os indicados) retorna 400 validation_error — inclusive um booleano que não seja exatamente true ou false. Um taxId malformado
retorna 400 invalid_rut (veja RUT).
Titulares e representantes na lista (holders, representatives)
Cada marca da resposta traz holders (nomes dos titulares) e representatives (nomes dos representantes): string[], [] se não houver, nunca null. representatives inclui apenas a relação vigente
(papel representante ou ambas); não traz o id da parte (para isso, GET /trademarks/{n} com parties).
Pensado para exportar sem buscar o registro linha a linha.
holders também é só a relação vigente (antes misturava titulares anteriores). Os
anteriores são pedidos com includeFormer=true (parâmetro opcional, false por padrão; aceita só true ou
false): cada marca traz então formerHolders e formerRepresentatives (string[], [] se não houver), além
de holders e representatives. Sem o parâmetro essas duas chaves não viajam. Vale igual em GET /trademarks,
POST /trademarks/search e search_trademarks, com ou sem q, similaridade, janela de oposição ou lote. Não muda
quais marcas saem (para filtrar por titulares anteriores existe relation). O registro GET /trademarks/{n} não
precisa dele: já separa parties (vigentes) de formerParties.
Marcos (milestones)
Cada marca da resposta —e o registro GET /trademarks/{n}— traz milestones[]: suas datas com
nome, [] se não tiver nenhuma. Cada marco diz de onde vem (basis): source (um dado que o INAPI
publica) ou derived (um prazo calculado, que leva SEMPRE sua âncora, sua regra e seu artigo).
Ordenados por data. Esta é a lista de tipos (os outros guias apontam para cá):
kind |
basis |
o que é | filtra? |
|---|---|---|---|
expiry |
source |
a data de vencimento que o INAPI publica (field: "expiresOn") |
sim |
opposition_close |
derived ou estimated |
o fechamento da janela de oposição: o 30.º dia útil depois da publicação do extrato. legalBasis cita as três normas: Ley 19.039 art. 5 (term), Ley 19.039 art. 11 (business_days) e Ley 19.880 art. 25 (computation, supletiva). Sua date é o deadline de oppositionWindow. Se o INAPI deixou sem efeito uma publicação e republicou o extrato, a âncora é a última publicação (a que o INAPI publica como data de publicação da marca; o seu «Fin de plazo» cai 30 dias úteis depois dela) |
sim |
renewal_window_open |
derived |
a abertura da janela de renovação: o vencimento − 6 meses, de data a data (31-ago − 6 meses = 28-fev). anchor: {kind: "expiry"}, rule: "6_months_before_expiry", legalBasis Ley 19.039 art. 24 (term), Decreto 82/2022 art. 27 (regulation), Código Civil art. 48 (computation; sua aplicação é a pergunta 4, aberta ao advogado) e Ley 19.880 art. 25 (computation; a mesma quarta norma de grace_end) |
sim Não se publica em renewed_expiry_pending. |
grace_end |
derived ou estimated |
o fim da graça de renovação: o vencimento + 6 meses, de data a data, e, quando esse dia cai em sábado, domingo ou feriado, o primeiro dia útil seguinte (o mesmo calendário de feriados de opposition_close). rule: "6_months_after_expiry_next_business_day"; legalBasis as mesmas quatro normas de renewal_window_open, a última Ley 19.880 art. 25 (computation: quando o último dia do prazo for inábil, entende-se prorrogado para o primeiro dia útil seguinte; o INAPI confirmou por escrito que a renovação apresentada nesse dia útil está no prazo). estimated com estimateReasons: ["outside_holiday_calendar"] quando a data cai depois da cobertura declarada do calendário de feriados (hoje até 2030-12-31): pulam-se os fins de semana e só os feriados conhecidos, então o dia real é esse ou posterior. Sem reserva |
sim |
appeal_close |
derived |
⭐ (44-14) a data limite para apelar de uma RECUSA (024) ou de uma ACEITAÇÃO PARCIAL (444): o 15.º dia útil ESTRITAMENTE posterior à publicação dessa resolução no Estado Diario. anchor: {kind: "rejection_notice"}, rule: "15_business_days_after_notification", legalBasis Ley 19.039 art. 17 bis B (term), Ley 19.039 art. 11 (business_days) e Ley 19.880 art. 25 (computation). Só quando o 024 ou o 444 é o movimento resolutivo mais recente (entre os dois, o mais recente; na mesma data, o 024), em dia útil, dentro do calendário declarado e fora de Madrid; senão não sai (nunca estimated) e get_deadlines diz por quê — ou, com resoluções posteriores a um 024 ou 444 anterior, dá a data com o seu aviso (caveat) e sem marco |
não (400) |
opposition_response_close |
derived ou estimated |
⭐ (2026-10-10) a data limite para contestar o traslado de uma oposição: o 30.º dia útil ESTRITAMENTE posterior à notificação do traslado; improrrogável. anchor: {kind: "transfer_notice", date, annotationId, sectionCode} — o ato de que sai a data: a notificação C1 do Estado Diario ou, na falta dela, a resolução de traslado (458, 647, 1197, 1198)—, rule: "30_business_days_after_notification", legalBasis Ley 19.039 art. 9 (term), Ley 19.039 art. 11 (business_days), Ley 19.880 art. 25 (computation) e Decreto 82/2022 art. 24 (regulation: vencido o prazo, «se haya o no evacuado el traslado», o procedimento segue — não contestar não é abandono). derived com notificação e resolução no mesmo dia; estimated se faltar uma das duas (notification_inferred_from_resolution_date ou transfer_resolution_not_in_corpus). Vale o traslado mais recente. Não sai em designações de Madrid, traslados anteriores a 2022-05-09, âncora em dia não útil nem fora do calendário: get_deadlines e get_filing_context dizem por quê |
não (400) |
grant_fee_close |
estimated |
⭐ (2026-10-10) a data limite para comprovar o pagamento das taxas de concessão: o 60.º dia útil ESTRITAMENTE posterior à notificação da aceitação (029) ou da certidão de trânsito em julgado (911, 912); sem pagamento, o pedido é tido por abandonado. anchor: {kind: "acceptance_notice" \| "finality_certificate", date, annotationId, sectionCode}, rule: "60_business_days_after_notification", legalBasis Ley 19.039 art. 18 bis E (term), Ley 19.039 art. 11 (business_days) e Ley 19.880 art. 25 (computation). Sempre estimated (estimateReasons: ["anchor_by_office_practice"]) e com reservation {code, text {es, en, pt}}: a lei conta os 60 dias desde que a resolução transita em julgado; o INAPI, desde a sua notificação; a data segue o que o INAPI aplica. Mostre-a com essa ressalva. Não sai com uma aceitação parcial ou uma decisão de oposição ainda sem certidão, em Madrid, antes de 2022-05-09, em dia não útil nem fora do calendário: get_deadlines diz por quê |
não (400) |
resolution |
derived |
⭐ (2026-10-26) a data em que o INAPI decidiu o pedido —não é um prazo—: o ato de aceitação ou de recusa mais recente. date = anchor.date; anchor: {kind: "acceptance" \| "rejection", date, annotationId, sectionCode}, rule: "latest_acceptance_or_rejection", legalBasis Ley 19.039 art. 13 (notification: a resolução é notificada pelo Estado Diario). Aceitação: 029, 444, 484, 485, W146, W151, W152, W147, a seção M4 do Estado Diario e os atos que cumprem uma decisão do TDPI que concede o registro (915, 916, 918, 919, 921, 922, W150, W149); recusa: 024, 486, W160, W148 e a seção M6. No mesmo dia, o código vence a seção. Não aparece (nunca null) se o pedido não chegou a ser decidido (428 «tener por no presentada», desistido ou abandonado antes da decisão), se depois um ato do TDPI o altera sem dizer em que sentido (920, 743, W126) ou num processo de renovação (W390, 539, 706, 632, 961, 540) |
não (400) |
designation_ceased |
derived |
⭐ (2026-10-28) a data em que o INAPI declarou cessada a proteção de uma designação Madrid após uma notificação DEATH da OMPI —não é um prazo—. date = anchor.date; anchor: {kind: "office_cessation", date, annotationId, sectionCode} com a última cessação: 1238 (renúncia ao Chile), 1240 (cancelamento), 1241 (falta de renovação) ou 1242 (dependência da marca de base); o 1237 (transferência parcial) não extingue. rule: "office_cessation_after_wipo_death", legalBasis Protocolo de Madri arts. 6.3, 6.4 e 9 bis e Regulamento Comum regras 25 e 27 (papel extinction). Aparece exatamente quando a marca publica status: caducado por essa cessação (bruto registrada ou denegada, cessação posterior ao último DEATH e ao último PROLONG, sem inscrição do registro posterior). ⭐ (2026-11-04) Também quando o cancelamento da OMPI (DEATH) chegou ao INAPI durante o trâmite e o INAPI concedeu depois (bruto registrada, DEATH anterior à concessão e ao vencimento, sem PROLONG, BIRTH, CORRECTION, cessação nem série adicional no seu dia ou depois): date = anchor.date = o DEATH, anchor: {kind: "wipo_death", date, annotationId, sectionCode: "MAD01"}, rule: "wipo_death_received_before_grant", a mesma legalBasis |
não (400) |
legalBasis é uma lista de {norm, article, role}. opposition_close é derived quando pode ser
afirmado, e estimated —mesma forma, mais estimateReasons— quando não:
published_on_non_business_day— publicada em sábado, domingo ou feriado (a lei não diz a partir de que dia se conta então); conta-se a partir do primeiro dia útil posterior;outside_holiday_calendar— o trecho publicação → fechamento cai fora da cobertura declarada do calendário de feriados (meta.coveragedeGET /holidays, hoje 2013-2030 — ver Feriados); só se descontam fins de semana e os feriados conhecidos, então o fechamento real cai nesse dia ou depois.
oppositionWindow leva a mesma legalBasis e, se estimado, os mesmos estimateReasons. Uma marca
sem data de publicação não tem opposition_close: não há âncora.
Os dois marcos de renovação só existem nas marcas registrada ou esperando_renovacion nacionais com vencimento a partir
de 2022-05-09 (a regra vigente do art. 24). Com eles viaja renewalStatus, em cada marca da
resposta e no expediente, avaliado na data da resposta (hora do Chile):
renewalStatus |
quando (V = vencimento publicado) |
|---|---|
not_due |
antes de V − 6 meses |
window_open |
de V − 6 meses a V, ambos incluídos |
grace |
depois de V e até a data de grace_end, incluída (V + 6 meses, ou o primeiro dia útil seguinte quando esse não é útil): o registro continua em vigor e ainda pode ser renovado |
lapsed |
passada a graça |
renewed_expiry_pending |
no lugar de window_open, grace ou lapsed, antes ou depois de V: a marca tem uma concessão de renovação (um renewals[] de kind: "grant") datada desde V − 6 meses e já registrada — o INAPI já renovou e o vencimento publicado é o anterior, pendente de atualização; a marca não publica renewal_window_open nem grace_end, e volta à regra assim que o vencimento é atualizado |
null |
a regra não se aplica: sem data de vencimento (nunca um status deduzido), nem registrada nem esperando_renovacion, ou via Madri (número de 9 dígitos) |
Vencimentos anteriores a 2022-05-09 seguem o art. 24 antigo: window_open até V, grace até o 30.º dia
útil seguinte, lapsed depois, e sem marcos. renewalStatus descreve o prazo para pedir a
renovação. ⭐ Em grace o registro está em vigor: caduca por falta de renovação só se a graça terminar sem o pedido de
renovação (Ley 19.039 art. 24, inciso 2º), a renovação vale desde o vencimento, sem lacuna (Decreto
82/2022, art. 27, inciso 2º) e a caducidade não é retroativa (Directrices do INAPI, cap. 23). O INAPI cita
os registros em graça como obstáculo do art. 20 h, como cita os vigentes. ⚠ lapsed não diz que a
renovação não foi pedida (uma renovação concedida move o vencimento publicado). A regra
completa, com seus artigos, está na descrição de renewalStatus da referência OpenAPI em
https://api.tarno.cl/docs.
O filtro de marcos se aplica na coleção, na busca, no lote, na similaridade, na janela de oposição e em
/insights, e o mesmo vale para o filtro renewalStatus. Sem milestoneKind casa qualquer um dos
quatro tipos ([BEH]: até 2026-09-25 não olhava as duas datas de renovação). Os tipos de renovação casam
exatamente a data que a marca publica: uma do regime anterior, de Madri ou que não esteja registrada nem esperando_renovacion nunca sai
por eles, mesmo que seu vencimento ± 6 meses caia no intervalo. O filtro por
fechamento devolve exatamente as marcas cujo opposition_close publicado —derivado ou estimado—
cai no intervalo: vira limites sobre a data de publicação (uma só consulta, sem teto de intervalo).
# «Quais desta lista estão no período de graça?» — UMA chamada; cada marca devolvida traz renewalStatus = "grace".
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1171492,1181941,1198902&renewalStatus=grace" \
-H "X-API-Key: $TARNO_API_KEY"
# «Para quais se abre a janela de renovação no mês que vem?»
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=renewal_window_open&milestoneFrom=2026-10-01&milestoneTo=2026-10-31" \
-H "X-API-Key: $TARNO_API_KEY"
# → p. ex. 1257468 OXIBLOCK: renewal_window_open 2026-10-30 (vence 2027-04-30), renewalStatus "not_due"
# «Quais marcas desta lista têm um marco nos próximos 30 dias, e quando?» — UMA chamada com o lote de 100.
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1672581,1712345,1720001&milestoneFrom=2026-09-24&milestoneTo=2026-10-24" \
-H "X-API-Key: $TARNO_API_KEY"
# → results[].milestones = [{ "kind": "expiry", "date": "2026-10-10", "basis": "source", "field": "expiresOn" }]
# O fechamento da janela de oposição de uma marca publicada na sexta-feira 2026-08-14 (1648329):
curl -sS "https://api.tarno.cl/trademarks/1648329" -H "X-API-Key: $TARNO_API_KEY"
# → milestones = [{ "kind": "opposition_close", "date": "2026-09-28", "basis": "derived",
# "anchor": { "kind": "publication", "date": "2026-08-14" },
# "rule": "30_business_days_after_publication",
# "legalBasis": [ { "norm": "Ley 19.039", "article": "5", "role": "term" },
# { "norm": "Ley 19.039", "article": "11", "role": "business_days" },
# { "norm": "Ley 19.880", "article": "25", "role": "computation" } ] }]
# → oppositionWindow.deadline = "2026-09-28", com o mesmo legalBasis
# «Quais marcas fecham a janela de oposição na semana que vem?» — UMA chamada.
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=opposition_close&milestoneFrom=2026-09-28&milestoneTo=2026-10-04" \
-H "X-API-Key: $TARNO_API_KEY"
# → cada marca traz em milestones[] seu opposition_close entre 28-09 e 04-10
O core publica as datas; não avisa ninguém. A quem e quando avisar (30 dias antes, 7, no dia) é decisão da sua aplicação.
Avisos do processo (notices)
Algumas marcas trazem na ficha (GET /trademarks/{applicationNumber} ≡ get_trademark) e no seu
relatório uma lista notices[]: fatos verificados à mão no processo do INAPI e no Registro Internacional
da OMPI que as fontes públicas não trazem. Um aviso não decide mais nada: status, statusInapi,
statusStale e milestones[] são decididos pelas anotações do corpus. A chave é omitida (nunca [] nem
null) em toda marca sem aviso, que são quase todas.
| campo | o que diz |
|---|---|
kind |
wipo_designation_ended: a OMPI inscreveu no Registro Internacional que o Chile não está mais designado · wipo_refused_recording: a OMPI não inscreveu a declaração de concessão de proteção do INAPI (regra 18ter.1 do Regulamento Comum), porque o Chile não figura entre as Partes Contratantes designadas |
date |
a data do fato: a do ato da OMPI, a inscrição ou o aviso de recusa (source.recordedOn) |
cause |
só em wipo_designation_ended; o que a OMPI inscreveu: renunciation (renúncia à designação do Chile), cancellation, dependency (cancelamento por dependência da marca de base, art. 6.4 do Protocolo de Madri), non_renewal |
label |
o aviso em es-CL, en e pt-BR |
source |
a fonte principal: a inscrição da OMPI (kind: "wipo_record"), com reference (RNN/2024/11, CBN/2025/15, ou GP-I/2135499301/BB num aviso de recusa), recordedOn, internationalRegistrationNumber e madridMonitorUrl (o registro no Madrid Monitor; null se o número não foi anotado) |
corroboration |
o respaldo: o documento do processo do INAPI (kind: "inapi_expediente_document") com documentIndex (sua posição no índice do processo), label e date; null se não foi anotado |
Um aviso não decide o status nem os marcos: decidem-nos as anotações do corpus. Uma designação Madrid que o
INAPI concedeu depois de receber o cancelamento da OMPI durante o trâmite publica caducado com o marco
designation_ceased (ver Marcos), e o aviso fica ao lado com a sua fonte; o mesmo se o INAPI ditar a
cessação. Uma marca pode trazer os dois avisos, por ordem de data.
// GET /trademarks/991718309 (trecho)
{
"status": "caducado",
"statusInapi": "registrada",
"statusStale": true,
"notices": [{
"kind": "wipo_designation_ended",
"date": "2024-02-15",
"cause": "renunciation",
"label": { "es-CL": "La OMPI inscribió en el Registro Internacional que Chile ya no está designado. …", "en": "…", "pt-BR": "…" },
"source": {
"kind": "wipo_record",
"reference": "RNN/2024/11",
"recordedOn": "2024-02-15",
"internationalRegistrationNumber": "1718309",
"madridMonitorUrl": "https://www3.wipo.int/madrid/monitor/en/showData.jsp?ID=ROM.1718309"
},
"corroboration": {
"kind": "inapi_expediente_document",
"documentIndex": 11,
"label": "Madrid OD - Notificación de OMPI tipo DEATH",
"date": "2024-02-15"
}
}]
}
Séries de um registro de Madri
Um registro internacional (Protocolo de Madri) pode ter mais de uma série no Chile. O INAPI trata
cada série adicional como uma solicitação à parte e a numera com o número da primeira mais um sufixo
(991652209 e 991652209-2). O contrato faz o mesmo: cada série é mais uma marca, com seu número
de registro, suas classes, suas datas e seu histórico, e é pedida pelo seu próprio número.
| campo | onde | o que diz |
|---|---|---|
baseApplicationNumber |
em uma série adicional: coleção, busca, semelhança, lote, marcas de uma parte, relatórios e ficha | o número de solicitação da série 1 do mesmo registro (991652209) |
seriesSuffix |
igual | o sufixo, tal como o INAPI o escreve (2, A). applicationNumber = baseApplicationNumber + - + seriesSuffix |
relatedSeries[] |
na ficha (GET /trademarks/{applicationNumber} ≡ get_trademark) de qualquer série de um registro do qual o corpus tem várias |
as outras séries, a série 1 primeiro: applicationNumber, seriesSuffix (null na série 1), registrationNumber, status, classes e registeredOn |
Os três campos são omitidos (não viajam como null) em qualquer outra marca: uma marca que não faz
parte de um registro com várias séries responde exatamente o mesmo de antes.
- Em buscas, semelhança, lote e carteira a marca aparece uma vez por série, cada uma com suas classes e seu número de registro. Buscar pelo número de registro de uma série adicional a encontra.
- No calendário de renovação há uma só linha por registro: o registro vence uma vez e é renovado uma vez, então uma série adicional nunca tem linha própria. Hoje, além disso, as marcas da via Madri não publicam marcos de renovação (ver acima).
- Pedir o número base (
991652209) devolve a série 1, como sempre (salvo o caso do expediente com letra, mais abaixo). Pedir991652209-2devolve a série 2. Não remova o sufixo ao normalizar um número: você atribuiria a série 2 à série 1. - A ausência de
relatedSeriesdiz que o corpus não tem outra série desse registro, não que o INAPI não a tenha: uma série ainda em trâmite pode não estar carregada. - O sufixo pode ser uma letra (
991866300-A,-B…): é o expediente que o INAPI abre quando uma parte do registro muda de mãos (transferência parcial). É servido da mesma forma, como mais uma marca, com seu titular, suas classes e seu histórico. Na maioria dos casos a marca viva é a da letra e o número base fica com seu próprio estado (muitas vezes denegada ou cessada): antes de dar por perdida uma marca de Madrid, vejarelatedSeries. - Um registro que no Chile só tem o expediente com letra. Alguns registros internacionais nunca
designaram o Chile com o seu número base: no Chile só existe o expediente com letra (
<base>-A), que é como o INAPI o lista. Essa marca é publicada com o número com letra (baseApplicationNumber= o base,seriesSuffix= a letra, semrelatedSeries) e pedir o número base a encontra do mesmo jeito:GET /trademarks/{applicationNumber}≡get_trademark,/deadlines≡get_deadlinese/annotations≡list_trademark_annotationsrespondem200com a marca com letra (veja o seuapplicationNumber), não404. O lote por número (GET /trademarks?applicationNumber=…), a busca e a vigilância não reconhecem esse número base: use ali o número com letra. Os atos do Estado Diario que o boletim imprime com o número base ficam nessa marca. - Os atos do Estado Diario de uma série adicional aparecem na série 1: o boletim imprime só o número base. O histórico próprio da série vem da ficha de processo do INAPI.
- Uma série pode ser vigiada separadamente, com suas próprias classes.
curl -sS "https://api.tarno.cl/trademarks/991652209" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209", "registrationNumber": "1433511", …
# "relatedSeries": [{ "applicationNumber": "991652209-2", "seriesSuffix": "2",
# "registrationNumber": "1500507", "status": "registrada",
# "classes": [35], "registeredOn": "2026-06-23" }]
curl -sS "https://api.tarno.cl/trademarks/991652209-2" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209-2", "baseApplicationNumber": "991652209", "seriesSuffix": "2", …
# "relatedSeries": [{ "applicationNumber": "991652209", "seriesSuffix": null, … }]
Semântica AND
Todos os parâmetros presentes combinam-se com AND. Cada campo restringe mais o resultado:
# Marcas na classe 9 OU 25 (OR dentro do campo), E cujo titular contém "sonda",
# E depositadas desde 2020 (AND entre campos).
curl -sS "https://api.tarno.cl/trademarks?niceClass=9&niceClass=25&holder=sonda&filedFrom=2020-01-01" \
-H "X-API-Key: $TARNO_API_KEY"
- OR dentro de um campo multivalorado:
?niceClass=9&niceClass=25= classe 9 ou 25. - AND entre campos distintos: adicionar
holder=restringe aos que também cumprem esse predicado.
Nomes de parte: uma vírgula não separa
holder, representative e taxId são texto livre, e um nome de parte leva vírgulas, pontos, & e
aspas («PEPSICO, INC.», «MARS, INCORPORATED», «SARGENT & KRAHN»). Por isso uma vírgula nunca separa
valores nesses três parâmetros: o valor viaja inteiro, com seus sinais. Para vários nomes (OR), repita o
parâmetro; no corpo de POST /trademarks/search e no MCP, um item do array por nome.
# As marcas de «PEPSICO, INC.» OU de «MARS, INCORPORATED» (codifique cada valor: a vírgula viaja como %2C)
curl -sS -G "https://api.tarno.cl/trademarks" \
--data-urlencode "holder=PEPSICO, INC." --data-urlencode "holder=MARS, INCORPORATED" \
-H "X-API-Key: $TARNO_API_KEY"
- Os espaços das pontas são removidos e espaços seguidos contam como um.
- Um valor vazio ou só de espaços, um de menos de 2 caracteres ou um sem letra nem dígito
(
holder=%) é400 validation_error— nunca «sem filtro». - Codifique cada valor: num querystring um
+sem codificar é um espaço (BAUSCH + LOMBviaja comoBAUSCH%20%2B%20LOMB). - Para uma parte concreta, sem substrings, use seu id: Partes por id.
- As demais listas (
niceClass,status,applicationNumber,party,includeApplicationNumber…) são números, ids ou vocabulário fechado e continuam aceitandoa,b.
q é um conjunto de candidatos, não um predicado
Cada canal de q (exato, fuzzy, fonético, semântico) devolve no máximo os seus 200 melhores candidatos e o resultado é
a fusão deles. Com um termo comum (q=cosme casa mais de 200 marcas) a resposta é, portanto, uma amostra dos melhores
candidatos, não todas as marcas que casam.
Os filtros que restringem (filedFrom, niceClass, status, …) aplicam-se dentro de cada canal, antes do limite de
200: com filtro obtém os melhores candidatos do conjunto filtrado, não os de q isolado cortados depois. Não assuma:
q & filtronão é um subconjunto deq: o filtro pode trazer marcas queqisolado não devolvia por ficarem fora do limite. Medido (2026-10-14):q=cosme⇒ 553 marcas;q=cosme&filedFrom=2020-01-01⇒ 566, 359 delas ausentes da primeira.meta.estimatedTotalé o tamanho desse conjunto de candidatos (limite inferior, nunca o total do corpus que casa). É exato para o que essa consulta pagina, mas uma consulta com filtro e outra sem não são comparáveis: um total maior com filtro não significa que o filtro ampliou a busca.- Para contar ou percorrer todas as marcas que cumprem um critério, use a listagem por campos (sem
q).
Regra q + campos
q é descartado somente quando chega junto com um campo competidor de texto/identidade —
denomination, applicationNumber ou registrationNumber — que então conduz a busca combinada. Os filtros
de restrição (niceClass, status, signType, filedFrom/To, holder, representative, taxId)
não descartam q: mantêm-no e só o restringem com AND.
?q=cafe⇒ busca de texto clássica (ranqueada, levascore).?q=cafe&niceClass=43⇒qé mantido; o resultado é «marcas café na classe 43».?q=cafe&denomination=nescafe⇒qé descartado (chegou um campo competidor);denomination=conduz.- Para buscar por denominação dentro do modo avançado, use
denomination=(nãoq=).
Ordem e sort=
sort= escolhe a ordem; explícito sempre vence. Sem sort=, com texto é relevance (RRF) e sem texto
é filedOn desc. Marcas com filedOn nulo ficam no fim. Um sort fora da lista retorna
400 validation_error.
Cada elemento de results[] traz as quatro datas pelas quais se pode ordenar e filtrar: filedOn,
publishedOn, registeredOn e expiresOn (YYYY-MM-DD ou null), as mesmas da ficha
(GET /trademarks/{applicationNumber} ≡ get_trademark). Assim é possível mostrar e conferir a ordem
recebida sem pedir a ficha de cada marca.
A lista de campos ordenáveis e sua paginação exata vive na referência
https://api.tarno.cl/docs— não é duplicada aqui.
matchedFields[]
Cada elemento de results[] pode incluir matchedFields[], respondendo «por que esta marca apareceu?».
Cada entrada é { field, kind } (field = campo que casou; kind = canal: exact, fuzzy, phonetic,
semantic). field é o nome do filtro que fez a marca aparecer: denomination, applicationNumber,
registrationNumber, holder, representative ou taxId (e highlight.field é denomination). É omitido
quando não há match de identidade/texto (p. ex. uma listagem pura por
?niceClass=9). É aditivo: um cliente que não o lê continua funcionando.
Semelhança e termos genéricos: o canal distinctive
Com similarTo (texto livre), o motor de semelhança soma um quarto canal, distinctive. Ele busca pelo
elemento distintivo do texto: o que resta ao tirar os termos genéricos nas classes pedidas e ao separar
as palavras coladas. Existe por um caso real: «ALTODESEMPEÑO CONSULTORES» na classe 35 só encontrava marcas
com «CONSULTORES» e não via «MAS DESEMPEÑO».
O que conta como genérico:
- Lista curada neutra, com fonte e data de revisão em cada entrada (versão
2026-09-28): conectores (de,la,the…), formas societárias (ltda,s.a.,spasó no final e nunca nas classes 3 e 44…), gentílicos, domínios, e palavras de comércio (classes 35 e 25) ou de serviços profissionais (35 e 42). - Frequência na classe: uma palavra presente em pelo menos
max(50, 0,75 %)das marcas da classe (p. ex. «cafe» na 43, «clinica» na 44). - Palavras coladas: «altodesempeno» ⇒ «alto» + «desempeno», só se a palavra inteira não está no corpus e as duas partes estão.
O desconto é declarado. Quando o canal roda, as marcas que ele trouxe levam distinctive em
matchedBy, e meta publica genericTerms (cada termo com seus motivos), distinctiveCore (o que se
buscou) e decompounded. signals e score não mudam: continuam medindo o texto inteiro.
Quando não roda. Se não há nada a descontar, se só restam termos genéricos ou se o que resta tem menos de 3 letras (p. ex. «AB CONSULTORES» ⇒ «ab», que se parece com qualquer coisa), o canal não roda: a resposta é exatamente a de antes e as três chaves não viajam. Também não roda se falhar (fica registrado e a busca segue com os outros canais). A vigilância de semelhantes não o usa (está desativado nela).
Quanto pesa na ordem. Na fusão, o canal distintivo pesa 2 (os canais semântico e léxico pesam 1, o fonético 2). O peso foi calibrado em 2026-09-29 com o corpus real: 32 casos medidos em produção. É o menor peso com o qual as 19 marcas que deviam aparecer entram no grupo do relatório de disponibilidade, sem deixar entrar marcas alheias nas 20 primeiras dos 13 casos de controle. Com 2, «MAS DESEMPEÑO» sai em 32.º para «ALTODESEMPEÑO CONSULTORES» (antes, com 1,5, saía em 77.º).
Latência. Quando há termos genéricos a descontar, o canal acrescenta cerca de 0,7 s à resposta (medido em produção em 2026-09-28: ~0,73–0,79 s a quente e ~1 s na primeira vez por classe). Sem termos genéricos não acrescenta nada.
⛔ Uma palavra ser genérica não é um veredicto sobre a registrabilidade: é como o motor decide o que buscar, e isso é dito.
RUT: normalização e invalid_rut
O parâmetro taxId casa exato contra o RUT de titular e representante. O servidor normaliza
o valor antes de comparar, aceitando os três formatos:
| Entrada | Normalizado para |
|---|---|
76.123.456-7 |
76123456-7 |
761234567 |
76123456-7 |
76123456-7 |
76123456-7 |
⭐ Um
taxIdbem formado cujo dígito verificador não calcula não é mais erro: retorna resultado vazio (o corpus guarda pessoas cujo RUT falha o DV). UmtaxIdcuja forma não é de RUT (letras no corpo, ou DV fora de0–9/K) retorna400 invalid_rut— idêntico em REST e MCP.⭐
partyRole(desde 2026-09-28) limita otaxIda um papel:holder(titular) ourepresentative(representante). SempartyRole, o RUT casa com os dois papéis, como sempre; combina comrelation(p. ex.partyRole=representative&relation=former: as marcas que esse RUT representou).partyRolesemtaxIdé400 validation_error, idêntico em REST e MCP.curl -s "$TARNO_BASE_URL/trademarks?taxId=76.086.428-5&partyRole=representative" -H "X-API-Key: $TARNO_API_KEY"⭐ RUT de pessoas físicas. Hoje o RUT de toda parte é publicado inteiro e
taxIdencontra qualquer uma. O serviço pode passar a um modo, anunciado antes no changelog, no qual otaxIdde uma parte cujokindnão élegalvem mascarado (***678-5: os 3 últimos dígitos do corpo e o dígito verificador) e o filtrotaxIdsó encontra pessoas jurídicas (o RUT de uma pessoa física devolve uma resposta vazia, não um erro). Esse modo reconhece-se pormeta.naturalPersonTaxId: "masked"em toda coleção; se a chave não estiver, nada muda.
Partes por id
party=<id>:<papel> filtra pela identidade da parte, não pelo nome: não traz marcas de partes com
nome parecido e serve também para partes sem RUT (estrangeiras). O id é o de GET /parties?q= ≡
list_parties; o papel, holder (titular) ou representative (representante).
- Vários valores somam-se (OR): saem as marcas em que alguma dessas partes tem esse papel.
partycombina-se com AND com os demais filtros (niceClass,status, datas…). - O papel significa o mesmo que em
GET /parties/{id}/trademarks?role=: uma parte inscrita como titular e representante conta para os dois, erelationescolhe vínculos atuais (padrão), anteriores ou todos.party=<id>:representativedevolve as mesmas marcas queGET /parties/{id}/trademarks?role=representative, agora com filtros, ordenação, facetas e cursor. - Repetível ou separado por vírgulas, até 20 valores. Um valor sem a forma
<id>:<papel>ou mais de 20 é400 validation_error, idêntico em REST e MCP. Um id que não é de nenhuma parte não casa com nenhuma marca. - Vale também em
POST /trademarks/search(comsimilarTo/similarToTrademark), em/insights/trademarkse no calendário de renovação; comoppositionWindowé um400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&party=1234:holder&niceClass=25" -H "X-API-Key: $TARNO_API_KEY"
Carteira à mão: incluir e excluir pedidos
Uma carteira é o que dizem os seus filtros de parte, mais alguns pedidos acrescentados à mão, menos outros retirados à mão; sobre isso aplicam-se os filtros da listagem:
resultado = ((âmbito da carteira ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ demais filtros
- O âmbito da carteira são os filtros de parte:
party,holder,representativeetaxId(compartyRole), com o seurelation. Entre si continuam a combinar-se com AND, como sempre. - Todo o resto é filtro da listagem e aplica-se depois, também aos incluídos:
q,denomination,status,niceClass,signType, datas, marcos,renewalStatus,liveOnly,goodsAndServicese o loteapplicationNumber. Um incluído que não os cumpra não aparece. - A exclusão ganha: um pedido excluído não sai mesmo que case com o âmbito ou esteja incluído.
- Sem nenhum filtro de parte, os incluídos são a carteira (só eles, ∩ os filtros da listagem); a exclusão retira igual, também sobre o corpus inteiro.
- A ordem, o cursor,
totalemeta.facetscalculam-se sobre o conjunto final. - Repetível ou separado por vírgulas, até 500 números por parâmetro, escritos como o INAPI os
escreve (
991652209-2,990373519-C). Para listas longas, use vírgulas noGET(500 números repetidos um a um não cabem num URL) ou o corpo dePOST /trademarks/search, que aceita o mesmo. Um número malformado, uma lista vazia ou mais de 500 é400 validation_error, igual em REST e MCP. Um número que não existe não soma nada. - Vale também em
POST /trademarks/search(comsimilarTo/similarToTrademark), em/insights/trademarkse no calendário de renovação; comoppositionWindowé um400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&includeApplicationNumber=1672581&excludeApplicationNumber=991652209-2&status=registrada" -H "X-API-Key: $TARNO_API_KEY"
O objeto portfolio: o que foi adicionado à mão está sempre dentro
Com os campos planos acima, um pedido incluído à mão sai quando não cumpre os filtros que refinam a
carteira (classe, estado, datas…). O objeto portfolio separa os dois tipos de filtros:
resultado = (((partes ∩ refine) ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ filtros de primeiro nível
{
"portfolio": {
"party": ["123:holder", "456:representative"],
"refine": { "niceClass": [9, 42], "status": ["registrada"], "filedFrom": "2015-01-01" },
"includeApplicationNumber": ["1672581"],
"excludeApplicationNumber": ["991652209-2"]
},
"niceClass": [9]
}
portfolio.party: as partes da carteira, com o mesmo valor queparty(<id>:<papel>).portfolio.refine: os refinamentos da carteira. Aceita os mesmos filtros de predicado que/trademarks/application-numbers(niceClass,status, datas, marcos,renewalStatus,liveOnly,holder/taxId,relation, o lote…) e restringe só as marcas das partes. O seurelationdecide também com que vínculos se leem as partes deportfolio.party.q,denomination, os motores,facets, os filtros de norma eparty/includeApplicationNumber/excludeApplicationNumberdentro derefinesão um400.portfolio.includeApplicationNumber: sempre na carteira, diga o que disserrefine.portfolio.excludeApplicationNumber: sempre fora — a exclusão ganha.- Os filtros de primeiro nível são os da listagem (o que o usuário acrescenta ao navegar) e aplicam-se ao conjunto inteiro, também aos incluídos.
- Sem
portfolio.partya carteira são os seus incluídos (∩ a listagem), nunca o corpus. - Dentro de
portfolio, cada lista aceita até 10.000 números. - Com
portfolio,party,includeApplicationNumberouexcludeApplicationNumberde primeiro nível são400 validation_error(uma entradanot_combinablepor campo): cada coisa num só lugar. Semportfolio, tudo continua como acima. - Só pelo corpo:
POST /trademarks/searchePOST /trademarks/application-numbers(e no MCP,search_trademarkselist_application_numbers).GET /trademarkscontinua plano. ComoppositionWindowé um400; comsimilarTo/similarToTrademarka semelhança ordena-se dentro da carteira.
O objeto text: busca de texto configurável
text configura a busca de texto com o vocabulário do Algolia. Com todas as opções no padrão
responde exatamente o mesmo que q; q/denomination continuam sendo o atalho de
text: { query }, e combiná-los com text é um 400.
{
"text": {
"query": "colgate",
"queryType": "contains",
"typoTolerance": false,
"minWordSizefor1Typo": 1,
"minWordSizefor2Typos": 1,
"exactOnSingleWordQuery": "word",
"removeWordsIfNoResults": "allOptional",
"phonetic": false,
"semantic": false,
"getRankingInfo": false
}
}
| opção | valores (padrão primeiro) | o que faz |
|---|---|---|
queryType |
prefixNone, prefixLast, prefixAll, contains, exact |
Como uma palavra casa: inteira; a última pode ser o início de uma palavra; todas podem ser; em qualquer ponto da denominação, também dentro de uma palavra; a denominação inteira, palavra a palavra. |
typoTolerance |
true, false, min, strict |
Erros de digitação (Levenshtein) por palavra segundo o tamanho; min deixa só as de menos erros; strict, essas e as de um a mais. |
minWordSizefor1Typo · minWordSizefor2Typos |
1 · 1 |
Tamanho mínimo de palavra para aceitar 1 e 2 erros (o Algolia usa 4 e 8). |
exactOnSingleWordQuery |
word, attribute, none |
O que é «exata» na ordem com uma só palavra: a denominação a contém; a denominação é essa palavra; nada. |
removeWordsIfNoResults |
allOptional, none, lastWords |
Que palavras se exigem: basta uma (mais palavras ordenam primeiro); todas; todas ou, se nenhuma marca tem todas, a sequência inicial mais longa que tem. |
phonetic · semantic |
true · true |
Acrescentam as parecidas fonéticas e semânticas depois do bloco de palavras-chave. |
getRankingInfo |
false |
Acrescenta rankingInfo a cada acerto: bloco, exata, prefixo, palavras e erros. |
Dois blocos, nesta ordem. Configurado, primeiro vem o bloco de palavras-chave: um conjunto
determinístico e completo (uma marca está ou não está pelas regras acima, sem teto por canal),
ordenado exata → prefixo (a denominação começa pela consulta) → mais palavras → menos erros → sort →
número de pedido. Depois, com phonetic ou semantic, as aproximadas, sem borda definida e em
ordem de relevância (sort não as reordena). Sem aproximadas, total é o tamanho exato da
resposta; com elas (se algum desses canais roda) total não vem, meta.keywordTotal é o tamanho exato do bloco de palavras-chave
e meta.estimatedTotal conta os dois blocos (limite inferior). O cursor percorre essa mesma ordem e
está ligado ao pedido. Qualquer opção fora do padrão (também getRankingInfo: true) escolhe este
motor.
queryaceita no máximo 16 palavras, repetidas incluídas; sem nenhuma letra nem dígito é um400. Uma opção que nunca atua com as demais também é um400(typoTolerance: falsecom tamanhos mínimos,exactcomremoveWordsIfNoResults);exactOnSingleWordQueryeremoveWordsIfNoResults, cujo efeito depende do número de palavras, são aceitos com qualquer consulta.-
Com os tamanhos mínimos padrão (1 e 1) toda palavra aceita 2 erros: uma palavra curta fora de uma carteira pode dar
422. Para uma caixa de busca geral,minWordSizefor1Typo: 4eminWordSizefor2Typos: 8(os do Algolia). -
Em
GET /trademarksvai achatado:text=colgate&textQueryType=contains&textTypoTolerance=false&textPhonetic=false&textSemantic=false. Uma opção semtexté um400. - Em
/trademarks/application-numberse emportfolio.refine.textvale como conjunto: só o bloco de palavras-chave, então exigephonetic: falseesemantic: false(getRankingInfonão é aceito). - Com
portfolio, umtextde primeiro nível restringe e ordena o conjunto final. textcom o lote,registrationNumber,similarTo/similarToTrademarkouoppositionWindowé um400, eminScorecomtextconfigurado também. Onde se responde um conjunto,exactOnSingleWordQuery(só ordena) também é um400.- Uma página de aproximadas cujos canais não são os da anterior (um falhou ou demorou) é
409 cursor_stale: recomece semcursor. Sem nenhuma coincidência de palavras-chave e com todos os canais aproximados fora,503: tente de novo, não significa «não há marcas». - Um bloco de palavras-chave com mais de 50.000 candidatas é
422 text_set_too_large: restrinja o filtro, use palavras mais longas ou tire a tolerância a erros.
# A caixa de busca de uma carteira: literal, total exato.
curl -s -X POST "$TARNO_BASE_URL/trademarks/search" -H "X-API-Key: $TARNO_API_KEY" -H 'Content-Type: application/json' \
-d '{"portfolio":{"party":["306948:representative"]},"text":{"query":"colgate","queryType":"contains","typoTolerance":false,"phonetic":false,"semantic":false}}'
Paginação: somente keyset
Não há offset. A paginação é keyset por cursor, para todas as ordens:
- Para a próxima página, reenvie
nextsem mudanças comocursor. next: nullsignifica fim — pare.- O cursor é opaco (base64url das chaves de ordem); trate como caixa-preta.
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# página 2: reenvie o `next` da página 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20&cursor=<next>" -H "X-API-Key: $TARNO_API_KEY"
Todos os números de um filtro, por páginas
GET /trademarks/application-numbers ≡ list_application_numbers (escopo brands:read) devolve só os
números de pedido de todas as marcas que casam com o filtro, ordenados por número de pedido como
texto (não numérico: 1000001 vem antes de 990373519-C), em páginas de até 10.000. O filtro é o
de GET /trademarks (lote, partes, carteira à mão, classe, estado, datas, marcos, renewalStatus,
liveOnly, goodsAndServices…) e o conjunto é o mesmo que a coleção percorreria página a página.
{ "applicationNumbers": ["1161630", "1192677"], "total": 2, "next": null, "cap": 10000,
"dataAsOf": "2026-10-18T03:12:44.000Z", "coverageThrough": "2026-10-17" }
limit(1..10.000, por omissão 10.000 =cap) fixa o tamanho da página.nexté o cursor opaco da página seguinte enullna última: enquanto não fornulla lista está incompleta.totalé a contagem exata do conjunto inteiro e, comodataAsOf, é a mesma em todas as páginas.- O cursor volta como
cursorcom o mesmo filtro (limitpode mudar); com outro filtro é400 validation_errorsobrecursor. Num percurso nenhum número se repete nem se perde. - Se uma sincronização do corpus começou ou terminou entre duas páginas, a seguinte responde
409 cursor_stale: recomece da página um, semcursor. - Só predicados:
q,denomination,similarTo,similarToTrademark,allClasses,oppositionWindow,facetse os filtros de norma são400 validation_errorcom uma entrada por campo (os motores de texto e de semelhança ordenam uma vizinhança, não definem um conjunto). Não hásortnemminScore. - Um lote de mais de 100 é
422 batch_too_large, como na coleção. POST /trademarks/application-numbersdá a mesma resposta com o filtro no corpo JSON (mesmolimit,cursor,next,409 cursor_stale), e é a única forma que aceita o objetoportfolio. O cursor está atado ao filtro inteiro,portfolioincluído.
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada" -H "X-API-Key: $TARNO_API_KEY"
# a página seguinte, com o `next` da anterior:
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada&cursor=$NEXT" -H "X-API-Key: $TARNO_API_KEY"
Paridade MCP
A ferramenta MCP search_trademarks aceita exatamente os mesmos parâmetros com idêntica semântica
(incluindo sort, a normalização de taxId e o erro invalid_rut), e devolve o mesmo JSON que
GET /trademarks para a mesma pergunta. O lote é search_trademarks com
applicationNumber: [a, b, c]. Veja o guia de MCP.
Até 2026-09-24 esta rota tinha a sua própria ferramenta gêmea de listagem; foi retirada porque era a mesma pergunta que
search_trademarks. A rota REST não muda.
Tempo de resposta
Uma busca por texto (q ou denomination) consulta quatro canais ao mesmo tempo: exato, aproximado,
fonético e por significado. Não espera por um canal mais de 3 s: passado esse tempo, e com pelo
menos um canal que já tenha encontrado coincidências, responde 200 com os que tem. O normal é que os quatro respondam em menos de
um segundo; o limite só atua quando um está lento.
Como é uma resposta à qual faltou um canal (igual a quando um canal falha):
- as coincidências desse canal não estão na página, e a sua etiqueta (
exact,fuzzy,phonetic,semantic) não aparece emmatchedBynem emmatchedFields[].kind; - se faltou o canal por significado,
signals.semanticpode virnullem todos os resultados (nullé «não avaliado», nunca um 0); meta.estimatedTotalconta o que encontraram os canais que responderam;- ⭐
meta.degradedChannelsnomeia os canais que faltaram (p. ex.["semantic"]), com o mesmo vocabulário dematchedBy. Ausente = correram todos.semanticsó conta onde há serviço de significado configurado. Vale igual parasimilarTo(canaisfuzzy,semantic,distinctive) e paratext(phonetic,semantic).
As páginas seguintes de uma busca por relevância com q, denomination ou similarTo são montadas
com os mesmos canais da primeira
(o cursor lembra-os): se um que estava na primeira falha agora, a resposta é o 503 reexecutável;
se um que faltou na primeira volta, continua de fora e é declarado em meta.degradedChannels, para
que o percurso não repita nem salte marcas. (Com text uma mudança de canais entre páginas
continua a ser 409 cursor_stale.) Um minScore explícito que descarta tudo continua a dar uma página
vazia, com meta.degradedChannels se faltou algum canal.
A mesma busca repetida alguns segundos depois pode trazer mais coincidências e uma ordem ligeiramente
diferente. Por isso convém pedir as páginas de uma busca seguidas, sem uma espera longa entre uma e a
seguinte. Nunca se devolve por isto uma página vazia: se aos 3 s nenhum canal encontrou nada, a busca
continua à espera do primeiro que encontre algo ou de que terminem todos (uma página vazia continua a
significar que todos correram e nenhum encontrou nada); se faltar algum e os demais não encontrarem
nada, é o 503 da tabela abaixo.
O objetivo de latência da busca (p95 < 3 s) está no SLA. similarTo não tem este
limite.
Erros
Todos os erros usam o corpo RFC 9457 descrito em primeiros passos.
| HTTP | code |
Quando |
|---|---|---|
| 400 | validation_error |
Parâmetros inválidos (sort fora do enum, niceClass fora de 1–45, data malformada). |
| 400 | invalid_rut |
Um taxId cuja forma não é de RUT — também com similarTo/similarToTrademark e oppositionWindow. |
| 400 | invalid_range |
Um intervalo com From > To (filedFrom/To, expiresFrom/To, registeredFrom/To, publishedFrom/To, milestoneFrom/To) — também com semelhança e janela de oposição. |
| 400 | validation_error |
⭐ Um parâmetro que a rota não declara (uma entrada de errors[] por chave, field = a chave) — nunca é ignorado em silêncio. |
| 400 | validation_error |
O lote combinado com limit, cursor, sort, minScore, q, denomination ou facets — uma entrada de errors[] por campo (field = o campo, code: "not_combinable"). |
| 400 | validation_error |
⭐ As demais regras do despacho —o que a semelhança ou a janela de oposição não aplicam, similarTo com similarToTrademark, oppositionWindow sem niceClass, partyRole sem taxId, milestoneKind sem intervalo, os filtros de norma sobre marcas, um goodsAndServices sem nada pesquisável— também trazem errors[], uma entrada por campo: code: "not_combinable" se conflita com outro campo da requisição (o detail diz qual), "custom" para outra regra do contrato (o code que a validação de schemas dá a uma regra própria), "too_big"/"too_small" para um tamanho. |
| 422 | batch_too_large |
Um lote (applicationNumber) com mais de 100 valores. |
| 422 | text_set_too_large |
O bloco de palavras-chave de text tem mais de 50.000 candidatas ou é custoso demais de verificar. |
| 401 / 403 | unauthorized / forbidden |
Chave ausente/inválida, ou falta o escopo brands:read. |
| 429 | rate_limited / quota_exceeded |
Limite de rajada ou cota mensal. |
| 503 | service_unavailable |
⭐ Uma busca por texto (q, denomination, text ou similarTo) em que faltou algum canal e os demais não encontraram nada, ou em que todos falharam. Reexecutável. Uma página vazia lê-se como «nenhuma marca coincide», e com um canal fora do ar isso não se sabe: até 2026-10-01 era um 200 vazio com tudo fora do ar, e até 2026-11-03 com algum canal fora do ar. Se alguns falham e os demais encontram algo, responde 200 e declara-os em meta.degradedChannels. Também é 503 a página seguinte cujo canal da primeira está fora do ar agora, e uma página que não se pôde ler inteira. |
Veja também
- Primeiros passos — URL base, envelope, paginação por keyset, corpo de erro.
- Busca de pessoas —
GET /parties, a pessoa como sujeito da consulta. - Autenticação e escopos —
X-API-Key,brands:read. - A referência OpenAPI ao vivo em
https://api.tarno.cl/docs.