Integrações: MCP, API e webhooks

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.

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):

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:

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.

{
  "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…):

{
  "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).

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:

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:

{ "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:

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:

# 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).

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.