# Integrações: MCP, API e webhooks

> Como um negócio conecta a sua Atenta ao Claude, ChatGPT, Zapier, Make, n8n ou ao próprio sistema: tokens com permissões, servidor MCP, API REST com OpenAPI e webhooks assinados.

A Atenta é **aberta**: com **um token** o negócio conecta a sua Atenta ao Claude, ChatGPT, Zapier, Make, n8n ou ao seu próprio código. Tudo o que se faz a partir daí é o mesmo que se faria no app: mesmos dados, mesmas regras, mesmos limites.

- **Servidor MCP:** `https://mcp.atenta.mx` (Claude Code, Claude Desktop, Cursor, n8n e qualquer cliente MCP que envie um cabeçalho `Authorization`).
- **API REST:** `https://api.atenta.mx/v1` · OpenAPI 3.1 em `https://api.atenta.mx/v1/openapi.json` · documentação em `https://api.atenta.mx/v1/docs`.
- **Webhooks de saída:** a Atenta avisa a sua URL quando algo acontece (mensagem, escalação, pedido, horário, pagamento, ligação).

As páginas por integração, na linguagem do dono, estão em [/integraciones](https://atenta.mx/pt/integraciones).

## 1. O token

É criado no app → **Ajustes → Integrações** («Conectar» no cartão que você quiser, com as permissões sugeridas). Tem a forma `atk_<negocio>_<32 caracteres>` e **é mostrado uma única vez**: guarde em um gerenciador de senhas ou em uma variável de ambiente, nunca em um chat nem em um repositório. A Atenta guarda só o hash e um prefixo para reconhecê-lo.

Permissões (escolha só as que a integração precisa):

| Permissão | O que deixa fazer |
|---|---|
| `leer_chats` | ler conversas, mensagens, respostas rápidas e equipe |
| `escribir_chats` | responder em um chat, assumir ou devolver o comando, fixar/arquivar |
| `pedidos` | ver, criar e atualizar pedidos |
| `citas` | ver disponibilidade, agendar, mover e cancelar horários; datas |
| `clientes` | buscar clientes, ficha, notas, etiquetas, acompanhamentos, segmentos, importar/exportar |
| `finanzas` | carteira, crédito e parcelas, cobrança, links de pagamento, cobrar pedidos |
| `reportes` | relatório do mês, PDF, histórico e métricas de ligações |
| `base` | ler a base de respostas, o cardápio, o cardápio do dia, o catálogo e os ajustes; **propor** correções (aprová-las é do dono, no app) |
| `integraciones` | ver os tokens e administrar os webhooks |

Regras que valem sempre: **120 chamadas por minuto** por token; cada escrita fica no registro do negócio com o nome do token; o que só se faz pelo app (aprovar a base, ligar, cobrar o plano, campanhas, excluir) responde `403 solo_desde_la_app` (só pelo app); os telefones dos clientes chegam mascarados; um token só vê o seu negócio. **Revogar** um token corta a integração na hora; «Revogar tudo» (vermelho, com a confirmação `REVOCAR TODO`) corta todas.

## 2. Claude Code e Claude Desktop

**Claude Code** (terminal). Guarde o token em uma variável de ambiente; a configuração faz referência a ele, não o contém:

```bash
export ATENTA_TOKEN="atk_..."   # o token que o app te deu
claude mcp add --transport http atenta https://mcp.atenta.mx --header 'Authorization: Bearer ${ATENTA_TOKEN}'
claude mcp list                 # atenta: https://mcp.atenta.mx (HTTP) - ✓ Connected
```

Depois, dentro do Claude Code: *«Quais conversas precisam de mim hoje?»*, *«Agenda a Laura na quinta às 5»*, *«Faz o resumo do dia»*. As ferramentas se chamam `atenta_chats_listar`, `atenta_pedidos_crear`, `atenta_citas_disponibles`… (só aparecem as que o seu token permite; `atenta_yo` diz quais).

**Claude Desktop** se conecta por arquivo (`claude_desktop_config.json`) com a ponte `mcp-remote`, que envia o token como cabeçalho. Os «conectores personalizados» do claude.ai autenticam por OAuth e a Atenta autentica por token, então esse caminho não se aplica.

```json
{
  "mcpServers": {
    "atenta": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atenta.mx", "--header", "Authorization: Bearer ${ATENTA_TOKEN}"],
      "env": { "ATENTA_TOKEN": "atk_..." }
    }
  }
}
```

Bloco genérico `mcpServers` para qualquer cliente que fale Streamable HTTP (Cursor, Windsurf, VS Code…):

```json
{
  "mcpServers": {
    "atenta": {
      "type": "http",
      "url": "https://mcp.atenta.mx",
      "headers": { "Authorization": "Bearer atk_..." }
    }
  }
}
```

### O que o servidor MCP expõe

Só aparecem as ferramentas que o token permite (mais `atenta_yo`, sempre).

| Ferramentas | Permissão |
|---|---|
| `atenta_chats_listar` · `atenta_chats_leer` | `leer_chats` |
| `atenta_chats_escribir` · `atenta_chats_tomar_control` · `atenta_chats_devolver` | `escribir_chats` |
| `atenta_pedidos_listar` · `atenta_pedidos_crear` · `atenta_pedidos_actualizar` | `pedidos` |
| `atenta_pedidos_cobrar` · `atenta_finanzas_saldo` · `atenta_finanzas_recargar` · `atenta_finanzas_abonar` · `atenta_finanzas_cobranza` · `atenta_finanzas_link` | `finanzas` |
| `atenta_citas_listar` · `atenta_citas_disponibles` · `atenta_citas_crear` · `atenta_citas_mover` · `atenta_citas_cancelar` | `citas` |
| `atenta_clientes_buscar` · `atenta_clientes_ficha` · `atenta_clientes_nota` · `atenta_clientes_seguimiento` · `atenta_clientes_etiquetar` | `clientes` |
| `atenta_reporte_mes` · `atenta_llamadas_historial` | `reportes` |
| `atenta_base_leer` · `atenta_base_proponer` (fica como correção proposta; **aprovar é do dono, no app**) · `atenta_menu_leer` · `atenta_menu_dia_hoy` | `base` |

Recursos (com `base`): `atenta://base`, `atenta://menu-dia`, `atenta://catalogo`, `atenta://menu`, `atenta://horario`, `atenta://plan`. Prompts: `resumen_del_dia`, `que_contesto_a_los_escalados` (propõe, não envia), `cobranza_de_hoy`.

## 3. ChatGPT

O caminho que funciona com um token é um **GPT personalizado com Actions**: em «Ações» importe o esquema de `https://api.atenta.mx/v1/openapi.json`, autenticação **API Key**, tipo **Bearer**, valor `atk_...`. O esquema já traz `servers`, `securitySchemes` e uma operação por ação (`chats_listar`, `pedidos_crear`, `citas_disponibles`…). Instrução sugerida para o GPT: *«Use as ações da Atenta para responder com dados reais do negócio; nunca invente preços nem horários; se uma ação falhar, diga o motivo que ela devolve».*

Os conectores MCP personalizados do ChatGPT autenticam por OAuth ou sem autenticação; a Atenta autentica por token, então para o ChatGPT usa-se a via de Actions.

## 4. Zapier, Make e n8n

Duas direções.

**a) Atenta → o seu fluxo (webhooks).** São criados em **Ajustes → Integrações → Webhooks** (URL `https` pública + eventos) ou pela API com a permissão `integraciones`:

```bash
curl -X POST https://api.atenta.mx/v1/webhooks \
  -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.zapier.com/hooks/catch/123/abc","eventos":["pedido","cita","escalacion"]}'
```

A resposta traz `secreto` (`whsec_…`, **uma única vez**). Cada evento chega como `POST` JSON:

```json
{ "evento": "pedido", "tenant": "mi-negocio", "ts": "2026-09-21T18:03:11.000Z",
  "datos": { "id": 812, "cliente_id": 41, "estado": "nuevo", "total": 250, "moneda": "MXN", "canal": "whatsapp", "nuevo": true } }
```

com os cabeçalhos `X-Atenta-Evento`, `X-Atenta-Entrega` (id único: serve para não processar duas vezes) e `X-Atenta-Firma: t=<unix>,v1=<hmac>`. Para verificar: `v1 == HMAC_SHA256(secreto, t + "." + cuerpo_crudo)` e `|agora − t| ≤ 300 s`. Em Node:

```js
import { createHmac, timingSafeEqual } from "node:crypto";
export function firmaValida(secreto, cuerpoCrudo, firma) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(firma ?? ""); if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = createHmac("sha256", secreto).update(`${m[1]}.`).update(cuerpoCrudo).digest("hex");
  return esperado.length === m[2].length && timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}
```

Eventos: `mensaje` (cada mensagem que entra ou sai, com a mensagem completa), `escalacion` (a Atenta pediu uma pessoa), `pedido` (novo ou mudança de estado), `cita` (novo, movido ou cancelado), `pago` (link pago ou parcela registrada), `llamada` (ligação com IA encerrada). Tentativas: se a sua URL não responde 2xx, a Atenta tenta de novo 3 vezes (1 s, 5 s, 25 s); depois de 20 falhas seguidas o webhook se desliga sozinho e você vê isso no app (com as últimas entregas). Botão «Testar» = evento `ping`. Máximo de 5 webhooks por negócio; só URLs `https`.

No Zapier: *Webhooks by Zapier → Catch Hook* te dá a URL; no Make: *Webhooks → Custom webhook*; no n8n: nó *Webhook* (POST) e um nó *Crypto* ou *Code* para validar `X-Atenta-Firma`.

**b) O seu fluxo → Atenta (API REST).** Qualquer rota do negócio funciona em `https://api.atenta.mx/v1/…` com `Authorization: Bearer atk_...` (módulos *HTTP Request* / *Webhooks by Zapier → Custom Request*). Exemplos:

```bash
# quem sou eu e o que posso fazer
curl https://api.atenta.mx/v1/yo -H "Authorization: Bearer $ATENTA_TOKEN"
# pedidos novos
curl "https://api.atenta.mx/v1/crm/pedidos?estado=nuevo&limite=20" -H "Authorization: Bearer $ATENTA_TOKEN"
# horários livres para agendar
curl "https://api.atenta.mx/v1/citas/disponibles?n=5" -H "Authorization: Bearer $ATENTA_TOKEN"
# agendar
curl -X POST https://api.atenta.mx/v1/citas -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"inicio":"2026-09-25T17:00:00-06:00","nombre":"Laura","motivo":"corte","estado":"confirmada"}'
# responder em um chat como pessoa do negócio
curl -X POST https://api.atenta.mx/v1/conversaciones/5214421234567/mensajes -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"texto":"Seu pedido já saiu, chega em 20 minutos."}'
# relatório do mês
curl "https://api.atenta.mx/v1/reporte?mes=2026-09" -H "Authorization: Bearer $ATENTA_TOKEN"
```

Erros, sempre com `error` curto e `motivo` em linguagem humana: `401` token inválido ou revogado · `403 sin_permiso` (diz qual permissão falta) · `403 solo_desde_la_app` (só pelo app) · `404` não existe neste negócio · `409` estado que não permite (`fuera_de_ventana`, `saldo_insuficiente`…) · `422` dados incompletos (`campos`) · `429` mais de 120 chamadas em um minuto (`Retry-After`). Cabeçalhos `X-RateLimit-Limit` e `X-RateLimit-Remaining` em cada resposta.

## 5. Integradores (agências)

Um token de integrador (`atp_…`, emitido pela Kalia Code) cadastra negócios como faz o formulário de atenta.mx e lê o estado deles; nunca entra nos dados de um negócio (para isso existe o token do dono).

```bash
curl -X POST https://api.atenta.mx/v1/alta -H "Authorization: Bearer $ATENTA_INTEGRADOR" -H "Content-Type: application/json" \
  -d '{"negocio":"Taquería El Güero","giro":"fonda","whatsapp":"5214421234567","pais":"MX"}'
curl https://api.atenta.mx/v1/tenants -H "Authorization: Bearer $ATENTA_INTEGRADOR"
curl https://api.atenta.mx/v1/tenants/taqueria-el-guero/base -H "Authorization: Bearer $ATENTA_INTEGRADOR"
```

## 6. Segurança, em resumo

- O token só existe do seu lado: a Atenta guarda um hash. Se vazar, revogue no app e crie outro.
- Tudo viaja por HTTPS; as respostas nunca trazem segredos nem números completos de clientes.
- Cada escrita feita com um token fica no registro do negócio com o nome do token.
- As IAs externas leem dados do negócio **só** com um token que o dono criou de propósito, com as permissões que ele escolheu e enquanto não o revogar. O provedor dessa IA é um subprocessador escolhido pelo próprio negócio, como diz o [aviso de privacidade](https://atenta.mx/pt/privacidad).