Ir para o conteúdo

Base documental (diretrizes e leis)

Este guia cobre a base documental do Tarno: o que o INAPI, a BCN e o SII publicam sobre o registo de marcas no Chile, guardado literalmente e com versões e lido pelo mesmo contrato que as marcas (REST ≡ MCP). Tem a sua própria permissão, legal:read (veja Permissão).

O esquema completo e sempre atualizado por campo vive na referência OpenAPI interativa em https://api.tarno.cl/docs (Scalar). Este guia explica como estas leituras são pedidas — não reformula o esquema.

Ao longo do guia a URL base é https://api.tarno.cl e cada chamada leva o cabeçalho X-API-Key.

O que é a base documental

Três fontes (o SII com duas execuções), cada uma com a sua execução:

fonte o que guarda execução
INAPI as Diretrizes de marcas (capítulo a capítulo, com a sua página), as circulares, o Sistema de Madrid e a tabela de taxas inapi_documents (semanal)
BCN LeyChile o texto das leis do catálogo de normas —a Lei 19.039, o seu Regulamento…— em todas as suas versões, artigo → letra → inciso, com as notas de modificação bcn_statutes (semanal)
SII os indicadores UTM, UTA, IPC, UF e dólar observado sii_indicators (diária)
SII (nómina) a razão social, o subtipo, o início de atividades e o domicílio vigente (comuna e região) das pessoas jurídicas com RUT chileno; lê-se no bloco sii da parte (Partes) sii_legal_entities (diária, no fim da cadeia de sincronização)

⛔ O que se guarda é o que a fonte escreveu: sem resumos, sem paráfrases e sem «relevância». Nada é apagado: uma versão nova fecha a anterior e conserva-a, por isso é sempre possível ler o que um texto dizia numa data passada.

Hoje leem-se as Diretrizes, as circulares e Madrid —a lista, o Sumário de cada documento e qualquer secção, literal— (abaixo), o texto de um artigo numa data (abaixo), a pesquisa por texto e por semelhança nos dois (abaixo), a tabela de taxas com os pesos calculados ao ler (abaixo), os indicadores do SII (abaixo) e o registo de alterações de versão (abaixo). E, no detalhe de uma anotação, a citação explicada: o texto de cada norma citada tal como vigorava nesse dia e os capítulos das Diretrizes que a tratam (abaixo).

Permissão: legal:read

Toda leitura da base documental exige legal:read, e essa permissão é concedida explicitamente:

  • uma chave irrestrita (com scopes vazio) não a tem;
  • a chave de teste também não;
  • brands:read e reports:read não a incluem.

Sem ela, a chamada responde 403 forbidden e a mensagem nomeia legal:read. Peça-a ao seu operador.

⚠ Para quem concede chaves: uma lista de scopes não vazia é uma lista fechada. Passar uma chave de [] para ["legal:read"] remove todas as outras leituras: é preciso escrever a lista completa (por exemplo ["brands:read", "insights:read", "watch:read", "legal:read"]). Veja autenticação.

A data do dado, por fonte

Cada resposta diz a data da sua fonte em dataAsOf (e no cabeçalho Iris-Data-As-Of quando a resposta é um objeto): a última execução correta de inapi_documents, bcn_statutes ou sii_indicators, conforme o que se lê. ⛔ Nunca é a data do corpus de marcas: uma execução de marcas desta manhã não diz nada sobre quando a Lei 19.039 foi lida, e vice-versa. dataAsOf: null significa «não há nenhuma execução correta dessa fonte» — não sabemos, o que é diferente de «hoje».

Diretrizes, circulares e Madrid

Tudo o que o INAPI publica na base documental: os 50 capítulos das Diretrizes de marcas, as circulares, a página e o manual do Sistema de Madrid e as publicações de taxas. Três leituras, todas com a permissão legal:read:

operação REST MCP
a lista de documentos, cada um com a sua versão vigente GET /guidance/documents list_guidance_documents
um documento com o seu Sumário (a árvore de secções, sem corpos) e o histórico das suas versões GET /guidance/documents/{code} get_guidance_document
uma secção literal, com a sua página, a sua versão e as normas que cita GET /guidance/documents/{code}/section get_guidance_section

Como se cita uma secção

  • A citação estável é (code, version, path): o código do documento (guideline-35 = capítulo 35 das Diretrizes), o número da versão (version.seq) e o path da secção no próprio Sumário do INAPI (III.D, III.D.▪1.§7, III.D.sidebar1, intro). Por exemplo: «Diretrizes, cap. 35, versão 2, III.D.▪1.§7 (p. 18)». ⛔ Nunca um id de linha: reconstroem-se quando a extração da mesma versão melhora, e não os publicamos.
  • A citação de um advogado é code + paragraph: «cap. 35 § 7» pede-se com paragraph=7. Se esse número se repetir dentro da versão (o INAPI por vezes numera duas vezes), a resposta é 409 ambiguous_selector com os path candidatos; volta-se a pedir por path.
  • Sem version lê-se a versão vigente; com version, uma anterior (o INAPI não conserva as versões antigas no seu site; nós sim). O histórico está em get_guidance_document → versions.

O que significam partial, image_only e ocr

Cada versão declara em extractionStatus como pôde ser lida:

valor significado
extracted o texto e o Sumário leram-se limpos
partial o texto é literal, mas a árvore está incompleta: uma entrada do Sumário que o INAPI imprime não aparece no corpo, ou um título rotulado do corpo não está no Sumário (e o seu texto fica dentro da secção de cima). É uma inconsistência da fonte, que se declara. Um título apenas redigido de outra forma no Sumário e no corpo já não conta como partial: a secção está lá, com o título do corpo
image_only o INAPI publicou o documento como imagens: não há texto. get_guidance_document responde 200 com outline: [], e pedir uma secção é 422 out_of_coverage com extractionStatus: "image_only"
ocr o INAPI publicou o documento como imagens e o seu texto foi lido por máquina (OCR). Tem uma secção por página (ocr.p1, …) e aparece nas pesquisas, mas não é literal: alguma palavra pode estar mal lida e, num diagrama (o cap. 21, o fluxo de tramitação), os rótulos vêm pela ordem da página, não pela do procedimento, e as setas não são texto. Cita-se o PDF, nunca este texto. Os resultados de search_guidance levam-no em version.extractionStatus
pending · failed ainda não lido / não foi possível ler

⛔ Um capítulo partial ou image_only nunca se preenche com texto que não é da fonte; o texto de um ocr é da fonte, mas lido por máquina, e assim se declara.

Parâmetros

operação parâmetro o que é
lista kind opcional, um ou vários de guideline, circular, manual, web_page, fee_schedule (kind=guideline,circular)
lista q opcional, palavras do título sem acentos nem maiúsculas (2–100 caracteres)
documento, secção code o código do documento (minúsculas, dígitos e hífenes: guideline-35, madrid-page)
documento, secção version opcional, o número da versão (seq); por omissão, a vigente
secção path ou paragraph um e só um: o path do Sumário (até 200 caracteres, codificado no URL) ou o número do parágrafo (1–9999)

A lista vem ordenada por tipo, número de capítulo (guideline-2 antes de guideline-10) e código, com total exato; um documento que o INAPI deixou de ligar continua nela com missingSince.

Exemplo: o § 7 do capítulo 35, na versão vigente.

curl -sS "https://api.tarno.cl/guidance/documents/guideline-35/section?paragraph=7" \
  -H "X-API-Key: $TARNO_API_KEY"
# ou pelo seu path, codificado: ?path=III.D.%E2%96%AA1.%C2%A77
{ "name": "get_guidance_section",
  "arguments": { "code": "guideline-35", "paragraph": 7 } }

A resposta traz document, version (seq, extractionStatus…), path, kind, heading, paragraphNumber, pageFrom/pageTo, o body literal, children (os filhos diretos, para descer pelo Sumário) e citations: cada norma citada com legalNormId (que se lê com get_legal_norm_article), citedNorm (o número da lei, também se estiver fora do catálogo) e lawNamed: false quando o texto cita um «art. 19» sem dizer de que lei. dataAsOf é a última leitura correta do INAPI (inapi_documents).

Erros

estado code quando
400 validation_error um parâmetro desconhecido; path e paragraph ao mesmo tempo, ou nenhum; kind=statute (é do BCN); q de um carácter; um code com maiúsculas ou /
403 forbidden a chave não tem legal:read
404 not_found o documento, a versão ou a secção não existem
409 ambiguous_selector o número do parágrafo repete-se na versão; candidates traz os path
422 out_of_coverage a versão não tem texto (image_only); leva coverage: null e o seu extractionStatus

O texto de um artigo numa data

GET /legal-norms/{id}/articles/{article} ≡ get_legal_norm_article — permissão legal:read.

O artigo literal, tal como a BCN o publica, na versão que vigorava para essa norma em asOf, com as suas letras, incisos e notas de modificação.

parâmetro o que é
id o id da norma em GET /legal-norms ≡ list_legal_norms (texto opaco)
article a chave do artigo: 20, 17 bis a, 1, único — a mesma que as citações das anotações trazem. Maiúsculas, um «Artículo»/«Art.» à frente e º são ignorados. Em REST, com os espaços codificados (17%20bis%20a)
letter opcional, uma letra (a–z, ñ): só essa letra
subsection opcional, um inciso (1–99): da letra se houver letter, do artigo se não
asOf opcional, YYYY-MM-DD: a data cujo texto quer. Por padrão, hoje no Chile
transitional opcional, true para o artigo transitório com essa chave (uma lei pode ter um art. 1 permanente e um art. 1 transitório). Por padrão false. Só true ou false: outro valor ⇒ 400 validation_error

Exemplo: o art. 20 letra h da Lei 19.039 tal como vigorava em 2021-03-15 (1 é um id ilustrativo; obtenha-o de GET /legal-norms).

curl -sS "https://api.tarno.cl/legal-norms/1/articles/20?letter=h&asOf=2021-03-15" \
  -H "X-API-Key: $TARNO_API_KEY"
{ "name": "get_legal_norm_article",
  "arguments": { "id": "1", "article": "20", "letter": "h", "asOf": "2021-03-15" } }

Que texto vigora numa data

Uma norma do catálogo pode ter vários textos da BCN ao longo do tempo. A Lei 19.039 tem três:

desde até texto
— 2006-06-19 a Lei 19.039 original
2006-06-20 2022-08-05 o DFL 3 (texto consolidado)
2022-08-06 — o DFL 4 (texto consolidado vigente)

E cada texto tem as suas próprias vigências na BCN. A resposta diz tudo em text: documentCode (que texto), validFrom/validTo (a sua vigência segundo a BCN), appliesFrom/appliesTo (a janela em que é o texto desta norma) e lastSeenAt (a última vez que a BCN nos serviu esse conteúdo). Uma data de 2015 lê o DFL 3 mesmo que a BCN dê ao DFL 3 uma vigência aberta: manda a janela da norma.

Artigos não divididos e transitórios

  • split/splitStatus: split = as letras foram encontradas e verificadas; unsplit = não puderam ser cortadas com segurança (por exemplo, uma lista de letras que recomeça a meio do artigo) e o artigo é servido inteiro; no_letters = o artigo não tem letras.
  • Se pedir uma letter de um artigo unsplit, a resposta é 200 com o artigo inteiro, letters: [] e selection.status: "article_not_split". ⛔ Nunca um corte inventado.
  • transitional: true lê o artigo transitório dessa chave; sem ele, o permanente.

Erros

Todos com o corpo RFC 9457 (application/problem+json), iguais em REST e em MCP:

estado code quando
400 validation_error um parâmetro desconhecido, uma letra maiúscula, uma data impossível (2026-02-31), subsection fora de 1–99, um article com / ou com mais de 40 caracteres
403 forbidden a chave não tem legal:read
404 not_found a norma não existe; ou o artigo, a letra ou o inciso não estão no texto dessa data
409 ambiguous_selector o texto tem dois artigos com a mesma chave; candidates traz os seus nomes. Não escolhemos um em silêncio
422 out_of_coverage não temos texto para responder: com coverage: null, a norma está no catálogo mas o seu texto não está carregado; com coverage {from, through}, a data cai fora das janelas em que o temos (null num extremo = aberto)

Forma do corpo (valores ilustrativos):

{ "type": "https://api.tarno.cl/problems/out_of_coverage", "title": "Business rule not satisfied",
  "status": 422, "code": "out_of_coverage", "requestId": "...",
  "detail": "we have no text of legal norm 1 that applies on 1990-01-01",
  "coverage": { "from": "2006-06-20", "through": null } }

As respostas 200 levam cache de catálogo (Cache-Control: public, max-age=3600, stale-while-revalidate=86400 e Vary: X-API-Key); os erros, no-store.

Duas pesquisas, ambas com a permissão legal:read, iguais em REST e em MCP:

o que pesquisa REST MCP
nas secções vigentes dos documentos do INAPI (Diretrizes, circulares, Madrid, taxas) POST /guidance/search search_guidance
artigos de lei, no texto que vigorava numa data ou em todas as vigências POST /legal-norms/search search_statutes

Servem para encontrar «o que diz o INAPI sobre a coexistência» ou «que artigo falava da renovação antes de 2022» sem saber o número da secção nem do artigo. Cada resultado traz a referência para o ler inteiro (get_guidance_section / get_legal_norm_article) e um excerto literal.

Os três modos

mode o que faz
hybrid (por omissão) dois canais em paralelo —texto (espanhol, sem acentos nem maiúsculas) e semelhança de significado (busca semântica)— fundidos por posição recíproca (RRF)
text só palavras. Aceita a sintaxe de motor de busca: "frase exata", or, -palavra
semantic só significado

Cada resultado diz em matchedBy por que canal saiu (text, semantic ou ambos). Não publicamos pontuações: a ordem é a resposta.

⭐ Degradação declarada. Se o canal de significado não puder correr (o serviço de vetores está em baixo ou lento, ou a pesquisa vetorial esgotou o tempo), hybrid devolve o do texto e di-lo em meta.channels:

"meta": { "dataAsOf": "2026-09-27T05:00:00.000Z", "mode": "hybrid",
          "channels": { "text": "ran", "semantic": "unavailable" } }

Em mode: "semantic" não há com que continuar: a resposta é 503 service_unavailable. ⛔ Nunca uma lista vazia que diga «não há nada» quando não se pesquisou.

Nas leis: asOf ou allVersions

  • Por omissão pesquisa-se no texto que vigora hoje no Chile, com a mesma regra que get_legal_norm_article (Que texto vigora numa data): pesquisar e ler dão o mesmo texto.
  • asOf: "2015-03-01" pesquisa no texto que vigorava nesse dia.
  • allVersions: true pesquisa em todas as vigências de todos os textos —para ler contra que texto se examinou um pedido antigo—. ⭐ O mesmo texto de um artigo repetido em várias vigências (o DFL 3 tem cinco) sai uma vez, com todas em validity; um texto que mudou é outro resultado.
  • asOf e allVersions juntos são um 400.
  • norm (o id do catálogo) limita a uma norma. Sem texto carregado —ou sem texto para essa data— é 422 out_of_coverage com a sua coverage, como na leitura do artigo; inexistente, 404.

Cada resultado de lei traz norm (null se o texto não está ligado a exatamente uma norma do catálogo), document (o texto da BCN: code, title, bcnNormaId), article, articleLabel, transitional, headingPath, excerpt e validity ([{validFrom, validTo}], da mais antiga à mais recente).

Parâmetros

parâmetro pesquisa o que é
q ambas o que pesquisa, 2–200 caracteres
mode ambas hybrid (omissão), text ou semantic
kind Diretrizes um ou vários de guideline, circular, manual, web_page, fee_schedule
document Diretrizes só esse documento (guideline-35)
norm leis só essa norma do catálogo (o seu id)
asOf leis YYYY-MM-DD; por omissão, hoje no Chile
allVersions leis true para todas as vigências
limit, cursor ambas 1–50 (omissão 20); cursor é o next da página anterior, tal como vem

Exemplo: que artigos falavam da renovação, em qualquer vigência.

curl -sS -X POST "https://api.tarno.cl/legal-norms/search" \
  -H "X-API-Key: $TARNO_API_KEY" -H "Content-Type: application/json" \
  -d '{"q": "renovacion del registro", "allVersions": true}'
{ "name": "search_statutes",
  "arguments": { "q": "renovacion del registro", "allVersions": true } }

E nas Diretrizes vigentes:

{ "name": "search_guidance",
  "arguments": { "q": "coexistencia de marcas", "kind": ["guideline"] } }

Erros

estado code quando
400 validation_error q sem palavras pesquisáveis (só palavras vazias: «de la») ou que só exclui (-marca); q com menos de 2 ou mais de 200 caracteres; um parâmetro desconhecido; asOf junto com allVersions
403 forbidden a chave não tem legal:read
404 not_found norm não existe
422 out_of_coverage norm sem texto carregado (coverage: null) ou sem texto para asOf (coverage {from, through})
503 service_unavailable mode: "semantic" e o canal de significado não pôde correr

Uma pesquisa não leva cache de catálogo. meta.dataAsOf é a data da sua fonte: inapi_documents para as Diretrizes, bcn_statutes para as leis.

Taxas

A tabela de taxas de marcas do INAPI, em UTM e literal, com o montante em pesos calculado ao ler:

REST MCP
GET /fee-schedule get_fee_schedule

A tabela é a do capítulo 13 das Diretrizes de marcas (2026): as cinco taxas (ao apresentar, ao ser aceite para registo, ao renovar, anotações marginais e recurso) e os seis meses da sobretaxa por renovação tardia. As outras duas publicações de taxas do INAPI (a de 2022 e o anexo antigo) não se servem como tabela: só se comparam com o cap. 13, e o que difere publica-se na nota da sobretaxa.

Como se calcula amountClp

  • amountUtm é literal do INAPI (7.2, nunca arredondado).
  • amountClp é um valor DERIVADO ao ler: amountUtm × utm.value, exato e sem arredondar (a regra de arredondamento do INAPI não é nossa). Nenhum montante em pesos se guarda, por isso nenhum caduca.
  • utmMonth (YYYY-MM) escolhe o mês da UTM; por omissão, o mês em curso no Chile.
  • utm diz que UTM se usou:
utm.basis significa
requested_month a UTM do próprio utmMonth
latest_published a desse mês ainda não está publicada: usou-se a última publicada antes (utm.month diz qual)
  • Sem nenhuma UTM em ou antes de utmMonth (a série do SII começa em 2013), utm é null e todos os amountClp são null: a taxa em UTM continua lá; o que falta é a conversão.
  • unit: per_class paga-se por cada classe de Nice; fixed, uma vez por pedido.

Ao citar um montante em pesos, diga o mês e a fonte: «6 UTM por classe; 430.326 pesos com a UTM de setembro de 2026».

⭐ As taxas de um trâmite concreto (pedido + registro, ou uma renovação com o seu vencimento publicado) são calculadas por POST /fee-schedule/calculate ≡ calculate_fees, com brands:read: veja custos oficiais.

A nota da sobretaxa

A tabela da sobretaxa das Directrices 2026 (cap. 13; cap. 23 §42) é a regra aplicada: o 1.º mês em 6 UTM, igual à renovação no prazo, até 12 UTM no 6.º. A nota «(*)» do cap. 13 diz que a renovação aumenta 20 % ao mês depois da expiração, e outras publicações de taxas do INAPI redigem-na de outra forma. Essa discrepância é publicada como nota informativa e não bloqueia nenhum cálculo (o campo mantém o nome, surchargeDoubt):

  • surchargeDoubt.description diz qual é a regra e em que diferem as notas;
  • surchargeDoubt.notes[] traz as notas literais: primeiro a do cap. 13 e depois as das outras publicações do INAPI cuja nota difere (só diferenças abertas), cada uma com o seu documentCode e o seu documentTitle;
  • as linhas a que a nota se refere (a renovação e os meses 2.º a 6.º; o 1.º mês foi confirmado pelo INAPI por escrito em 2026-11-04) levam hasDoubt: true.
curl -sS "https://api.tarno.cl/fee-schedule?utmMonth=2026-09" -H "X-API-Key: $TARNO_API_KEY"
{ "name": "get_fee_schedule", "arguments": { "utmMonth": "2026-09" } }
{ "utm": { "month": "2026-09", "value": 71721, "basis": "requested_month" },
  "items": [ { "itemKey": "renewal_per_class", "amountUtm": 6, "unit": "per_class",
               "amountClp": 430326, "hasDoubt": true },
             { "itemKey": "renewal_surcharge_month_2", "amountUtm": 7.2, "surchargeMonth": 2,
               "amountClp": 516391.2, "hasDoubt": true } ] }
estado code quando
400 validation_error utmMonth não é um mês real (2026-13, 2026-9) ou um parâmetro desconhecido
403 forbidden a chave não tem legal:read
422 out_of_coverage não há tabela de taxas carregada (coverage: null)

dataAsOf é a data da fonte de documentos do INAPI (inapi_documents). Leva cache de catálogo.

Indicadores

Os indicadores que o SII publica, por código e intervalo de datas:

REST MCP
GET /economic-indicators list_economic_indicators
code o que é um valor por
UTM unidade tributária mensal mês (datado no dia 1)
UTA unidade tributária anual mês (datado no dia 1)
IPC índice de preços no consumidor, em pontos (unit: "index_points") mês (datado no dia 1)
UF unidad de fomento — publicada antecipadamente dia
USD_OBSERVED dólar observado — até ao dia útil bancário anterior dia útil bancário
  • code é obrigatório; from/to (YYYY-MM-DD, inclusivos) delimitam o intervalo; limit 1–366 (por omissão 31) e next paginam. total é exato.
  • meta.coverage {code, from, through} diz desde e até quando temos esse indicador. Um intervalo que a ultrapassa em parte devolve o que há; um inteiramente fora é um 422 out_of_coverage com a cobertura — nunca um 200 vazio que diria «não houve valores».
  • ⚠ O IPC mistura bases. O SII rebaseou-o: os valores de 2013 dizem «base anual diciembre 2013=100» e os de 2026 «base anual 2023=100». Cada linha traz a sua baseNote literal, e pontos de bases diferentes não são comparáveis: não se subtraem nem se encadeiam num só número.
curl -sS "https://api.tarno.cl/economic-indicators?code=UF&from=2026-09-01&to=2026-09-30" \
  -H "X-API-Key: $TARNO_API_KEY"
{ "name": "list_economic_indicators",
  "arguments": { "code": "IPC", "from": "2025-01-01" } }
estado code quando
400 validation_error sem code ou com um desconhecido; uma data impossível; from posterior a to
403 forbidden a chave não tem legal:read
422 out_of_coverage o intervalo cai inteiro fora da cobertura (coverage {code, from, through}), ou não há nenhum valor do código (coverage: null)

meta.dataAsOf é a data da fonte do SII (sii_indicators).

Alterações de versão

O registo de que secções mudaram de cada vez que o INAPI publicou outra versão de um documento, ou a BCN outra vigência de um texto legal, e quando o detetámos:

REST MCP
GET /guidance/changes list_guidance_changes

Cada alteração traz o document (code, kind, publisher, title), as duas versões (fromVersion, toVersion: seq e versionTag), detectedAt, effectiveDate, titleChanged, as contagens (counts {added, removed, modified}) e as secções que mudaram (sections [{path, change, headingChanged}]).

  • detectedAt é quando nós a vimos (a corrida que descarregou a versão nova), não quando o editor a fez.
  • effectiveDate só existe para a BCN: a data em que o texto novo entrou em vigor, literal como a BCN a dá (há uma com 2222-02-02, um marcador da BCN, guardada tal qual). O INAPI não publica nenhuma: null.
  • No máximo 100 secções por alteração: sectionsTruncated: true diz que há mais, e counts traz sempre os totais. Uma secção lê-se com get_guidance_section (a da versão anterior, com version).
  • Filtros: document, publisher (inapi ou bcn) e from/to — o dia de deteção na hora do Chile. A mais recente primeiro; limit 1–100 (por omissão 20) e next.
  • ⭐ meta.dataAsOf: com publisher (ou com um document), a data da sua fonte; sem ele, a mais antiga de inapi_documents e bcn_statutes — o registo misturado só está completo até aí.
{ "name": "list_guidance_changes",
  "arguments": { "publisher": "inapi", "from": "2026-09-01" } }
estado code quando
400 validation_error from posterior a to; uma data impossível; publisher desconhecido; limit fora de 1–100
403 forbidden a chave não tem legal:read

A citação explicada

Uma resolução do INAPI diz «recusada pelo art. 20 letra h) da Lei 19.039». Com expand=citations, o detalhe dessa anotação traz, para cada norma que cita, o texto literal do artigo ou da letra que vigorava na data da anotação e os sinais das Diretrizes: os documentos do INAPI que citam esse mesmo artigo/letra, com a sua contagem.

REST MCP
GET /annotations/{id}?expand=citations get_annotation com expand: ["citations"]

⛔ Exige legal:read ALÉM de brands:read. Sem ela, 403 forbidden que nomeia legal:read — e o pedido não consome quota. Sem expand, a anotação é exatamente a de sempre, com brands:read: a chave citations não existe.

⛔ Só no detalhe. As listas (GET /trademarks/{n}/annotations, POST /annotations/search, list_trademark_annotations, search_annotations) e GET /trademarks/{n}?expand= rejeitam expand=citations com 400: cem anotações com os seus textos seriam uma resposta enorme.

Cada elemento de citations[] (50 no máximo, pela ordem em que a resolução as cita; citationsTruncated: true se houver mais):

  • o que a resolução cita: normKind (ley | reglamento), legalNormId (o catálogo de GET /legal-norms), citedNorm (19039), name, article, letter, subsection e span (as palavras literais);
  • text — o texto desse dia, com a mesma regra que get_legal_norm_article: asOf (a data usada), chosenBy (o que a escolheu: act_date, ou uma das duas exceções abaixo), documentCode e bcnNormaId (o texto da BCN), validFrom/validTo (a vigência dessa versão), articleLabel, split, scope (letter: body é a letra citada; article: body é o artigo inteiro) e body, literal;
  • textStatus — porque há ou não há texto;
  • guidance — os sinais (abaixo).
textStatus o que significa text
found o artigo (ou a sua letra) que vigorava nesse dia sim
letter_not_split o artigo não está dividido em letras (nunca se inventa um corte) o artigo inteiro, scope: "article"
law_not_identified a resolução cita um artigo sem nomear nenhuma lei null, e guidance: []
no_text_loaded a norma está no catálogo, mas o seu texto não está carregado null
no_date a anotação não tem data null
out_of_window nenhum texto dessa norma vigorava nessa data null
article_not_found o texto desse dia não tem esse artigo null
ambiguous_article o texto desse dia tem dois artigos permanentes com essa chave (get_legal_norm_article responde 409) null
letter_not_found o artigo não tem essa letra null

⚠ A data usada é a da anotação, tomada como a da resolução. Perto de uma alteração do texto (2022-05-09, 2022-08-06) uma anotação publicada dias depois da resolução leria o texto seguinte: por isso text.asOf diz que data se usou. E um artigo transitório não se distingue na citação: lê-se o permanente com esse número.

⚠ Duas exceções, ambas do Regulamento da Lei 19.039 e ambas pelo modelo que o INAPI copia.

1 · O art. 9 depois de 2022-05-09 (chosenBy: "former_regulation_template"). Em 2022-05-09 o Decreto 82 revogou o Decreto 236, e o seu art. 9 mudou de matéria: no DS 236 são as menções do pedido de marca («Toda solicitud para el registro de marcas comerciales contendrá…», letras a-d); no DS 82, as do pedido de patente. O INAPI continuou a citar nas suas resoluções de marcas o modelo do DS 236. Quando a prosa da anotação traz a assinatura textual desse modelo —o cabeçalho «registro de marcas comerciales contendrá» para qualquer letra; «especificación clara de la marca» ou «transliteración» para a b; a «Resolución Exenta N° 391» para a c— a citação lê-se contra o DS 236 no último dia da sua vigência, e text.asOf é 2022-05-08. Sem assinatura, o art. 9 segue a data como qualquer outra citação. Medido em produção em 2026-09-29: 254 citações (230 com letra, 24 sem).

2 · O art. 6 e o 7 antes de 2022-05-09 (chosenBy: "later_regulation_template"). A simétrica: desde dezembro de 2017 o INAPI citou nas suas resoluções de marcas «art. 6 letra a/b/c/d» e «art. 7 letra b/c» do Regulamento com a numeração e a redação do DS 82, que entrou em vigor em 2022-05-09; os arts. 6 e 7 do DS 236, vigente nessa data, não têm letras, pelo que a regra da data não encontrava a letra (letter_not_found). Quando a citação é anterior a 2022-05-09 e a prosa traz a assinatura textual da sua letra —art. 6: a) «marcas comerciales contendrá»; b) «especificación clara» ou «especificar con claridad»; c) «Res. Ex. N° 391 de 2017»; d) «idioma distinto al/del español»; art. 7: b) «nombre propio» ou «nombre de una persona»; c) «acompañe poder» ou «artículos 15 y 22»— a citação lê-se contra o DS 82 no seu primeiro dia, e text.asOf é 2022-05-09, posterior ao ato: ⚠ esse texto ainda não vigorava na data da resolução, e chosenBy di-lo para que se possa advertir. O art. 7 a) e d) (a fórmula «letras a) y d)… nuevos ejemplares», que não casa com o art. 7 d) do DS 82) e qualquer citação sem assinatura seguem a data. Medido em produção em 2026-09-29: 15.353 citações (art. 6: 9.679; art. 7: 5.674), 2017-12-07 → 2022-05-05.

Sinais, não veredicto

guidance lista os documentos vigentes do INAPI (Diretrizes, circulares, manual, página) que citam esse artigo e essa letra, os que mais o citam primeiro (5 no máximo), cada um com:

  • citingCount — quantas citações desse artigo/letra tem a sua versão vigente, e unnamedCount — quantas não nomeiam a lei;
  • até 3 secções (path, heading, paragraphNumber, pageFrom, lawNamed): parágrafos numerados primeiro, depois o mais curto. Leem-se com get_guidance_section (code + path).

⛔ Não é «a» secção que interpreta a citação. É um sinal de onde o INAPI fala desse artigo, com a sua contagem; que secção se aplica ao caso decide-o quem lê. (Uma heurística que escolhia uma escolheu em produção o capítulo 43 em vez do 42.)

⭐ As citações sem lei. Nas Diretrizes de marcas, um «art. 20 letra h)» sem mais é a Lei 19.039 (a sua lei por defeito): essas citações contam só para citações da Lei 19.039, e a sua secção di-lo com lawNamed: false. Para o Regulamento ou qualquer outra lei não se aplica.

curl -H "X-API-Key: $TARNO_API_KEY" \
  "https://api.tarno.cl/annotations/11397483?expand=citations"
{ "name": "get_annotation",
  "arguments": { "id": "11397483", "expand": ["citations"] } }
estado code quando
400 validation_error expand diferente de citations; expand numa lista
403 forbidden com expand=citations, a chave não tem legal:read (ou não tem brands:read)
404 not_found a anotação não existe

Anotações por parte e por status atual

POST /annotations/search ≡ search_annotations (scope brands:read) aceita, desde 2026-09-28, mais cinco filtros. Sem eles a resposta é byte a byte a de sempre.

campo o que filtra
partyId os atos das marcas dessa parte (o seu id de /parties); um inexistente ⇒ 404
taxId o mesmo por RUT, com ou sem pontos e hífen (no máximo um de partyId/taxId); sem forma de RUT ⇒ 400 invalid_rut
partyRole holder ou representative (ausente: os dois); exige parte
relation current (padrão), former (relação retirada) ou all; exige parte
trademarkStatus lista de status: só atos de marcas cujo status publicado hoje é um deles — o mesmo significado que status da busca de marcas, nunca o valor bruto do INAPI
# «O que aconteceu este mês às marcas deste RUT?»
curl -s -X POST "$TARNO_BASE_URL/annotations/search" -H "X-API-Key: $TARNO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"taxId": "76.086.428-5", "dateFrom": "2026-09-01"}'

A parte resolve-se primeiro aos números das suas marcas (até 5.000; uma parte maior segue outra forma da mesma consulta), por isso o filtro não percorre o corpus por data. Medido em produção em 2026-09-28: todos os caminhos abaixo de 2 s. A ordem (fecha, id) e o cursor são os de sempre. O lote de anotações por lista de marcas e o filtro por data de deteção: mais abaixo.

O prazo que o INAPI imprime no nome do ato: inapiTermLabel

Desde 2026-09-29, cada anotação do recurso —POST /annotations/search ≡ search_annotations, GET /trademarks/{n}/annotations, GET /annotations/{id} ≡ get_annotation e o boletim do dia— traz o campo inapiTermLabel. Alguns atos do INAPI trazem no nome o prazo que a própria resolução fixa («Fondo - Res. Observaciones Escrito (30 días)»); o campo cita esse texto:

{
  "section": "M11",
  "act": "661B",
  "actName": "Fondo - Res. Observaciones Escrito (30 días)",
  "inapiTermLabel": {
    "basis": "inapi_label",
    "text": "30 días",
    "code": "661B",
    "quotedFrom": "actName"
  }
}
  • Só uma lista fechada de 14 códigos: as observações de escrito administrativas e de forma, mérito e registro (661, 661B, 661D, 813, 813A, 813B, 813D, 931, 931B, 931D) e as dos contenciosos de oposição (738, 964, 925, 926). Em qualquer outro ato, null; e também null se o nome do INAPI não traz o prazo entre parênteses.
  • Primeiro o ato: se a anotação tem act, a citação sai de actName (quotedFrom: "actName"); se não, de sectionName.
  • Fora, de propósito: a apelação (W146, W148), o pagamento (W570), W015/W023 e 664B.

⛔ Um rótulo não é um prazo. inapiTermLabel é texto do INAPI citado: não traz data, não é um marco e nunca aparece em milestones[]. Nenhum vencimento é calculado a partir dele. Um aviso redige-se como um fato com a sua data: «Em 11-09-2026 o INAPI publicou observações de mérito; o INAPI indica 30 días». A contestação do traslado de oposição, o pagamento dos direitos de concessão e as observações continuam sem prazo calculado até haver uma norma verificada.

Por lista de marcas e por data de deteção

Desde 2026-09-29, POST /annotations/search ≡ search_annotations (scope brands:read) responde numa única chamada «que atos novos têm estas marcas desde a última vez».

campo o que faz
applicationNumbers as anotações de até 100 marcas, por cursor; os duplicados contam uma vez. Mais de 100 distintas ⇒ 422 batch_too_large; mais de 1.000 ⇒ 400. Não se combina com applicationNumber, partyId nem taxId (400)
detectedAfter só atos que este corpus conheceu estritamente depois deste instante (ISO 8601 com fuso e com segundos, 2026-10-01T10:00:00Z; sem segundos ⇒ 400; exclusivo). Com applicationNumber ou applicationNumbers, as alterações dessas marcas; sozinho, o feed de todo o corpus
detectedUntil o extremo inclusivo, com o mesmo formato (segundos obrigatórios). Exige detectedAfter, applicationNumber ou applicationNumbers; anterior a detectedAfter ⇒ 400

Cada anotação traz denomination (a denominação da sua marca; cadeia vazia se a marca não tiver) e detectedAt: quando este corpus a conheceu, não quando o INAPI a publicou (isso é date). O histórico importado do legado traz a sua data de carga (2026-06-28/29, 2026-08-22, 2026-08-27): serve para «daqui em diante», não para reconstruir a história. Com dedupe (o padrão) um fato conta desde a sua primeira linha: uma versão gémea que chega hoje não torna novo um fato antigo.

Com lista ou deteção, a resposta declara meta.detectedThrough, o horizonte seguro: o menor entre agora e o início de qualquer execução de ingestão em curso. Nada detetado depois é servido, por isso nenhuma linha de uma execução a meio é saltada.

# Primeira vez: a minha lista até agora (guarde meta.detectedThrough)
curl -s -X POST "$TARNO_BASE_URL/annotations/search" -H "X-API-Key: $TARNO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"applicationNumbers": ["1510102", "1672581"], "detectedAfter": "2026-09-01T00:00:00Z"}'
# Na vez seguinte: «alterações desde X», X = o detectedThrough anterior
curl -s -X POST "$TARNO_BASE_URL/annotations/search" -H "X-API-Key: $TARNO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"applicationNumbers": ["1510102", "1672581"], "detectedAfter": "2026-09-29T13:24:04.323Z"}'

O padrão de cursor: peça com detectedAfter = o detectedThrough da vez anterior; pagine com cursor e o MESMO detectedUntil = o detectedThrough da primeira página; ao terminar, guarde esse valor para a próxima. Nenhuma linha é saltada nem repetida: o que o corpus guardar depois desse detectedUntil fica fora da varredura, mesmo como versão gémea de um fato já servido. Listas de mais de 100: divida em lotes de 100. Medido em produção em 2026-09-29: listas de 100 marcas em 3–15 ms, sem índice novo.

O feed de todo o corpus

detectedAfter sem applicationNumber, sem applicationNumbers e sem parte (partyId, taxId) devolve todos os atos que o corpus conheceu desde esse instante, de todas as marcas: quem acompanha milhares de marcas lê o feed e filtra do seu lado, em vez de perguntar lote a lote.

  • Ordem de deteção, não por data do ato: o instante em que o corpus guardou a linha e, em caso de empate, o seu id. Pagina-se com cursor. Com dedupe (o padrão) cada fato sai uma vez, na posição da linha que o apresenta, e o seu detectedAt é o da sua primeira linha: pode ser anterior ao dos vizinhos.
  • Sem filtros de conteúdo. Só admite detectedUntil, maxActAgeDays, dedupe, limit e cursor. family, section, citedNorm, article, letter, dateFrom, dateTo, niceClass e trademarkStatus dão 400 nomeando o campo: filtre do seu lado, ou nomeie as marcas. detectedAfter com partyId ou taxId e sem marca também é 400.
  • Cada linha traz o necessário para avisar sem outra chamada: applicationNumber, denomination, section com sectionName e sectionLabel, date e detectedAt.
  • Antiguidade do ato: maxActAgeDays (inteiro 0..3650, exige detectedAfter). Só saem os atos que tinham no máximo N dias quando o corpus os guardou: a sua date não é anterior ao dia UTC da deteção menos N. Um ato datado depois da sua deteção passa sempre; um sem date, nunca. Serve para que uma carga histórica (atos antigos que o corpus incorpora hoje) não chegue ao feed: o servidor não a envia. A ordem, o cursor e meta.detectedThrough não mudam. No feed, cada página lê um trecho limitado da ordem de deteção: pode trazer menos de limit resultados, ou nenhum, com next não nulo — siga next até ser nulo. Também vale com applicationNumber ou applicationNumbers.
# Primeira página: tudo o que se conheceu desde X (guarde meta.detectedThrough e next)
curl -s -X POST "$TARNO_BASE_URL/annotations/search" -H "X-API-Key: $TARNO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"detectedAfter": "2026-10-03T13:24:04.323Z", "limit": 100}'
# Páginas seguintes: o cursor e, SEMPRE, detectedUntil = o detectedThrough da primeira página
curl -s -X POST "$TARNO_BASE_URL/annotations/search" -H "X-API-Key: $TARNO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"detectedAfter": "2026-10-03T13:24:04.323Z", "detectedUntil": "2026-10-04T13:20:11.870Z", "limit": 100, "cursor": "<next>"}'
# Na próxima vez: detectedAfter = esse detectedThrough

O feed entra por um índice próprio, idx_anotacion_created_at_id (migração …513).