Ir para o conteúdo

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 — q ranqueia 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, com meta.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á em notFound). O lote não pagina nem ordena: limit, cursor, sort, minScore, q, denomination ou facets com applicationNumber são um 400.

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.coverage de GET /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). Pedir 991652209-2 devolve 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 relatedSeries diz 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, veja relatedSeries.
  • 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, sem relatedSeries) e pedir o número base a encontra do mesmo jeito: GET /trademarks/{applicationNumber} ≡ get_trademark, /deadlines ≡ get_deadlines e /annotations ≡ list_trademark_annotations respondem 200 com a marca com letra (veja o seu applicationNumber), não 404. 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 + LOMB viaja como BAUSCH%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 aceitando a,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 & filtro não é um subconjunto de q: o filtro pode trazer marcas que q isolado 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, leva score).
  • ?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ão q=).

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., spa só 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 taxId bem formado cujo dígito verificador não calcula não é mais erro: retorna resultado vazio (o corpus guarda pessoas cujo RUT falha o DV). Um taxId cuja forma não é de RUT (letras no corpo, ou DV fora de 0–9/K) retorna 400 invalid_rut — idêntico em REST e MCP.

⭐ partyRole (desde 2026-09-28) limita o taxId a um papel: holder (titular) ou representative (representante). Sem partyRole, o RUT casa com os dois papéis, como sempre; combina com relation (p. ex. partyRole=representative&relation=former: as marcas que esse RUT representou). partyRole sem taxId é 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 taxId encontra qualquer uma. O serviço pode passar a um modo, anunciado antes no changelog, no qual o taxId de uma parte cujo kind não é legal vem mascarado (***678-5: os 3 últimos dígitos do corpo e o dígito verificador) e o filtro taxId só encontra pessoas jurídicas (o RUT de uma pessoa física devolve uma resposta vazia, não um erro). Esse modo reconhece-se por meta.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. party combina-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, e relation escolhe vínculos atuais (padrão), anteriores ou todos. party=<id>:representative devolve as mesmas marcas que GET /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 (com similarTo/similarToTrademark), em /insights/trademarks e no calendário de renovação; com oppositionWindow é um 400.
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, representative e taxId (com partyRole), com o seu relation. 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, goodsAndServices e o lote applicationNumber. 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, total e meta.facets calculam-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 no GET (500 números repetidos um a um não cabem num URL) ou o corpo de POST /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 (com similarTo/similarToTrademark), em /insights/trademarks e no calendário de renovação; com oppositionWindow é um 400.
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 que party (<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 seu relation decide também com que vínculos se leem as partes de portfolio.party. q, denomination, os motores, facets, os filtros de norma e party/includeApplicationNumber/ excludeApplicationNumber dentro de refine são um 400.
  • portfolio.includeApplicationNumber: sempre na carteira, diga o que disser refine.
  • 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.party a 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, includeApplicationNumber ou excludeApplicationNumber de primeiro nível são 400 validation_error (uma entrada not_combinable por campo): cada coisa num só lugar. Sem portfolio, tudo continua como acima.
  • Só pelo corpo: POST /trademarks/search e POST /trademarks/application-numbers (e no MCP, search_trademarks e list_application_numbers). GET /trademarks continua plano. Com oppositionWindow é um 400; com similarTo/similarToTrademark a 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.

  • query aceita no máximo 16 palavras, repetidas incluídas; sem nenhuma letra nem dígito é um 400. Uma opção que nunca atua com as demais também é um 400 (typoTolerance: false com tamanhos mínimos, exact com removeWordsIfNoResults); exactOnSingleWordQuery e removeWordsIfNoResults, 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: 4 e minWordSizefor2Typos: 8 (os do Algolia).

  • Em GET /trademarks vai achatado: text=colgate&textQueryType=contains&textTypoTolerance=false&textPhonetic=false&textSemantic=false. Uma opção sem text é um 400.

  • Em /trademarks/application-numbers e em portfolio.refine.text vale como conjunto: só o bloco de palavras-chave, então exige phonetic: false e semantic: false (getRankingInfo não é aceito).
  • Com portfolio, um text de primeiro nível restringe e ordena o conjunto final.
  • text com o lote, registrationNumber, similarTo/similarToTrademark ou oppositionWindow é um 400, e minScore com text configurado também. Onde se responde um conjunto, exactOnSingleWordQuery (só ordena) também é um 400.
  • Uma página de aproximadas cujos canais não são os da anterior (um falhou ou demorou) é 409 cursor_stale: recomece sem cursor. 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 next sem mudanças como cursor.
  • next: null significa 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 e null na última: enquanto não for null a lista está incompleta. total é a contagem exata do conjunto inteiro e, como dataAsOf, é a mesma em todas as páginas.
  • O cursor volta como cursor com o mesmo filtro (limit pode mudar); com outro filtro é 400 validation_error sobre cursor. 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, sem cursor.
  • Só predicados: q, denomination, similarTo, similarToTrademark, allClasses, oppositionWindow, facets e os filtros de norma são 400 validation_error com uma entrada por campo (os motores de texto e de semelhança ordenam uma vizinhança, não definem um conjunto). Não há sort nem minScore.
  • Um lote de mais de 100 é 422 batch_too_large, como na coleção.
  • POST /trademarks/application-numbers dá a mesma resposta com o filtro no corpo JSON (mesmo limit, cursor, next, 409 cursor_stale), e é a única forma que aceita o objeto portfolio. O cursor está atado ao filtro inteiro, portfolio incluí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 em matchedBy nem em matchedFields[].kind;
  • se faltou o canal por significado, signals.semantic pode vir null em todos os resultados (null é «não avaliado», nunca um 0);
  • meta.estimatedTotal conta o que encontraram os canais que responderam;
  • ⭐ meta.degradedChannels nomeia os canais que faltaram (p. ex. ["semantic"]), com o mesmo vocabulário de matchedBy. Ausente = correram todos. semantic só conta onde há serviço de significado configurado. Vale igual para similarTo (canais fuzzy, semantic, distinctive) e para text (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