API, ключи и нейросети.

Обзор

Работать с CRM можно не только в браузере. Для программ, интеграций и нейросетей есть:

• REST API — https://crm.operatorai.cc/api/v1: сделки, воронки, клиенты, чаты, отправка сообщений.
• MCP-сервер для ИИ — https://crm.operatorai.cc/api/mcp/workspace: Grok, Claude, ChatGPT, Cursor работают с вашей CRM как с инструментом.
• Вебхуки — приём заявок из любых форм и отправка событий о новых заявках в вашу систему.

Доступ к API и MCP — только по API-ключу вашей компании.

API-ключи и права

Ключ создаёт администратор: CRM → Настройки → API и ИИ → Создать ключ. Назовите ключ по назначению («Grok — отчёты») и отметьте права:

Правила безопасности

• Ключ показывается один раз; на сервере хранится только его хэш. Потеряли — отзовите и создайте новый.
• Один ключ — одна программа или нейросеть, с минимальными правами. Право send давайте, только если ИИ действительно должен писать клиентам.
• Не вставляйте ключ в код сайта или в публичные репозитории — только в переменные окружения и настройки сервисов.
• В списке ключей видно, когда и с какого адреса ключ использовался последний раз. «Отозвать» — доступ прекращается сразу.
• Лимиты: 120 запросов в минуту на ключ; после 20 неверных ключей с одного адреса за 15 минут он блокируется. Все события пишутся в журнал безопасности.

Ключ передаётся в заголовке:

Authorization: Bearer oai_ВАШ_КЛЮЧ

REST API

Базовый адрес https://crm.operatorai.cc/api/v1, формат JSON, только HTTPS.

# новые сделки
curl https://crm.operatorai.cc/api/v1/deals?limit=20 \
  -H "Authorization: Bearer $OPERATORAI_KEY"

# создать сделку в нужной воронке
curl -X POST https://crm.operatorai.cc/api/v1/deals \
  -H "Authorization: Bearer $OPERATORAI_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Иван","phone":"+79990000000","comment":"Заявка с выставки","pipelineId":"<id из /pipelines>"}'

Ошибки: 401 — нет или неверный ключ, 403 — у ключа нет нужного права, 404 — объект не найден (или он чужой), 429 — превышен лимит. Тело ошибки: {"error": "понятное описание"}.

Нейросети (MCP)

MCP — стандартный способ дать нейросети инструменты. Адрес вашего рабочего пространства:

https://crm.operatorai.cc/api/mcp/workspace

Транспорт Streamable HTTP, ключ — в заголовке Authorization. Нейросеть видит только инструменты, разрешённые правами ключа:

• get_overview, list_pipelines, list_deals, get_deal, search_clients, list_chats, get_chat_messages — с правом read;
• create_deal, update_deal — с правом write;
• send_message — с правом send.

Для вопросов о самом продукте (без ключа и без ваших данных) есть публичный сервер https://operatorai.cc/mcp.

Подключение Grok

Grok подключает внешние MCP-серверы через xAI API (Responses API, инструмент mcp). Ключ Operator AI передаётся в поле authorization, ключ xAI — ваш, из console.x.ai.

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": [{"role": "user", "content": "Покажи сделки за неделю по воронке «Основная» и кратко подведи итог"}],
    "tools": [{
      "type": "mcp",
      "server_url": "https://crm.operatorai.cc/api/mcp/workspace",
      "server_label": "operatorai",
      "server_description": "CRM компании: сделки, клиенты, чаты",
      "allowed_tools": ["get_overview", "list_pipelines", "list_deals", "get_deal"],
      "authorization": "Bearer oai_ВАШ_КЛЮЧ"
    }]
  }'

allowed_tools дополнительно ограничивает, что Grok может вызывать; без него доступны все инструменты, разрешённые ключом.

Claude, ChatGPT, Cursor

Claude Code

claude mcp add --transport http operatorai https://crm.operatorai.cc/api/mcp/workspace \
  --header "Authorization: Bearer oai_ВАШ_КЛЮЧ"

OpenAI (ChatGPT API, Responses)

"tools": [{
  "type": "mcp",
  "server_label": "operatorai",
  "server_url": "https://crm.operatorai.cc/api/mcp/workspace",
  "headers": { "Authorization": "Bearer oai_ВАШ_КЛЮЧ" },
  "require_approval": "never"
}]

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "operatorai": {
      "url": "https://crm.operatorai.cc/api/mcp/workspace",
      "headers": { "Authorization": "Bearer oai_ВАШ_КЛЮЧ" }
    }
  }
}

Подойдёт любой MCP-клиент, который умеет передавать заголовок Authorization.

Синхронизация: заявки из форм

Заявки из любой системы (сайт, лендинг, 1С, бот) отправляйте на универсальный вебхук. Адрес и ключ — в CRM: Виджеты → CMS и формы → WordPress (ключ показывается один раз).

curl -X POST https://crm.operatorai.cc/webhooks/wordpress/$SITE_ID \
  -H "Content-Type: application/json" \
  -H "X-OperatorAI-Key: $OPERATORAI_KEY" \
  -d '{"name":"Иван","phone":"+79990000000","comment":"Хочу консультацию","form":"Лендинг","submission_id":"order-0001"}'

• submission_id защищает от дублей при повторной отправке.
• Ответы: 201 — создано, 200 — дубль, 403 — неверный ключ, 429 — больше 120 запросов в минуту.
• Готовые подключения: плагин WordPress, вебхук Tilda, телефония Mango Office, Авито и сообщество ВКонтакте — в настройках CRM.
• Отправляйте заявки со своего сервера, а не из кода страницы: ключ не должен попадать в браузер посетителя.

Исходящие события

CRM может сообщать вашей системе о каждой новой заявке: Настройки → Заявки на почту и вебхук. Запрос подписывается вашим секретом:

POST https://ваш-сервер/hook
X-OperatorAI-Signature: sha256=<hex>

{"event":"lead.created","data":{...},"timestamp":"2026-10-05T12:00:00.000Z"}

Проверка подписи (Node.js) — HMAC-SHA256 от сырого тела запроса:

const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get("X-OperatorAI-Signature") ?? ""));

Адрес должен быть публичным HTTPS (порт 443); перенаправления не выполняются.