Ir para o conteúdo

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" e asOf = 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 (se branches tiver 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 use regionCode.
"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.unresolvedOpponentMentions diz 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, com n, grantShare sobre as decididas (pendentes fora) e a definição inteira. Não é uma «taxa de sucesso»: veja desfechos.
  • POST /annotations/search com partyId ou taxId (e partyRole, 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, partyRole junto a taxId limita 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.