Primeiros passos
O Tarno expõe um contrato de leitura neutro sobre o corpus de marcas do INAPI: uma API REST (sem prefixo de versão) e um servidor MCP, ambos apoiados na mesma camada de consultas e nos mesmos dados. Este guia leva você do zero até uma primeira chamada autenticada contra a API REST.
O schema completo, sempre atualizado e por campo, vive na referência OpenAPI interativa em
https://api.tarno.cl/docs(Scalar). Este guia explica como fazer os primeiros passos e aponta para essa referência — não reformula o schema. Quando um campo não está documentado aqui,https://api.tarno.cl/docsé autoritativo.
1. URL base
A API REST é servida por HTTPS em https://api.tarno.cl. O contrato não usa mais prefixo de versão:
cada recurso vive direto na raiz, p. ex. https://api.tarno.cl/trademarks. A referência interativa (Scalar)
está em https://api.tarno.cl/docs.
Algumas rotas são intencionalmente públicas (não exigem chave):
| Path | Propósito |
|---|---|
/health |
Sonda de liveness/readiness (200 ok / 503 degradado) |
/docs |
Referência OpenAPI (Scalar) interativa — https://api.tarno.cl/docs |
/metrics |
Métricas Prometheus (somente rede interna) |
Todas as demais rotas de negócio (p. ex. /trademarks) são protegidas e exigem chave de API (veja abaixo e
o guia de autenticação).
2. Obtenha uma chave de API
As chaves de API são emitidas pelo operador, fora de banda, pelo portal do operador. Não há endpoint de cadastro self-service — você não cria a própria chave. Peça ao operador uma chave de leitura; ele entrega uma string opaca e informa quais escopos ela carrega (a lista completa está na tabela de escopos). Veja o guia de autenticação para escopos, ciclo de vida (rotacionar / revogar / expirar) e a semântica exata de erros.
Guarde a chave como variável de ambiente e nunca a versione:
export TARNO_API_KEY="<API_KEY>" # a string de chave opaca que o operador emitiu
Todos os exemplos deste portal usam o marcador óbvio
<API_KEY>. Substitua pela sua chave real em tempo de execução; nunca escreva uma chave fixa em arquivo versionado.
3. Sua primeira chamada autenticada: GET /trademarks
Envie a chave no cabeçalho X-API-Key. GET /trademarks busca ou lista resumos de marcas.
curl
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=5" \
-H "X-API-Key: $TARNO_API_KEY"
TypeScript (fetch)
const baseUrl = "https://api.tarno.cl";
const apiKey = process.env.TARNO_API_KEY!; // "<API_KEY>"
const res = await fetch(`${baseUrl}/trademarks?q=cafe&limit=5`, {
headers: {
"X-API-Key": apiKey,
"X-Correlation-ID": "<seu-id-de-correlação>", // opcional; devolvido em toda resposta
},
});
if (!res.ok) {
// application/problem+json (RFC 9457)
const problem = await res.json();
throw new Error(`${problem.status} ${problem.code}: ${problem.detail} (requestId=${problem.requestId})`);
}
const page = await res.json(); // { results: Trademark[], limit, next, hasMore, total, meta }
console.log(page.results.length, "results; next =", page.next);
Uma resposta bem-sucedida é uma página por keyset:
{
"results": [
{
"applicationNumber": "123456",
"registrationNumber": null,
"denomination": "CAFE EXAMPLE",
"status": "en_tramite",
"statusInapi": null,
"statusStale": false,
"signType": "mixta",
"filedOn": "2023-01-15",
"expiresOn": null,
"publishedOn": "2023-02-01",
"registeredOn": null,
"renewalStatus": null,
"milestones": [],
"score": 0.87
}
],
"limit": 20,
"next": "eyJvIjoyMH0",
"hasMore": true,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" }
}
score é uma confiança absoluta de 0 a 1 (o maior dos sinais por canal, não o valor RRF interno, que só ordena a lista; por isso pode não cair de forma monótona) e está presente somente na rota de busca por texto livre
(q=); é omitido em uma listagem filtrada simples. ⭐ A busca por texto omite total: a chave só
viaja no lote (applicationNumber=), na listagem sem filtros e nas listagens filtradas com contagem ≤
10.000. status e signType são strings
com o código (p. ex. "en_tramite", "mixta"), ou null. statusInapi e statusStale viajam sempre:
statusInapi é o status bruto do INAPI só quando difere de status (senão, null), e statusStale é true
exatamente quando diferem («o INAPI ainda não o atualizou»). Para o conjunto exato de campos da marca, veja a referência em
https://api.tarno.cl/docs.
4. Filtragem e paginação por keyset
GET /trademarks aceita estes parâmetros de consulta:
| Param | Tipo | Notas |
|---|---|---|
q |
string | Busca por texto livre (full-text + fuzzy). Quando presente, os resultados são ranqueados e levam score. Omita para listagem filtrada simples. |
niceClass |
integer[] | Filtro de classe de Nice, 1–45; aceita várias. |
status |
string[] | Códigos de status (catálogo controlado); aceita vários. |
signType |
string[] | Códigos de tipo de sinal (catálogo controlado); aceita vários. |
filedFrom |
YYYY-MM-DD |
Limite inferior da data de depósito (filedOn >=). |
filedTo |
YYYY-MM-DD |
Limite superior da data de depósito (filedOn <=). |
limit |
integer | Tamanho da página. Padrão 20, máximo 100. |
cursor |
string | Cursor keyset opaco (veja abaixo). Trate como caixa-preta. |
Busca por campos (field-scoped).
GET /trademarksaceita ainda uma superfície combinada por campos —denomination/holder/representative/taxId/applicationNumber/registrationNumber, multivalorada, semânticaAND,matchedFields[]e ordenação configurável comsort=. Veja o guia de busca por campos.
A paginação é por keyset, não por offset. Cada resposta leva um cursor opaco next:
- Para a próxima página, reenvie-o sem mudanças como o parâmetro
cursor. next: nullsignifica fim dos resultados — pare.- Uma exceção:
GET /watch/hitsé um feed e devolvenextsempre; ali o fim éhasMore: false(Vigilância de semelhantes).
# página 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# página 2 — reenvie o cursor `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"
Para obter uma marca com as seções completas (parties + annotations + encumbrances + classes + norms), chame
GET /trademarks/{applicationNumber}?expand=parties,annotations,encumbrances,classes,norms
(norms exige também o escopo legal:read; sem ele, retire-o de expand):
curl -sS "https://api.tarno.cl/trademarks/123456?expand=parties,annotations,encumbrances,classes,norms" \
-H "X-API-Key: $TARNO_API_KEY"
Um número de depósito desconhecido retorna 404 not_found.
A família insights:read (GET /system/freshness, GET /system/sync-runs) está documentada no
guia de autenticação e na referência https://api.tarno.cl/docs.
5. Erros (RFC 9457)
Todo erro — validação, autenticação, não encontrado, limite de taxa e erros inesperados — é devolvido
com o corpo application/problem+json da RFC 9457, com a mesma forma em REST e no MCP:
{
"type": "https://api.tarno.cl/problems/validation_error",
"title": "Request validation failed",
"status": 400,
"detail": "`offset` was withdrawn from the contract: paginate with `limit` + `cursor`",
"code": "validation_error",
"requestId": "74c953c7-24fc-492d-80ed-c6e1b18327fe",
"errors": [ { "field": "offset", "code": "unrecognized_keys", "detail": "…" } ]
}
code— token estável e neutro para ramificar (veja a tabela abaixo). É o contrato.title/detail— legíveis para humanos; a redação pode mudar sem ser uma quebra. Respostas5xxusam texto genérico e nunca vazam detalhes internos.requestId— correlaciona seu relato com o log do servidor. É o mesmo valor do cabeçalhoX-Correlation-ID; você pode fornecer o seu por esse mesmo cabeçalho.errors[]— em um400, detalha qual campo falhou e por quê. ⭐ Um parâmetro que a rota não declara também é um400 validation_error, com uma entrada por chave (field= a chave,code: "unrecognized_keys"): a API nunca ignora em silêncio o que não entende.
| HTTP | code |
Quando |
|---|---|---|
| 400 | validation_error |
Consulta/parâmetros inválidos (a validação de schemas falhou). |
| 401 | unauthorized |
Chave ausente, malformada, desconhecida ou revogada. |
| 403 | forbidden |
Chave válida, mas sem o escopo que a rota exige. |
| 404 | not_found |
Número de depósito desconhecido, ou rota desconhecida. |
| 409 | ambiguous_selector |
A referência (a um documento do INAPI ou a uma norma) casa com mais de um recurso. |
| 409 | cursor_stale |
O cursor de GET /trademarks/application-numbers é de um corpus anterior (uma sincronização começou ou terminou entre páginas): recomece sem cursor. |
| 405 | method_not_allowed |
Método HTTP não permitido (o MCP só aceita POST). |
| 413 | payload_too_large |
O corpo da requisição excede o tamanho admitido. |
| 422 | regra de negócio (p. ex. out_of_coverage) |
A requisição é válida e ainda assim não pode ser atendida: p. ex. um intervalo que o calendário de feriados não afirma cobrir. Nunca respondido com lista vazia/parcial — veja Calendário de feriados. |
| 429 | rate_limited |
Limite de rajada de curto prazo excedido (veja abaixo). |
| 422 | application_terminal · watch_limit_reached |
Vigilância: a solicitação está em estado terminal, ou a sua organização chegou ao limite do plano — veja Vigilância. |
| 429 | quota_exceeded |
Cota mensal esgotada (veja abaixo). Leva Retry-After. |
| 429 | watch_daily_limit_reached |
Limite diário de cadastros de vigilância. Leva limit e resetsAt; sem Retry-After: espere até resetsAt. |
| 500 | internal_error |
Erro não previsto do serviço; texto genérico, sem detalhes internos. |
| 502 | logo_analysis_invalid_output |
O modelo que descreve um logo devolveu uma saída inválida. |
| 503 | service_unavailable |
Uma dependência não está disponível agora (o banco sem recursos, o armazém de vigilâncias, o canal de significado de um semantic, a busca de marcas com todos os canais fora do ar…); reexecutável. |
| 503 | coverage_not_declared |
O calendário de feriados não declara nenhum ano coberto; reexecutável. |
| 504 | query_timeout |
Timeout de consulta/upstream; reexecutável. Como todo 5xx, não vaza detalhes internos. |
⭐ Um code tem um único status, o mesmo por REST e por MCP (desde 2026-09-30, ERR-1). A tabela
vive no código do serviço e os dois transportes a leem. Até essa data, um erro
de recursos do banco (disco, memória) era 500 internal_error pelo REST; agora é 503 service_unavailable.
6. Limites de taxa e cota
Dois limites independentes protegem o contrato de leitura:
- Limites de rajada de curto prazo — dois tetos de taxa, ambos com HTTP 429
code: "rate_limited"eRetry-After: um por chave (padrão 300 requisições a cada 60 s, idêntico em REST e MCP) e outro por IP de cliente (padrão 100 requisições/minuto no REST e 30 por segundo no MCP). Detalhes no guia de autenticação. - Cota mensal — um orçamento mensal por chave. Quando esgotado, a API retorna HTTP 429 com
code: "quota_exceeded"e o cabeçalhoRetry-After(segundos até a janela reiniciar no fim do mês). A mesma cota aplica-se idêntica em REST e MCP — veja o guia de MCP.
Toda resposta autenticada servida leva os cabeçalhos padrão RateLimit-Limit, RateLimit-Remaining e
RateLimit-Reset, que descrevem a cota mensal da chave (Reset = segundos até o reinício de fim de mês;
uma chave sem limite só leva RateLimit-Limit: unlimited). Os 429 de rajada e de cota levam Retry-After (o de vigilância, watch_daily_limit_reached, leva resetsAt no corpo):
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1209600
{ "type": "https://api.tarno.cl/problems/quota_exceeded", "title": "Rate limit exceeded", "status": 429,
"detail": "Monthly quota exceeded", "code": "quota_exceeded", "requestId": "…" }
Respeite Retry-After: espere o número indicado de segundos antes de tentar de novo.
Próximos passos
- Autenticação e escopos —
X-API-Key, a tabela de escopos, ciclo de vida da chave e a semântica completa de401/403/429. - Conecte seu agente de IA (MCP) — o endpoint
mcp.tarno.cle as ferramentassearch_trademarks/get_trademark. - Exemplos de código — clientes REST e MCP prontos para copiar e colar.
- A referência OpenAPI ao vivo em
https://api.tarno.cl/docs— o schema autoritativo por campo.