# Ligue o Claude, o ChatGPT ou o Gemini à sua loja do TorraHub

> Passo a passo, sem programar, para ligar a sua loja do TorraHub ao Claude, ao ChatGPT ou ao Gemini: que plano precisa, os botões de cada aplicativo, como testar e desconectar. E, para quem programa, o token, o servidor MCP e a lista do que o agente pode ler e lançar.

Página: https://torrahub.com/docs/agente · Atualizado em novembro de 2026.

Ligada ao Claude ou ao ChatGPT, a sua loja responde em conversa: o assistente lê o estoque e o resumo do dia e lança torra, envase, contagem, venda e despacho por você, com as mesmas regras das telas do painel. Você fala "torrei 6 kg do Gourmet" e o lançamento aparece em Torras, com o nome do assistente na nota. Ligar leva uns 5 minutos e não precisa programar: é copiar um endereço e entrar com a senha do painel.

Esta página serve a você e ao seu agente. Se preferir, mande o link para o Claude e peça "liga a minha loja do TorraHub": tudo o que ele precisa está aqui, inclusive a lista de operações em [JSON](https://torrahub.com/docs/agente/operacoes.json) e esta página em [Markdown](https://torrahub.com/docs/agente.md).

## O que o agente faz na sua loja

Você fala como falaria com alguém da equipe. O agente procura os ids que precisa (o café, a pilha, o cliente), mostra o que vai lançar com os números, e só lança depois do seu ok.

- **"Como está o dia?"** → `resumo`. Os pedidos a despachar, quem ainda deve e quanto, os alertas do sino e os pacotes que saíram sem rótulo.
- **"Torrei 6 kg do Gourmet hoje, saiu 5,1 kg. Envasei 12 de 250 g em grão."** → `cadastros`, `torra`. A fornada entra com o verde que saiu do lote, o custo do torrador e os 12 pacotes. O que não foi envasado fica a granel.
- **"Vendido 2 Gourmet para a Ana, cobra no Pix."** → `clientes`, `cadastros`, `venda`. O pedido entra como venda direta, com o preço do catálogo, e volta um link do WhatsApp com a cobrança e o Pix para você tocar e mandar.
- **"Despachei o #0071, rastreio AP123456789BR."** → `despacho`. O pedido passa a enviado com o rastreio. Antes, o agente pergunta se avisa o cliente.
- **"Contei o Moca: 14."** → `estoque`, `contagem`. A pilha do Moca fica com 14 pacotes. Se o Moca estiver em mais de uma pilha, o agente pergunta como dividir.

A lista completa, com cada campo que o agente pode mandar, está em [Tudo o que ele pode ler e lançar](https://torrahub.com/docs/agente#operacoes).

## Ligue em 5 minutos, sem programar

O caminho é o mesmo nos três aplicativos: você cola o endereço da loja como **conector personalizado**, entra com o e-mail e a senha do painel e clica em **Autorizar**. Não tem senha no endereço, e você não cola token nenhum.

1. No painel da sua loja, abra **Integrações → Assistentes de IA** (`/admin/integracoes/assistentes`) e escolha o seu assistente.
2. Clique em **Copiar endereço**. É sempre o domínio da loja (o mesmo da vitrine) mais `/api/mcp`, por exemplo `https://cafeserrano.com.br/api/mcp`.
3. Siga os passos do seu aplicativo, logo abaixo. O painel mostra os mesmos passos, ao lado do botão de copiar.

- **Claude: funciona.** Funciona em todos os planos.
- **ChatGPT: funciona em parte.** Só nos planos de empresa.
- **Gemini: ainda não.** Ainda não no Brasil.

## No Claude (claude.ai, app do computador e do celular)

**Que plano precisa.** Funciona em todos os planos do Claude, inclusive no gratuito. No gratuito cabe um conector personalizado só. Nos planos Team e Enterprise, quem adiciona é o dono da conta da empresa, em **Configurações da Organização → Conectores**; depois cada pessoa clica em **Conectar**.

**Computador ou celular.** Adicione pelo computador. Depois de ligada, a loja aparece também no app do Claude no celular, na mesma conta.

**Passo a passo:**

1. No computador, abra o **claude.ai** (ou o aplicativo do Claude para computador) e entre na sua conta.
2. Clique em **Personalizar** e depois em **Conectores**. Com o Claude em inglês: **Customize → Connectors**.
3. Clique em **+ Adicionar** e escolha **Adicionar conector personalizado** (em inglês, **Add custom connector**).
4. No nome, escreva o nome da sua loja. No endereço, cole o endereço da loja que você copiou e clique em **Continuar**.
5. O Claude mostra como vai entrar na loja. Deixe as opções que ele sugerir, clique em **Continuar** e depois em **Adicionar**.
6. Clique em **Conectar** no conector da loja. Abre a tela de entrada do painel: entre com o seu e-mail e senha e clique em **Autorizar**.

**Como é a tela de entrada.** O Claude abre uma janela do painel da sua loja. Entre com o mesmo e-mail e senha do painel. Depois aparece **"Claude quer acessar"** e o nome da sua loja, com o que ele vai poder fazer e o que não vai. Clique em **Autorizar**. A janela fecha sozinha e você volta para a conversa.

**Teste.** Numa conversa, clique no **+** embaixo, à esquerda, depois em **Conectores**, e ligue o da loja. Pergunte: "Como está o dia?". Na primeira vez, o Claude pede licença para usar a loja: aceite. Antes de lançar qualquer coisa, ele mostra o que vai lançar e espera o seu ok.

**Para desconectar:**

- No Claude: **Personalizar → Conectores**, no conector da loja, **Remover**.
- Pela loja: no painel, em **Integrações → Assistentes de IA**, clique em **Desconectar** ao lado do aplicativo. O acesso cai na hora, mesmo que o conector continue no aplicativo.

**Se não der certo.** Se a entrada der erro no passo 6, remova o conector e adicione de novo; no passo 5, em **Cliente OAuth**, escolha **Registrar automaticamente**.

Conferido nas páginas de ajuda em 9 de novembro de 2026: [Comece com conectores personalizados (ajuda do Claude)](https://support.claude.com/pt/articles/11175166-comece-com-conectores-personalizados-usando-mcp-remoto) · [Conectores no celular (ajuda do Claude)](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities).

## No ChatGPT

**Que plano precisa.** O ChatGPT lança venda, torra e estoque só nos planos **Business**, **Enterprise** e **Edu**. No **Pro**, ele liga a loja mas só lê (o resumo do dia, o estoque, os clientes). No **Plus** e no gratuito, a OpenAI ainda não libera conector próprio. No Business, só o administrador ou o dono da conta da empresa adiciona.

**Computador ou celular.** Só pelo site, no computador. O app do ChatGPT no celular ainda não adiciona conector próprio.

**Passo a passo:**

1. No computador, abra o **chatgpt.com** e entre na sua conta.
2. Abra **Plugins**, no menu da esquerda (ou direto em chatgpt.com/plugins).
3. Clique no **+** e escolha **Adicionar servidor MCP personalizado** (em inglês, **Add custom MCP server**).
4. Dê o nome da sua loja. Em **Conexão**, cole o endereço da loja que você copiou.
5. Na autenticação, deixe a entrada por login (OAuth). Em geral o ChatGPT já escolhe sozinho.
6. Leia o aviso, marque **Entendo e quero continuar** e clique em **Criar como plugin**.
7. Clique em **Conectar**. Abre a tela de entrada do painel: entre com o seu e-mail e senha e clique em **Autorizar**.

**Como é a tela de entrada.** O ChatGPT abre uma janela do painel da sua loja. Entre com o mesmo e-mail e senha do painel. Depois aparece **"ChatGPT quer acessar"** e o nome da sua loja, com o que ele vai poder fazer e o que não vai. Clique em **Autorizar**. A janela fecha sozinha e você volta para a conversa.

**Teste.** Numa conversa nova, digite **@**, escolha a loja e pergunte: "Como está o dia?". A escolha vale para aquela mensagem: na próxima, chame a loja de novo com **@**. Antes de lançar, o ChatGPT pede confirmação.

**Para desconectar:**

- No ChatGPT: **Configurações → Plugins**, abra o da loja e clique em **Desconectar**.
- Pela loja: no painel, em **Integrações → Assistentes de IA**, clique em **Desconectar** ao lado do aplicativo. O acesso cai na hora, mesmo que o conector continue no aplicativo.

**Se não der certo.** No Plus ou no gratuito, use o Claude: ele liga a loja até no plano gratuito.

Conferido nas páginas de ajuda em 9 de novembro de 2026: [Conectar servidores MCP personalizados no ChatGPT (ajuda da OpenAI)](https://help.openai.com/pt-BR/articles/12584461).

## No Gemini

**Que plano precisa.** O app do Gemini só aceita apps personalizados em conta pessoal do Google, de maiores de 18 anos, nos Estados Unidos e com o Gemini em inglês. Conta do trabalho ou da escola não aceita. No Brasil, a opção ainda não aparece. No Gemini Enterprise, o Google pede um cadastro fixo de aplicativo que a loja ainda não oferece.

**Computador ou celular.** Quando chegar, adiciona pelo site no computador e usa também no celular.

**O melhor caminho hoje.** Enquanto isso, use o Claude: ele liga a loja até no plano gratuito. Quem programa pode ligar a loja no Gemini CLI, em **Avançado**.

**Se a opção aparecer na sua conta:**

1. No computador, abra o **gemini.google.com**.
2. Vá em **Settings → Connected Apps** (se não aparecer, **Personal Intelligence → Connected Apps**).
3. Em **Custom apps**, clique em **Add a custom app**, cole o endereço da loja que você copiou e clique em **Next**.
4. Abre a tela de entrada do painel: entre com o seu e-mail e senha e clique em **Autorizar**.

**Como é a tela de entrada.** O Gemini abre uma janela do painel da sua loja. Entre com o mesmo e-mail e senha do painel. Depois aparece **"Gemini quer acessar"** e o nome da sua loja, com o que ele vai poder fazer e o que não vai. Clique em **Autorizar**. A janela fecha sozinha e você volta para a conversa.

**Teste.** Numa conversa, digite **@**, escolha a loja e pergunte: "How is my store doing today?" (o recurso é só em inglês). O Gemini pede confirmação antes de lançar.

**Para desconectar:**

- No Gemini: **Settings → Connected Apps**, em **Custom apps**, **More details → Remove app**.
- Pela loja: no painel, em **Integrações → Assistentes de IA**, clique em **Desconectar** ao lado do aplicativo. O acesso cai na hora, mesmo que o conector continue no aplicativo.

Conferido nas páginas de ajuda em 9 de novembro de 2026: [Conectar apps personalizados ao Gemini (ajuda do Google, em inglês)](https://support.google.com/gemini/answer/17209137) · [Servidor MCP no Gemini Enterprise (ajuda do Google)](https://support.google.com/g/answer/17106276).

## Para quem programa: o token da loja

O Claude Code, o Claude Desktop e os scripts entram com um token, sem a tela de entrada. Quem só usa o Claude ou o ChatGPT não precisa disto.

1. No painel da sua loja, abra **Integrações → Assistentes de IA** (`/admin/integracoes/assistentes`) e abra **Avançado (para quem programa)**.
2. Dê um nome ao agente (ele aparece na nota de cada lançamento, por exemplo "Claude do balcão") e toque em **Criar token**.
3. Copie o token na hora. Ele começa com `thag_` e aparece uma vez só: a loja guarda apenas uma impressão dele, e não tem como mostrá-lo de novo. Perdeu, crie outro e revogue o antigo.

Um token por pessoa ou por uso deixa a trilha mais clara e permite cortar um sem derrubar os outros. A lista de tokens mostra quando cada um foi usado pela última vez.

## No Claude Code

Troque o endereço pelo da sua loja e `thag_…` pelo token. O painel, em Avançado, já mostra este comando com o endereço certo e, logo depois de criado, com o token.

```bash
claude mcp add --transport http torrahub https://{sua-loja}/api/mcp --header "Authorization: Bearer thag_…"
```

Depois, numa conversa nova, `/mcp` mostra o servidor `torrahub` ligado. O endereço do servidor é sempre `https://<sua-loja>/api/mcp`, no domínio da loja (o mesmo da vitrine).

## No Claude Desktop, com token

O jeito simples é o conector personalizado, como no [claude.ai](https://torrahub.com/docs/agente#claude): o que se adiciona no site aparece no aplicativo. Para ligar com token, pelo arquivo de configuração, use o `mcp-remote` (precisa do Node.js instalado). Abra **Configurações → Desenvolvedor → Editar configuração** e acrescente:

```json
{
  "mcpServers": {
    "torrahub": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://{sua-loja}/api/mcp",
        "--header",
        "Authorization:${TOKEN}"
      ],
      "env": {
        "TOKEN": "Bearer thag_…"
      }
    }
  }
}
```

Feche e abra o Claude Desktop. As ferramentas da loja aparecem no botão de ferramentas da conversa. O `Authorization:${TOKEN}` vai sem espaço de propósito: no Windows, o espaço dentro do argumento quebra o cabeçalho.

## No Gemini CLI

O Gemini CLI, de linha de comando, liga servidores MCP remotos e descobre sozinho o login da loja: sem token. Ele abre o navegador nesta máquina para a tela de entrada, e a autorização volta para o `localhost` (a tela da loja avisa que o destino é o seu computador).

```bash
gemini mcp add --transport http torrahub https://{sua-loja}/api/mcp
# depois, dentro do Gemini CLI:
/mcp auth torrahub
```

## Outros agentes e scripts: a porta REST

As mesmas operações respondem em `/api/agente/<nome>`, com o token no cabeçalho `Authorization: Bearer thag_…`. As que só leem aceitam GET (os campos vão na URL); todas aceitam POST com o corpo em JSON.

```bash
# o que este token pode fazer, com o esquema de cada operação
curl -H "Authorization: Bearer $TOKEN" https://{sua-loja}/api/agente

# ler
curl -H "Authorization: Bearer $TOKEN" "https://{sua-loja}/api/agente/clientes?busca=Ana"

# lançar
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"pedido":"0071","tipo":"enviado","rastreio":"AP123456789BR","avisarCliente":true}' \
  https://{sua-loja}/api/agente/despacho
```

- `200`: deu certo. A resposta traz `ok`, `message` e, quando há, `dados` (ids, listas) e `whatsappUrl`.
- `422`: a regra recusou, com a mesma mensagem que a tela mostraria (granel curto, café que não é da loja, data inválida).
- `400` corpo que não é JSON; `401` sem token, token inválido ou revogado; `403` token de outra loja; `404` operação que não existe; `405` GET numa operação que escreve.

O servidor MCP é a mesma lista vista pelo protocolo: transporte Streamable HTTP, sem sessão, com `initialize`, `ping`, `tools/list` e `tools/call` num POST para `/api/mcp`.

## Tudo o que ele pode ler e lançar

Esta lista é gerada da mesma lista que o servidor da loja executa. O nome é o da ferramenta no MCP e o fim do caminho no REST. Campo marcado como obrigatório tem de ir; os outros, quando ausentes, usam o que a descrição diz.

### As que só leem

#### `resumo`

Só lê · MCP `resumo` · REST `GET ou POST /api/agente/resumo`

O resumo do dia: pedidos a despachar, pedidos esperando pagamento (com quanto falta), os alertas do sino (sem rastreio, entrega falhada, contas vencidas, extrato a decidir, rupturas) e os pacotes que saíram sem rótulo.

Sem campos de entrada.

#### `estoque`

Só lê · MCP `estoque` · REST `GET ou POST /api/agente/estoque`

Lista as fornadas que ainda têm café: granel (gramas), pilhas de pacotes prontos (id, peso, moagem, quantidade) e as gramagens que cada café vende. Use ANTES de envasar, moer, contar ou desenvasar, para pegar os ids. Não adivinhe ids.

Sem campos de entrada.

#### `cadastros`

Só lê · MCP `cadastros` · REST `GET ou POST /api/agente/cadastros`

Lista os cafés à venda (variantes com id, peso, moagem, preço e quanto dá para vender agora), os lotes de café verde (id, nome, código) e os torradores (id, nome, se é terceirizado, preço por kg de verde). Use antes de registrar torra ou venda.

Sem campos de entrada.

#### `clientes`

Só lê · MCP `clientes` · REST `GET ou POST /api/agente/clientes`

Procura clientes pelo nome, telefone ou e-mail. Devolve id, nome e telefone. Se vier mais de um com o mesmo nome, PERGUNTE qual antes de vender.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `busca` | string | sim | nome, telefone ou e-mail |

### As que escrevem (pedem confirmação)

#### `torra`

Escreve · MCP `torra` · REST `POST /api/agente/torra`

Registra uma torra inteira: o verde que entrou (por lote), o torrado que saiu, data, quantas fornadas no torrador, quem torrou (torrador do cadastro), se foi terceirizada, o custo, e na mesma chamada quanto foi moído e os envases (grão e/ou moído, peso, rótulo frente/trás, embalagem, custo do envase). Pegue os ids em "cadastros". Tudo que não foi envasado fica a granel.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `cafeSlug` | string | sim | slug do café (em "cadastros") |
| `data` | string | sim | AAAA-MM-DD da torra |
| `verde` | lista de objetos | não |  |
| `verde[].loteId` | string | não | uuid |
| `verde[].gramas` | integer | não | mínimo 1 |
| `torradoG` | integer | sim | mínimo 1 |
| `fornadas` | integer | não | quantas fornadas no torrador; mínimo 1 |
| `torradorId` | string | não | uuid do torrador do cadastro |
| `quemTorrou` | string | não | nome, se o torrador não está no cadastro |
| `terceirizada` | boolean | sim |  |
| `custoTorraCents` | integer | não | custo da torra; ausente = preço por kg do torrador × kg de verde |
| `consumoProprioG` | integer | não | mínimo 0 |
| `moerG` | integer | não | gramas do torrado que foram moídas; mínimo 1 |
| `envases` | lista de objetos | não |  |
| `envases[].pacotes` | integer | não | mínimo 1 |
| `envases[].grind` | string | não | 'whole' = grão, 'medium' = moído; valores: `whole`, `medium` |
| `envases[].pesoG` | integer | não | gramas do pacote; obrigatório se o café tem duas gramagens |
| `envases[].data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `envases[].nota` | string | não | texto livre que vai na nota do movimento |
| `envases[].insumos` | object | não | O que o envase consumiu. Ausente = o do cadastro do café. null num campo = "nenhum" (não colei / sem fecho). |
| `envases[].insumos.embalagem` | string \| null | não | slug do saco |
| `envases[].insumos.fecho` | string \| null | não | slug do fecho |
| `envases[].insumos.rotuloFrenteCents` | number \| null | não | custo da face da frente; null = não colei |
| `envases[].insumos.rotuloTrasCents` | number \| null | não | custo da face de trás; null = não colei |
| `envases[].envaseCentsPorPacote` | number \| null | não | mão de obra por pacote, em centavos; null = envasei eu; ausente = nada declarado |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `moer`

Escreve · MCP `moer` · REST `POST /api/agente/moer`

Mói granel em grão de uma fornada: as gramas viram granel moído (na fornada irmã ou numa nova, devolvida em destinoId).

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `roastBatchId` | string | sim | uuid |
| `gramas` | integer | sim | mínimo 1 |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `envase`

Escreve · MCP `envase` · REST `POST /api/agente/envase`

Envasa: o café sai do granel de uma fornada e vira pacote (a mesma regra da tela de Torras). Pegue o roastBatchId em "estoque". Moído (medium) sai do granel moído — se a fornada só tem grão, use "moer" antes.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `roastBatchId` | string | sim | uuid |
| `pacotes` | integer | sim | mínimo 1 |
| `grind` | string | sim | 'whole' = grão, 'medium' = moído; valores: `whole`, `medium` |
| `pesoG` | integer | não | gramas do pacote; obrigatório se o café tem duas gramagens |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |
| `insumos` | object | não | O que o envase consumiu. Ausente = o do cadastro do café. null num campo = "nenhum" (não colei / sem fecho). |
| `insumos.embalagem` | string \| null | não | slug do saco |
| `insumos.fecho` | string \| null | não | slug do fecho |
| `insumos.rotuloFrenteCents` | number \| null | não | custo da face da frente; null = não colei |
| `insumos.rotuloTrasCents` | number \| null | não | custo da face de trás; null = não colei |
| `envaseCentsPorPacote` | number \| null | não | mão de obra por pacote, em centavos; null = envasei eu; ausente = nada declarado |

#### `amostras`

Escreve · MCP `amostras` · REST `POST /api/agente/amostras`

Envasa amostras (saquinhos) do granel de uma fornada.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `roastBatchId` | string | sim | uuid |
| `quantidade` | integer | sim | mínimo 1 |
| `grind` | string | sim | 'whole' = grão, 'medium' = moído; valores: `whole`, `medium` |
| `pesoG` | integer | sim | gramas de cada amostra, ex.: 50 |
| `saquinho` | string | não | slug do insumo do saquinho |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `pacotes`

Escreve · MCP `pacotes` · REST `POST /api/agente/pacotes`

Move pacotes prontos de UMA pilha (o + e o − de Estoque): 'entrada', 'perda', 'consumo_proprio', 'amostra_avulsa'. Para contagem de várias pilhas, use "contagem".

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `roastBatchId` | string | sim | uuid |
| `roastPileId` | string | não | uuid da pilha; obrigatório se a fornada tem mais de uma |
| `motivo` | string | sim | valores: `contagem`, `perda`, `consumo_proprio`, `amostra_avulsa`, `entrada` |
| `pacotes` | integer | sim | na contagem, o TOTAL contado; nos outros, quantos; mínimo 0 |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `contagem`

Escreve · MCP `contagem` · REST `POST /api/agente/contagem`

Lança a contagem da prateleira, várias pilhas de uma vez: para cada pilha, o TOTAL contado (zero vale). Pegue roastBatchId e roastPileId em "estoque". Se o café/peso/moagem que a pessoa disse está em mais de uma pilha, PERGUNTE como dividir.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `itens` | lista de objetos | sim |  |
| `itens[].roastBatchId` | string | sim | uuid |
| `itens[].roastPileId` | string | não |  |
| `itens[].pacotes` | integer | sim | mínimo 0 |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `desenvasar`

Escreve · MCP `desenvasar` · REST `POST /api/agente/desenvasar`

Desfaz pacotes: o café volta ao granel. Diga se o saco volta a ser usado (devolveSaco).

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `roastBatchId` | string | sim | uuid |
| `roastPileId` | string | não |  |
| `pacotes` | integer | sim | mínimo 1 |
| `devolveSaco` | boolean | sim |  |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |
| `nota` | string | não | texto livre que vai na nota do movimento |

#### `venda`

Escreve · MCP `venda` · REST `POST /api/agente/venda`

Registra uma venda direta (WhatsApp, feira, balcão) para um cliente do cadastro, pelos pacotes do catálogo. Pegue clienteId em "clientes" e variantId em "cadastros". Sem preço, usa o do catálogo. cobrarPix: true devolve whatsappUrl com a mensagem de cobrança e o Pix — mostre o link para a pessoa tocar. Pacote sem estoque vira encomenda.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `clienteId` | string | sim | uuid |
| `itens` | lista de objetos | sim |  |
| `itens[].variantId` | string | sim | uuid |
| `itens[].quantidade` | integer | sim | mínimo 1 |
| `itens[].precoCents` | integer | não | preço combinado por pacote; ausente = do catálogo; mínimo 0 |
| `pago` | boolean | sim | true = já recebeu; false = a pagar |
| `cobrarPix` | boolean | não | gera a cobrança Pix e o link do WhatsApp (só se não pago) |
| `entrega` | string | não | em mãos ou despacho; valores: `hand`, `ship` |
| `data` | string | não | AAAA-MM-DD; sem ela, hoje |

#### `despacho`

Escreve · MCP `despacho` · REST `POST /api/agente/despacho`

Marca um pedido como enviado (com rastreio e data de postagem) ou entregue em mãos. avisarCliente: true manda o aviso ao cliente (e-mail/WhatsApp, se a régua estiver ligada); pergunte se não souber.

| Campo | Tipo | Obrigatório | Detalhe |
|---|---|---|---|
| `pedido` | string | sim | o número, ex.: "0071" ou "#0071" |
| `tipo` | string | sim | entregue = em mãos; valores: `enviado`, `entregue` |
| `rastreio` | string | não |  |
| `dataPostagem` | string | não | AAAA-MM-DD; sem ela, hoje |
| `cidade` | string | não | cidade da entrega em mãos |
| `avisarCliente` | boolean | sim |  |

#### `verificar-pagamentos`

Escreve · MCP `verificar-pagamentos` · REST `POST /api/agente/verificar-pagamentos`

O botão "Verificar pagamentos": confere no Mercado Pago os pagamentos dos últimos 35 dias, lança o que casa com certeza e diz o que precisa de confirmação na tela.

Sem campos de entrada.

## O que o acesso abre, e o que nunca abre

- **Uma loja por acesso.** O token, ou a autorização do conector, abre só a loja que o criou. Mandado ao endereço de outra loja, é recusado.
- **Revogável na hora.** Desconectar o aplicativo, ou revogar o token, em **Integrações → Assistentes de IA**, corta o acesso no pedido seguinte. Para voltar, conecte de novo (ou crie outro token).
- **Escrita com confirmação.** O servidor instrui o agente a dizer o que vai lançar, com os números, e esperar o seu ok antes de toda operação que escreve. O próprio Claude também pede permissão antes de usar uma ferramenta, a menos que você a libere.
- **Trilha de tudo.** Cada lançamento leva "Agente (nome do token)" na nota do movimento e uma linha na trilha de auditoria da loja, com o que foi pedido e o que a loja respondeu.
- **As regras das telas.** Nenhuma operação tem atalho: o envase confere o granel, a venda confere o catálogo, o despacho confere o pedido, e a recusa é a mesma mensagem da tela. Nenhuma operação apaga registro; o que sai do estoque sai por movimento, como no painel.
- **O que ele vê.** Só o que as operações devolvem: estoque, cafés, lotes de verde e torradores, o resumo do dia (pedidos a despachar e a receber, alertas) e, na busca de clientes, nome, telefone e e-mail de quem bate com a busca, para lançar a venda.
- **O que ele nunca alcança.** Dados de cartão, senhas, as configurações e as integrações da loja, a edição de preços e do cadastro de produtos, e o console de dados. Não existe operação para isso, então não há o que o agente chame.

Guarde o token como guarda uma senha: no segredo do ambiente ou no arquivo de configuração, nunca colado numa conversa.

## Para o agente que está lendo

Se você é um agente configurando esta integração para alguém:

1. Pergunte o domínio da loja (o da vitrine, por exemplo `https://cafeserrano.com.br`). Sem token, `GET https://<loja>/api/agente/descricao` devolve o nome da loja, o endereço do MCP dela e todas as operações com o esquema da entrada.
2. Se a pessoa usa o claude.ai, o app do Claude ou o ChatGPT, mande-a para os passos de [Ligue em 5 minutos](https://torrahub.com/docs/agente#conectar): ela cola o endereço como conector personalizado e autoriza na tela da loja, sem token.
3. Para você mesmo (Claude Code, scripts), peça à pessoa que crie o token em Painel da loja → Integrações → Assistentes de IA → Avançado (para quem programa) e o guarde como segredo. Não peça para colar o token no chat se houver outro caminho.
4. Ligue o MCP em `https://<loja>/api/mcp`: como conector personalizado, que entra por OAuth (a pessoa autoriza na tela da loja), ou com o cabeçalho `Authorization: Bearer thag_…` (comandos acima). Ou use o REST.
5. Siga as regras abaixo, que o servidor também manda no `initialize`.

- Antes de lançar, leia ("estoque", "cadastros", "clientes") para pegar os ids. Nunca invente um id.
- Confirme com a pessoa o que vai lançar antes de toda operação que escreve, dizendo os números.
- Quando uma operação devolver whatsappUrl, mostre o link para a pessoa tocar.
- Se a resposta vier com ok: false, diga a mensagem como veio: é a mesma recusa que a tela do painel mostraria.

Versões para máquina: [operacoes.json](https://torrahub.com/docs/agente/operacoes.json) (as operações com o esquema JSON, o caminho REST e o nome no MCP), [agente.md](https://torrahub.com/docs/agente.md) (esta página) e [llms.txt](https://torrahub.com/llms.txt).