Como o OpenThor funciona

Sete conceitos explicam tudo o que você vai encontrar no OpenThor. Cada um cabe em um parágrafo — leia na ordem ou pule direto para o que interessa.

• Chave de API — o crachá da sua empresa.
• MCP — a tomada padrão que liga a IA aos seus dados.
• Ferramenta — uma pergunta pronta que a IA sabe fazer.
• Domínio — os sete assuntos do seu negócio.
• O que sua chave enxerga — o recorte aplicado no servidor.
• Frescor — de quando são os dados de cada resposta.
• Estado vazio honesto — por que uma conta nova começa zerada.

Chave de API

A chave de API é o crachá da sua empresa: um código secreto que começa com ot_live_ e identifica a sua organização em cada chamada. Quem apresenta o crachá fala em nome da empresa — por isso a chave nunca vai em grupo de mensagens, planilha compartilhada ou e-mail.

Ela é criada no painel (app.openthor.dev), em Chaves & Uso, pelo botão Nova chave — e o valor completo aparece uma única vez, na hora da criação. Exemplo: a Distribuidora Modelo Ltda cria uma chave rotulada “planilha-financeiro” e cola só nessa planilha. Os detalhes estão em Autenticação.

MCP

MCP (Model Context Protocol) é o padrão aberto que conecta assistentes de IA a sistemas de dados — pense numa “tomada padrão”: qualquer aparelho compatível liga na mesma tomada, sem adaptador. O claude.ai, o ChatGPT e o Claude Desktop falam MCP; o OpenThor é um servidor MCP, a tomada onde eles se conectam.

https://api.openthor.dev/mcp

Na prática você não precisa decorar essa URL: os guias de conexão mostram onde colá-la, e no claude.ai e no ChatGPT a conexão termina com “entrar e aprovar” — sem colar chave nenhuma. Comece por Conectar o claude.ai.

Ferramenta

Uma ferramenta (tool) é uma pergunta pronta que a IA sabe fazer aos seus dados. get_top_products, por exemplo, responde “quais produtos mais venderam no período?”. É como um cardápio: você pede em português, e o garçom — a IA — escolhe sozinho o prato certo na cozinha. Você nunca precisa citar o nome de uma ferramenta.

O catálogo tem cerca de 50 ferramentas, agrupadas por assunto — veja o catálogo completo ou a página de uma delas, como get_top_products.

Domínio

Um domínio é um assunto do seu negócio — como os corredores de um armazém, cada coisa no seu lugar. São sete: Vendas, Clientes, Pedidos, Trade, Financeiro, Estoque e Metas. Toda ferramenta pertence a um domínio: “quem está devendo?” mora no Financeiro; “qual produto está em ruptura?” mora no Estoque.

O que sua chave enxerga

Cada credencial pode carregar um recorte (row_scope): a fatia dos dados que ela tem direito de ver — uma filial, um vendedor, um cliente, um fornecedor ou uma janela de datas. O recorte é aplicado no servidor, não no aplicativo: é uma parede, não uma cortina.

Exemplo: João (RCA 42) pergunta “quanto vendemos este mês?” e recebe o total da carteira dele — sem erro, sem aviso, por desenho. Os filtros de uma pergunta podem estreitar o recorte (“só a filial 2”), mas nunca ampliá-lo.

Frescor

Frescor é a idade dos dados de uma resposta. Toda resposta declara o campo data_as_of — “dados de 12 minutos atrás” — como a data de validade estampada na embalagem. O coletor sincroniza com o seu Winthor a cada poucos minutos, então os números acompanham o dia de perto. Detalhes em Resposta e metadados.

Estado vazio honesto

Uma organização recém-criada vê telas vazias e um R$ 0 verdadeiro — nunca números de exemplo apresentados como se fossem reais. É a loja no dia da inauguração: prateleira vazia de verdade vale mais que prateleira cheia de caixa vazia. Assim que o coletor começa a enviar dados, os números aparecem — os seus, e só os seus.