Ir para o conteúdo

Exemplos de código

Clientes prontos para copiar e colar para ambos os transportes do contrato de leitura do Tarno. Substitua o marcador <API_KEY> pela sua chave emitida pelo operador em tempo de execução — nunca versione uma chave real.

REST

curl

export TARNO_API_KEY="<API_KEY>"

# Buscar/listar resumos de marcas (página keyset)
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=5" \
  -H "X-API-Key: $TARNO_API_KEY"

# Detalhe completo de uma solicitação, com seções expandidas (`norms` exige também `legal:read`)
curl -sS "https://api.tarno.cl/trademarks/123456?expand=parties,annotations,encumbrances,classes,norms" \
  -H "X-API-Key: $TARNO_API_KEY"

# Lote: várias solicitações conhecidas de uma vez (até 100)
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1286842,823470,9999999" \
  -H "X-API-Key: $TARNO_API_KEY"

TypeScript (fetch)

const baseUrl = "https://api.tarno.cl";
const apiKey = process.env.TARNO_API_KEY!; // "<API_KEY>"

async function listTrademarks(q: string, limit = 20) {
  const url = new URL(`${baseUrl}/trademarks`);
  url.searchParams.set("q", q);
  url.searchParams.set("limit", String(limit));

  const res = await fetch(url, { headers: { "X-API-Key": apiKey } });
  if (!res.ok) {
    const problem = await res.json(); // application/problem+json (RFC 9457)
    throw new Error(`${problem.status} ${problem.code}: ${problem.detail}`);
  }
  // { results: Trademark[], limit, next, hasMore, total, meta }
  return res.json() as Promise<{ results: unknown[]; next: string | null }>;
}

const page = await listTrademarks("cafe", 5);
console.log(page.results.length, "results; next =", page.next);

MCP

Um cliente mínimo de @modelcontextprotocol/sdk que se conecta ao endpoint Streamable HTTP com o cabeçalho X-API-Key e chama as ferramentas.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url = process.env.MCP_URL ?? "https://mcp.tarno.cl";
const apiKey = process.env.TARNO_API_KEY!; // "<API_KEY>"

const transport = new StreamableHTTPClientTransport(new URL(url), {
  requestInit: { headers: { "X-API-Key": apiKey } },
});

const client = new Client({ name: "tarno-mcp-example", version: "1.0.0" });
await client.connect(transport); // handshake JSON-RPC initialize

try {
  // search_trademarks — mesma entrada/saída que GET /trademarks
  const search = await client.callTool({
    name: "search_trademarks",
    arguments: { q: "cafe", limit: 5 },
  });
  const firstText = (r: typeof search) =>
    (r.content as Array<{ type: string; text?: string }>).find((c) => c.type === "text")?.text;
  const page = JSON.parse(firstText(search) ?? "{}");
  console.log(page.results.length, "results; next =", page.next);

  // get_trademark — mesma entrada/saída que GET /trademarks/{applicationNumber}
  const detail = await client.callTool({
    name: "get_trademark",
    arguments: { applicationNumber: "123456", expand: ["parties", "annotations"] },
  });
  console.log(firstText(detail)); // JSON do detalhe
} finally {
  await client.close();
}

Ambas as ferramentas exigem o escopo brands:read (ou uma chave sem restrição). Uma chave ausente ou inválida retorna um resultado de erro — nunca dados do corpus. Veja o guia de MCP e o guia de autenticação.

Veja também

  • Primeiros passos — primeiros passos em REST, envelope e paginação.
  • Conecte seu agente de IA (MCP) — endpoint, ferramentas, configuração de cliente.
  • A referência OpenAPI ao vivo em https://api.tarno.cl/docs — o schema REST autoritativo.