Portal de documentação do Tarno
O Tarno expõe um contrato de leitura neutro sobre o corpus de marcas do INAPI: uma API REST
versionada (sob /v1) e um servidor Model Context Protocol (MCP), ambos apoiados na mesma camada de consultas
e nos mesmos schemas Zod, de modo que os dois transportes retornam resultados idênticos. Este portal é a
documentação de primeiros passos voltada a pessoas; é neutro e reutilizável por qualquer consumidor.
O schema autoritativo vive na referência OpenAPI ao vivo em
/docs(uma página Scalar interativa gerada a partir do código). Estes guias explicam como fazer os primeiros passos e apontam para essa referência — eles não duplicam o schema. Quando um detalhe de campo ou endpoint não estiver descrito aqui,/docsé a fonte da verdade.
Guias de integração (DOCS-01)
| Guia | O que cobre |
|---|---|
| Primeiros passos | URL base + /v1, obtenção de uma chave emitida pelo operador, primeira chamada GET /v1/brands (curl + TS fetch), paginação/filtragem por keyset, o envelope de erro, noções básicas de cota. |
| Autenticação e escopos | O header X-API-Key, os escopos brands:read / insights:read (vazio = irrestrito), o ciclo de vida da chave (rotacionar/revogar/expirar) e a semântica de 401 / 403 / 429. |
| Conecte seu agente de IA (MCP) | O endpoint https://mcp.tarno.cl, X-API-Key, transporte Streamable HTTP, as ferramentas search_brands / get_brand_detail e exemplos de configuração de cliente. |
| Exemplos de código | Clientes REST (curl + TS fetch) e MCP (@modelcontextprotocol/sdk) prontos para copiar e colar. |
Contrato e operações (DOCS-02)
| Documento | O que cobre |
|---|---|
| Status | Status do serviço e onde ficam as superfícies ao vivo de atualidade/saúde. |
| Versionamento e descontinuação | O contrato do prefixo /v1 e como mudanças incompatíveis ganham uma nova versão. |
| Migração v1.6 | A consolidação v1.6, já aplicada (janela fechada): denominacion→nombre, fechaDesde/Hasta→fechaPresentacion* (removidos) e estado→um vocabulário validado de 14 códigos (fora → 400). |
| SLA | Postura de disponibilidade, cadência de sync/atualidade, expectativas de suporte. |
| Calendário de feriados | O calendário legal chileno que o corpus usa para contar dias úteis: tipo/origen por linha, o intervalo que afirma cobrir (GET /v1/feriados/cobertura) e o 422 fuera_de_cobertura ao pedir fora dele. |
| Cobertura histórica | Até onde o corpus de marcas chega para trás (distinto do calendário de feriados). |
| Changelog | Histórico de versões do contrato de leitura. |
Os documentos DOCS-02 são produzidos pelo plano irmão desta fase; seus links estão listados aqui para que este índice seja o único ponto de entrada para todo o portal.
Referência autoritativa da API
O schema REST completo, sempre atualizado e por campo, é a referência OpenAPI (Scalar) interativa
servida em https://api.tarno.cl/docs. Comece pelos
guias acima para fazer os primeiros passos e, em seguida, use essa referência como o schema canônico para todo endpoint,
parâmetro e formato de resposta.