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 esquema completo e sempre atualizado por campo vive na referência OpenAPI interativa em /docs (Scalar). Este guia explica o contrato e aponta para essa referência — não reescreve o esquema. Quando um campo não está documentado aqui, /docs é autoritativo.

Ao longo do guia a URL base é escrita como $TARNO_BASE_URL e a chave como $TARNO_API_KEY, e cada chamada leva o cabeçalho X-API-Key.

GET /v1/personas · scope brands:read · equivalente MCP: search_personas

Até agora as pessoas só podiam ser usadas como filtro de marcas (?titular=, ?rut=) ou como agregado (/v1/insights/by-holder). Este endpoint inverte a pergunta: parte da pessoa e diz quanto do registro é dela.

curl -sS "$TARNO_BASE_URL/v1/personas?q=carey" -H "X-API-Key: $TARNO_API_KEY"

[
  {
    "id": "1261017",
    "nombre": "ESTUDIO CAREY LIMITADA",
    "identificador": "76111111-6",
    "pais": "CL",
    "region": "13",
    "comuna": "13101",
    "marcasTitular": 12,
    "marcasRepresentante": 3480,
    "marcasTotal": 3492,
    "marcasHistoricas": 0,
    "tipo": "juridica",
    "tipoOrigen": "rut",
    "observacion": null,
    "nombrePublicado": "Estudio Carey Limitada",
    "revision": false
  },
  {
    "id": "884213",
    "nombre": "JUAN CAREY SOTO",
    "identificador": null,
    "pais": "CL",
    "region": null,
    "comuna": null,
    "marcasTitular": 1,
    "marcasRepresentante": 0,
    "marcasTotal": 1,
    "marcasHistoricas": 0,
    "tipo": "desconocido",
    "observacion": null,
    "nombrePublicado": "Juan Carey Soto",
    "revision": false
  }
]

Como buscar

Parâmetro	O que faz
`q`	Correspondência parcial e insensível a acentos sobre nome e sobrenome. Mínimo 2 caracteres — `argandona` encontra `Argandoña`.
`rut`	Correspondência exata. Aceita qualquer formato (`17.271.415-3`, `17271415-3`) e o normaliza.
`limit` / `offset`	Paginação. `limit` padrão 25, máximo 100.
`envelope`	`true` adiciona o envelope `{ data, dataAsOf }`.

É obrigatório indicar q ou rut; sem nenhum dos dois a resposta é 400, para que ninguém liste a tabela inteira por acidente.

Os resultados vêm ordenados por volume de marcas, do maior para o menor. Ao buscar um sobrenome comum, o escritório com milhares de marcas aparece antes do homônimo com uma só.

As contagens são de HOJE, e `marcasHistoricas` avisa do que falta

marcasTitular, marcasRepresentante e marcasTotal contam apenas o que a pessoa tem hoje. Se transferiu uma marca, deixa de somá-la.

marcasHistoricas conta o que teve e já não tem. Existe para que essa subtração não seja silenciosa: sem ele veria um número menor e nada que indicasse que há histórico. É 0 para quase toda a gente; um valor diferente de zero é o sinal para perguntar pelo histórico:

# as marcas que esta pessoa TEVE e já não tem
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey&vigencia=historica" -H "X-API-Key: $TARNO_API_KEY"

Que tipo de parte é cada pessoa

Desde 2026-09-08 cada pessoa traz mais cinco campos, os mesmos nos três lugares onde o contrato publica uma pessoa: o detalhe da marca (GET /v1/brands/:nroSolicitud), o relatório de registrabilidade e esta busca. São aditivos: nenhum campo anterior foi removido, renomeado ou re-tipado, e nenhum scope mudou —são lidos sob o mesmo brands:read—, portanto uma integração escrita antes dessa data continua a parsear a resposta sem tocar em nada.

Campo	Tipo	O que diz
`tipo`	`natural` \| `juridica` \| `desconocido`	Que tipo de parte é.
`tipoOrigen`	`rut` \| `sufijo` \| `manual`	Que sinal produziu `tipo`. É omitido —nunca chega como `null`— quando não houve nenhum.
`observacion`	string \| null	A cláusula de jurisdição que a INAPI escreve colada ao nome.
`nombrePublicado`	string \| null	A grafia tal como a INAPI a publicou, frente ao `nombre` canónico.
`revision`	boolean	Há uma ambiguidade conhecida nesta linha.

Os cinco estão declarados opcionais no esquema —é isso que torna a mudança aditiva— e, além disso, tipoOrigen desaparece do objeto quando não há sinal.

desconocido é um valor, não um buraco. Medido em produção a 2026-09-07 sobre 396.287 pessoas: 127.263 têm RUT (79.385 natural, 47.878 jurídica), outras 167.568 têm um sufixo societário no nome, e aproximadamente um terço do corpus não tem nenhum dos dois sinais. Esse terço é desconocido, e dizê-lo é mais honesto do que deduzi-lo. Lê-lo como «provavelmente uma pessoa singular» meteria umas 130.000 partes por classificar dentro de um filtro tipo = 'natural'. Se precisa de certeza, exija tipoOrigen: 'rut' —o corte que o próprio Estado aplica ao emitir o número— em vez de aceitar uma dedução a partir de uma palavra no fim do nome.

tipoOrigen é omitido; não chega como null. Sem sinal a chave desaparece do objeto, que é exatamente quando tipo vale desconocido (o segundo elemento do exemplo acima não tem tipoOrigen). Um if (p.tipoOrigen === null) nunca se cumpre: a verificação correta é p.tipoOrigen === undefined ou !("tipoOrigen" in p).

nombre é o campo com que se BUSCA; nombrePublicado é o campo que se MOSTRA, ou que se COMPARA com um documento de origem. nombre é a forma canónica —MAIÚSCULAS com acentos— e é a que o motor indexa; nombrePublicado conserva a grafia da fonte para que qualquer valor possa ser confrontado com a INAPI. Comparar contra nombrePublicado reintroduz exatamente o ruído de maiúsculas e acentos que a forma canónica existe para remover.

observacion é prosa da INAPI, não uma nota nossa. É a cláusula de jurisdição retirada de dentro do nome: «X, SOCIEDAD ORGANIZADA BAJO LAS LEYES DEL ESTADO DE DELAWARE» é guardada como nombre: 'X' mais esta observação. É publicada literal, erros de grafia incluídos: 1.472 pessoas levam-na em 681 grafias distintas da mesma cláusula (SOCIEDD ORGANIZADA…, SOC. ORG. BAJO LAS LEYES…). Não a parseie como vocabulário controlado; é prosa.

revision avisa, não desqualifica. Significa que o próprio corpus marcou a linha para que uma pessoa a veja —um RUT que contradiz o sufixo do nome, uma cláusula que consumiu o nome inteiro—, não que o dado seja mau. Quem mostra a parte a um advogado talvez queira dizê-lo; quem conta marcas pode ignorá-lo. O motivo não é publicado: é vocabulário de operador e cresce a cada passagem, por isso o contrato responde só à pergunta que o consumidor tem, «posso confiar nesta linha às cegas?».

O corpus de pessoas foi reescrito a 2026-09-08

Os nomes são canónicos desde essa data: 396.444 pessoas foram reescritas para a forma canónica e cerca de 240.000 mudaram de grafia. Se comparar valores em cache de antes com os que a API devolve hoje, verá diferenças de maiúsculas e acentos que não são mudanças de dado. Além disso:

As cláusulas de jurisdição já não estão dentro de nombre: vivem em observacion, e o nome ao qual estavam coladas é agora apenas o nome.
Agrupar ou de-duplicar pessoas do seu lado por nombre contava a mais: a mesma parte que lia Estudio Carey Limitada numa marca e ESTUDIO CAREY LIMITADA noutra agora lê igual nas duas.
Foram fundidos 179 grupos de duplicados. Nenhuma marca mudou de dono, portanto o total de uma parte só pode subir ao absorver a sua gémea, nunca descer.

Duas coisas que vale entender

Devolve contagens, não marcas. Um escritório grande tem milhares: embuti-las tornaria a resposta ilimitada e duplicaria o motor de busca que /v1/brands já é. Para obter as marcas de uma pessoa, use os valores devolvidos aqui:

# todas as marcas em que esta parte aparece, por RUT (qualquer papel)
curl -sS "$TARNO_BASE_URL/v1/brands?rut=76111111-6" -H "X-API-Key: $TARNO_API_KEY"

# apenas onde é titular, por nome
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey" -H "X-API-Key: $TARNO_API_KEY"

# o que teve e já não tem (`vigencia=todas` abrange ambas)
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey&vigencia=historica" -H "X-API-Key: $TARNO_API_KEY"

Essas chamadas devolvem a titularidade atual por omissão: quem transferiu uma marca deixa de aparecer nela. vigencia muda essa pergunta — ver busca por campos.

identificador é null com frequência, e isso não é falha de dados. O RUT é um identificador chileno, portanto:

um titular estrangeiro nunca terá um — não existe;
em pedidos anteriores a 2023 o INAPI não o publicava (cobertura de 17-26% entre 2017 e 2022, contra ~75% a partir de 2024).

Se a sua integração cruza por RUT, trate o null como "indisponível", nunca como "não corresponde".

A partir de um agente de IA

search_personas(q: "carey", limit: 5)
search_personas(rut: "17.271.415-3")

A ferramenta MCP devolve sempre o envelope { data, dataAsOf } e é byte-idêntica a GET /v1/personas?envelope=true.