Busca de pessoas
Este guia cobre a leitura centrada na pessoa: encontrar um titular ou representante e saber quanto do registro é dele. Complementa a busca por campos, onde as pessoas são um filtro sobre marcas; aqui elas são o sujeito da consulta.
O schema completo, sempre atualizado e por campo, vive na referência OpenAPI interativa em
https://api.tarno.cl/docs(Scalar). Este guia explica o contrato 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.
GET /parties · escopo brands:read · gêmeo MCP: list_parties
O recurso parties inverte a pergunta: parte da pessoa e diz quanto do registro é dela. Titular,
requerente, representante e oponente são uma entidade com um role ali onde intervém.
curl -sS "https://api.tarno.cl/parties?q=carey" -H "X-API-Key: $TARNO_API_KEY"
{
"results": [
{
"id": "1261017",
"name": "ESTUDIO CAREY LIMITADA",
"taxId": "76111111-6",
"country": "CL",
"kind": "legal",
"kindSource": "tax_id",
"trademarkCount": 3492,
"publishedName": "Estudio Carey Limitada",
"review": null,
"mergedInto": null
}
],
"limit": 20,
"next": null,
"hasMore": false,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" }
}
Como buscar
| Parâmetro | O que faz |
|---|---|
q |
Correspondência parcial e insensível a acentos sobre o nome. Entre 2 e 256 caracteres. argandona encontra Argandoña. |
taxId |
Correspondência exata. Aceita qualquer formato (12.345.678-5, 12345678-5) e normaliza. |
kind |
natural | legal | unknown. |
role |
holder | applicant | representative | opponent. |
sort |
trademarkCount (padrão, do maior para o menor) | name, com asc ou desc opcional (name desc). |
limit / cursor |
Paginação com cursor opaco. limit padrão 20, máximo 100. |
Nenhum parâmetro é obrigatório: sem filtros são listadas todas as partes, inclusive as que não têm marcas.
Sem sort, os resultados vêm ordenados por volume de marcas, do maior para o menor.
As duas ordens são rápidas, com qualquer filtro. A contagem de marcas de cada parte é guardada no fim de
cada sincronização diária, então a ordem por volume sai por índice; com sort=name a página é escolhida
primeiro e a contagem é calculada só para as suas linhas. ⚠ Enquanto uma sincronização está em curso (uns
25 minutos por dia) a contagem guardada deixa de ser afirmada e a ordem por volume é calculada na hora: a
resposta é a mesma, mas leva de um a três segundos (até oito com kind ou role).
Cada resposta traz em meta a atualidade do corpus: dataAsOf (quando terminou a última sincronização) e
coverageThrough (até que data de depósito chega a cobertura).
As contagens são de AGORA — trademarkCount não filtra
trademarkCount conta somente o que a pessoa tem hoje. ⭐ Não filtra: pessoas sem nenhuma
marca continuam aparecendo, com o trademarkCount em zero — uma pessoa sem marcas hoje pode tê-las
amanhã, e por que ela está ali é um dado.
Partes fundidas — mergedInto
Quando duas fichas acabam sendo a mesma parte (o mesmo titular escrito de duas formas, um RUT corrigido…),
uma é fundida na outra: suas marcas e anotações passam para a que sobrevive. A ficha fundida não
aparece em GET /parties (list_parties), em nenhuma ordenação ou filtro. Se você guardou o id dela,
GET /parties/{id} (get_party) continua a devolvê-la, com mergedInto = o id da parte que tem hoje as
marcas dela (o fim da cadeia, se essa também foi fundida depois). Em qualquer outra parte, mergedInto é
null.
As demais leituras por id (/trademarks, /relations, /outcomes, o relatório de carteira) respondem
pela ficha pedida, que depois da fusão já não tem marcas: para os dados da parte, use o id de mergedInto.
O que diz o SII — sii
Cada parte com RUT chileno que consta da nómina de pessoas jurídicas do SII leva o bloco sii (em
GET /parties/{id} ≡ get_party e em cada parte de GET /parties ≡ list_parties): a razão social
(legalName; o nome do INAPI continua em name), o subtipo (companyType: código do SII, a nossa etiqueta
em três idiomas e o literal do SII), o início de atividades, o término de giro, a comuna e a região do
domicílio atual segundo o SII e as filiais atuais por comuna. A rua e o número não se publicam.
- Origem e data em cada bloco:
source: "sii"easOf= a data do ficheiro do SII de onde foi lido. A nómina e os endereços são dois ficheiros, cada um com a sua data. Uma mudança posterior a essa data não se vê. addressé o domicílio ATUAL segundo o SII (basis: "current_sii_domicile"), não o do pedido: esse éterritory, do INAPI. Muitas vezes não coincidem (mudanças de endereço).businessEndedOné o término de giro: o fim da atividade tributária, não uma dissolução. Uma sociedade com giro terminado pode continuar titular das suas marcas.sii: null= não há dado: a parte não tem RUT chileno, o ficheiro atual do SII não a lista (ou lista-a com outro dígito verificador), ou a parte foi fundida noutra (mergedInto; leia essa). Nunca um valor deduzido. Dentro do bloco,branches: null= ainda não há endereços lidos para esse RUT;address: null= ainda não lidos ou o SII não lista um domicílio atual para ele (sebranchestiver valor, é o segundo caso);branches.count: 0= o SII não lista filiais atuais.address.regionNameé o texto literal do SII: para comparar regiões useregionCode.
"sii": {
"source": "sii",
"asOf": "2026-08-05",
"legalName": "EJEMPLO SOCIEDAD POR ACCIONES",
"companyType": {
"code": "223",
"label": { "es-CL": "Sociedad por acciones (SpA)", "en": "Stock company (SpA)", "pt-BR": "Sociedade por ações (SpA)" },
"source": { "label": "SOCIEDAD POR ACCIONES", "kind": "PERSONA JURIDICA COMERCIAL" }
},
"activityStartedOn": "2011-04-12",
"businessEndedOn": null,
"address": {
"source": "sii",
"asOf": "2026-08-05",
"basis": "current_sii_domicile",
"since": "2019-03-01",
"communeCode": "13114", "communeName": "LAS CONDES",
"regionCode": "13", "regionName": "XIII REGION METROPOLITANA"
},
"branches": {
"count": 3,
"communes": [
{ "communeCode": "13101", "communeName": "SANTIAGO", "regionCode": "13" },
{ "communeCode": "13123", "communeName": "PROVIDENCIA", "regionCode": "13" }
]
}
}
Para obter as marcas de uma pessoa (não só a contagem), use
GET /parties/{id}/trademarks ou os filtros de pessoa de GET /trademarks:
# as marcas de uma pessoa, por id
curl -sS "https://api.tarno.cl/parties/1261017/trademarks" -H "X-API-Key: $TARNO_API_KEY"
# por RUT (qualquer papel), na busca de marcas
curl -sS "https://api.tarno.cl/trademarks?taxId=76111111-6" -H "X-API-Key: $TARNO_API_KEY"
Que classe de parte é cada pessoa
Cada pessoa publica kind (natural | legal | unknown) e kindSource (qual sinal o produziu:
tax_id | suffix | manual | name_pattern; o MESMO vocabulário na parte embutida na marca, desde
2026-09-23). name_pattern (desde a mudança de 2026-10-28) é uma dedução calibrada pela forma do nome (palavras de nomes de pessoa
ou palavras societárias como SOCIEDAD ou FUNDACION), aplicada só onde o seu acerto medido contra as fichas
com RUT tem um limite inferior de Wilson ≥ 98 %; um RUT que chegue depois a corrige. unknown é um valor, não um buraco: cerca de um terço do corpus não
leva RUT nem sufixo societário, e o contrato o diz em vez de deduzir. taxId é null para estrangeiros (por
definição, um RUT não existe) e em depósitos antigos onde o INAPI não o publicava. Para o resto dos campos da
pessoa (territory, publishedName, jurisdictionClause, review, …), veja a referência
https://api.tarno.cl/docs.
Relações entre partes
GET /parties/{id}/relations (ferramenta MCP list_party_relations) responde numa chamada «com quem esta parte
compartilha marcas, quem a representa, a quem cedeu, quem se opôs a ela?». Retorna arestas tipadas, cada
uma sustentada por marcas do corpus:
type |
significado | data (firstOn/lastOn) |
coverageFrom |
|---|---|---|---|
co_holder |
as duas são titulares da mesma marca (um titular retirado por mudança de nome, por transferência ou pela cessão do pedido em trâmite não conta como cotitular anterior) | depósito das marcas | null (todo o corpus) |
represents / represented_by |
esta parte representa marcas da outra, ou o inverso | depósito das marcas | null |
assigned_to / assigned_from |
cessão: um titular retirado por uma transferência do INAPI (A07T) frente ao titular da marca |
a do ato | 2011-08-01 |
opposed / opposed_by |
um oponente identificado num ato sobre a marca frente aos seus titulares | a do ato | 2024-04-19 |
Cada aresta traz a outra parte (party: id, name, taxId, kind), trademarkCount, firstOn/lastOn,
até cinco marcas de evidence (as mais recentes) com evidenceTruncated — a lista completa é paginada com
GET /parties/{id}/trademarks ou a busca de marcas —, e label nos três idiomas. Filtra-se por type (lista)
e por relation (current por padrão, former, all — o mesmo vocabulário de /parties/{id}/trademarks);
ordena-se por trademarkCount e pagina-se com cursor.
curl -sS "https://api.tarno.cl/parties/1261017/relations?type=represented_by,opposed_by" \
-H "X-API-Key: $TARNO_API_KEY"
⚠ Como ler:
- «Nunca se opôs» lê-se «não desde 2024-04-19»: as oposições só existem no corpus desde o primeiro Estado
Diario próprio (o de 2024-04-19). E só contam os oponentes identificados: quando o nome impresso não casa com nenhuma parte ou casa
com várias, a contraparte não é inventada; com
opposed_by,meta.unresolvedOpponentMentionsdiz quantas menções ficaram sem identificar. - A contraparte de uma oposição ou de uma cessão é o titular da marca segundo
relation(por padrão, o de hoje), não o da data do ato: o corpus não guarda desde quando cada titular consta. Com cessões encadeadas, o titular de hoje não é necessariamente o cessionário desse ato. - ⛔ São sinais com evidência, nunca veredictos: não há arestas de «mesmo grupo empresarial» nem por semelhança de nome ou de endereço. Uma mesma pessoa duplicada no corpus pode aparecer dividida em duas contrapartes.
Desfechos e mudanças de uma parte
GET /parties/{id}/outcomes≡get_party_outcomes: como terminaram as marcas da parte (como representante por padrão, ou titular), por grupo de status publicado, comn,grantSharesobre as decididas (pendentes fora) e a definição inteira. Não é uma «taxa de sucesso»: veja desfechos.POST /annotations/searchcompartyIdoutaxId(epartyRole,relation,dateFrom…): os atos das marcas da parte — «o que aconteceu esta semana às marcas deste RUT?». Veja anotações por parte.- Na busca de marcas,
partyRolejunto ataxIdlimita o RUT a um papel (RUT).
De um agente de IA
list_parties(q: "carey", limit: 5)
list_parties(taxId: "12.345.678-5")
get_party(id: "1261017")
list_party_trademarks(id: "1261017")
list_party_relations(id: "1261017", type: ["represented_by", "opposed_by"])
A ferramenta MCP retorna o mesmo envelope { results[], … } e é byte-idêntica a GET /parties.
Veja também
- Busca por campos — as pessoas como filtro sobre marcas.
- Primeiros passos — envelope e paginação keyset.
- A referência OpenAPI ao vivo em
https://api.tarno.cl/docs.