Ir para o conteúdo

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 /trademarks aceita ainda uma superfície combinada por campos — denomination/holder/representative/taxId/applicationNumber/registrationNumber, multivalorada, semântica AND, matchedFields[] e ordenação configurável com sort=. 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: null significa fim dos resultados — pare.
  • Uma exceção: GET /watch/hits é um feed e devolve next sempre; 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. Respostas 5xx usam texto genérico e nunca vazam detalhes internos.
  • requestId — correlaciona seu relato com o log do servidor. É o mesmo valor do cabeçalho X-Correlation-ID; você pode fornecer o seu por esse mesmo cabeçalho.
  • errors[] — em um 400, detalha qual campo falhou e por quê. ⭐ Um parâmetro que a rota não declara também é um 400 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:

  1. Limites de rajada de curto prazo — dois tetos de taxa, ambos com HTTP 429 code: "rate_limited" e Retry-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.
  2. Cota mensal — um orçamento mensal por chave. Quando esgotado, a API retorna HTTP 429 com code: "quota_exceeded" e o cabeçalho Retry-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