Guia de integração de componentes industriais da ETAR

Início rápido: escolha uma representação

1. Consulte o diretório público abaixo para descobrir as URLs das páginas publicadas e os metadados atuais dos documentos validados. Adicione ?lang=pt-br, ?lang=en ou ?lang=es; omita o parâmetro para consultar todos os idiomas.
2. Siga a URL de uma página retornada para acessar o conteúdo completo: HTML é o formato padrão. Solicite Accept: text/markdown nessa mesma URL para obter Markdown, inclusive neste guia. As respostas informam Vary: Accept e Content-Language.
3. Mantenha a URL da fonte junto ao seu resumo. Confirme o escopo e as condições publicados antes de preparar uma consulta pelo formulário HTML de contato.

Consultar o diretório

curl -sS --fail-with-body 'https://www.etar.com.ar/api/v1/content?lang=pt-br'

Ler uma página em Markdown

curl -sS --fail-with-body -H 'Accept: text/markdown' 'https://www.etar.com.ar/pt-br'

A URL de uma página define seu idioma; lang filtra apenas o diretório JSON. O JSON é um índice, não uma especificação técnica completa. Um array documents vazio indica que nenhum documento atende aos filtros atuais de publicação, validação, vigência e idioma; isso não constitui uma afirmação de certificação.

API de conteúdo público

GET /api/v1/content?lang=pt-br · HEAD /api/v1/content

Os dois métodos são operações seguras de consulta. GET retorna application/json; HEAD retorna os cabeçalhos da resposta sem corpo e também conta para o limite de requisições. O parâmetro opcional lang aceita exatamente es, en ou pt-br. Um valor vazio ou diferente retorna 400.

curl -sS --head 'https://www.etar.com.ar/api/v1/content?lang=pt-br'

Campos da resposta

name / access

Publicador e permissões: ETAR, public_read_only, authentication_required: false, writes_supported: false.

pages[]

Registros das páginas publicadas: key, language, title, description e a url canônica. Títulos e caminhos podem mudar em atualizações editoriais; siga a URL retornada.

documents[]

Metadados de documentos vigentes, publicados e validados: title, language, version, scope, url de download, valid_from e valid_until. As datas usam ISO 8601 YYYY-MM-DD ou null. Uma data nula não significa validade ilimitada. O download verifica novamente a disponibilidade e as permissões de publicação.

links

URLs canônicas de descoberta, incluindo documentation, openapi, directory e sitemap. As integrações devem aceitar campos adicionais.

Trecho da resposta JSON

Este trecho mostra o registro atual da página inicial. A resposta completa também contém outras páginas publicadas, registros de documentos quando disponíveis e links. O contrato completo é definido pelo esquema, não por este trecho.

{
  "name": "ETAR",
  "access": {
    "mode": "public_read_only",
    "authentication_required": false,
    "writes_supported": false
  },
  "pages": [{
    "key": "home",
    "language": "pt-br",
    "title": "Molas e componentes metálicos conforme desenho técnico.",
    "description": "Fabricação de molas e componentes metálicos conforme desenho técnico. Engenharia de processo, amostras, validação e fornecimento. Converse com a ETAR sobre seu próximo projeto.",
    "url": "https://www.etar.com.ar/pt\u002Dbr"
  }]
}

Baixe o contrato OpenAPI 3.1.1 para consultar os esquemas completos, as definições de parâmetros e as respostas. Os identificadores das operações são getEtarPublishedContent e headEtarPublishedContent. A própria especificação aceita GET e HEAD.

curl -sS --fail-with-body 'https://www.etar.com.ar/openapi.json'

Autenticação e permissões

A consulta pública não exige chave de API, token de acesso, conta nem escopo OAuth. Não envie credenciais. A API de conteúdo não oferece operações de escrita, registros de visitantes, nomes de anexos privados ou URLs assinadas de armazenamento. A ETAR não opera um servidor de autorização OAuth nem uma API GraphQL. Os ambientes de prévia podem exigir acesso ao Vercel antes de permitir a entrada neste site.

A administração utiliza sessões de colaboradores autorizados. Os anexos privados de consultas exigem permissão para download de consultas; os currículos de candidaturas exigem uma permissão separada. Esses recursos não fazem parte da API pública.

Consultas e candidaturas a vagas são fluxos HTML destinados a pessoas, com sessão, consentimento e proteção CSRF. Uma pessoa deve revisar e enviar o formulário apropriado; uma requisição JSON ou ferramenta MCP não pode enviá-lo. Não inclua desenhos, informações pessoais ou anexos nos parâmetros de consultas de leitura. Leia o aviso de privacidade antes de enviá-los pelo formulário.

Erros e limites de requisições

Os erros da API retornam um status HTTP de erro real e um corpo RFC 9457 application/problem+json. Verifique o status e o code; use detail e resolution para orientar a recuperação. O texto dos erros está em inglês em todos os filtros de idioma.

• 400 invalid_parameter: corrija lang antes de tentar novamente.
• 404 api_route_not_found: a rota da API não existe; consulte OpenAPI.
• 405 method_not_allowed: use Allow: GET, HEAD no endpoint de conteúdo; POST, PUT, PATCH e DELETE não realizam operações de escrita.
• 429 rate_limit_exceeded: aguarde o intervalo de Retry-After antes de tentar novamente.
• 500 service_error / 503 service_unavailable: tente novamente mais tarde, aumentando o intervalo entre as tentativas; evite requisições imediatas repetidas. Entre em contato com a ETAR se o erro persistir.

Exemplo de idioma inválido

curl -sS -i 'https://www.etar.com.ar/api/v1/content?lang=fr'

HTTP 400 · Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "The lang parameter must be es, en or pt-br, or omitted for all languages.",
  "code": "invalid_parameter",
  "resolution": "Use the parameters documented in /openapi.json."
}

Como interpretar a cota

O endpoint de conteúdo JSON permite 120 requisições por cliente em uma janela fixa de 60 segundos. Esses limites são aplicados conforme a disponibilidade do cache configurado: podem ser reiniciados entre instâncias ou implantações e não constituem uma cota global contratual. Consulte os cabeçalhos reais em vez de presumir o horário de reinício.

RateLimit-Policy: "public-read";q=120;w=60
RateLimit: "public-read";r=119;t=60
Cache-Control: private, no-store

Nesta resposta ilustrativa, q é a cota de requisições, w a janela em segundos, r as requisições restantes e t os segundos até o reinício. Uma resposta 429 acrescenta Retry-After em segundos. GET e HEAD compartilham essa cota. A API pública não garante um intervalo de consulta nem um acordo de nível de serviço.

Conectar por MCP

O endpoint MCP público é https://www.etar.com.ar/mcp, com Streamable HTTP e respostas JSON. Não exige autenticação e oferece apenas list_public_content, com o argumento opcional lang (es, en ou pt-br). A ferramenta retorna o mesmo diretório publicado da API de conteúdo; não pode enviar consultas nem acessar registros privados.

Configure a URL do servidor HTTP remoto do seu cliente MCP conforme indicado acima; as chaves de configuração variam de acordo com o cliente. Envie requisições JSON-RPC por POST com Content-Type: application/json e Accept: application/json, text/event-stream. GET, HEAD e DELETE retornam 405. O corpo das requisições é limitado a 64 KiB, e o MCP compartilha a cota da API. Clientes servidor a servidor podem omitir Origin; quando presente, ele deve corresponder à origem configurada do site.

Descoberta do protocolo

Para o protocolo 2026-07-28, use server/discover sem uma etapa inicial de negociação. Toda requisição inclui os metadados do protocolo em params._meta e os cabeçalhos correspondentes MCP-Protocol-Version e MCP-Method; uma chamada de ferramenta também exige MCP-Name. O documento de descoberta MCP da ETAR, em /.well-known/mcp, fornece metadados específicos da ETAR; não é um padrão central de descoberta MCP.

curl -sS 'https://www.etar.com.ar/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'MCP-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Compatibilidade com o protocolo 2025-11-25

Clientes que usam 2025-11-25 primeiro inicializam e depois enviam notifications/initialized. Em seguida, usam tools/list para consultar o esquema da ferramenta e tools/call para ler o diretório. Use a versão de protocolo negociada nas requisições seguintes.

curl -sS 'https://www.etar.com.ar/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"etar-guide","version":"1.0.0"}}}'

curl -sS 'https://www.etar.com.ar/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -sS 'https://www.etar.com.ar/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_public_content","arguments":{"lang":"pt-br"}}}'

Acesso pela linha de comando

O pacote @etar-srl/cli, versão 0.1.1, está disponível por download direto. Ele não está publicado no registro npm. Instale o pacote baixado pela URL; os exemplos com curl acima também funcionam sem a CLI.

npm install --global 'https://www.etar.com.ar/downloads/etar-cli-0.1.1.tgz'

Requer Node.js 22 ou posterior. O comando é etar; ele consulta recursos públicos sem credenciais e não pode enviar informações. Escolha um caminho de página retornado por content para usar em read, ou utilize um dos caminhos do guia de integração.

etar --version
etar content --lang pt-br
etar openapi
etar read /pt-br/desenvolvedores --format markdown

content e openapi imprimem JSON. read imprime um objeto JSON com url, content_type e markdown; --format markdown seleciona Markdown puro. Os resultados vão para stdout e os erros JSON para stderr. Os códigos de saída são 0 para sucesso, 1 para erros de rede ou resposta e 2 para argumentos inválidos. A CLI preserva o status HTTP de erro e Retry-After quando presente, sem tentativas automáticas.

Versões, fontes e próximos passos

O contrato atual de conteúdo usa /api/v1. A versão 1 está ativa e não tem encerramento programado. Metadados adicionais podem aparecer na v1; ignore os campos desconhecidos. Mudanças incompatíveis exigem uma nova URL de versão principal. Antes de um encerramento planejado, a ETAR publicará um aviso e a documentação de migração e indicará a descontinuação nos cabeçalhos das respostas.

Política de versionamento e descontinuação

• ETAR llms.txt: pontos de acesso ao material industrial publicado.
• ETAR sitemap.xml: URLs publicadas e alternativas de idioma.
• Sobre a ETAR: contexto da empresa e experiência publicada.
• Fale com a ETAR: encaminhe uma especificação para avaliação, um desenho definido para cotação ou os requisitos de cadastro de fornecedor.

Use as URLs canônicas das páginas e dos downloads em vez de guardar links de armazenamento específicos de uma implantação. Cite o certificado original e seu escopo exato quando um documento fundamentar uma afirmação; o acesso público, por si só, não comprova a adequação a uma peça ou aplicação específica.