# Aitomaton Platform: Документация для разработчиков и ИИ-агентов (API & MCP)

Версия спецификации: 2026.11 | Казахстан (Алматы) | https://aitomaton.online
Формат: Markdown / LLM-ready context / Human-readable

---

## Содержание / Table of Contents
1. [Обзор архитектуры платформы Aitomaton](#1-обзор-архитектуры-платформы-aitomaton)
2. [REST API: Нативный приём веб-форм в сделки CRM](#2-rest-api-нативный-приём-веб-форм-в-сделки-crm)
   - [2.1. Схема параметров запроса](#21-схема-параметров-запроса)
   - [2.2. Примеры на языках программирования (cURL, JS, Python, PHP, Node.js)](#22-примеры-на-языках-программирования)
   - [2.3. Коды ответов сервера](#23-коды-ответов-сервера)
3. [Booking API: Публичный API онлайн-записи и расписания](#3-booking-api-публичный-api-онлайн-записи-и-расписания)
4. [Model Context Protocol (MCP) — Интеграция с ИИ-агентами](#4-model-context-protocol-mcp-интеграция-с-ии-агентами)
   - [4.1. Каталог инструментов CRM Tools](#41-каталог-инструментов-crm-tools)
   - [4.2. Конфигурация для Claude Desktop и Cursor IDE](#42-конфигурация-для-клиентов)
   - [4.3. Примеры подключения через Python и TypeScript SDK](#43-примеры-подключения-через-sdk)
5. [Телефония и голосовые агенты (SIP / Asterisk)](#5-телефония-и-голосовые-агенты-sip--asterisk)
6. [Песочница для тестов (Sandbox)](#6-песочница-для-тестов-sandbox)
7. [Безопасность и соответствие Закону РК № 94-V](#7-безопасность-и-соответствие-закону-рк--94-v)

---

## 1. Обзор архитектуры платформы Aitomaton

Aitomaton — B2B-платформа для Казахстана и СНГ, объединяющая:
- **Ядро CRM и омниканальный инбокс**: единое окно для WhatsApp Business API, Telegram, Instagram Direct и телефонии.
- **ИИ-агентов под ролями сотрудников**: автономная обработка входящих обращений, квалификация лидов, ведение диалогов на казахском и русском языках, запись клиентов и контроль обязательств.
- **Открытые протоколы интеграции**:
  1. **REST API & Webhooks**: нативный приём заявок с любых сайтов и форм напрямую в сделки CRM, бронирование слотов, телефония.
  2. **Model Context Protocol (MCP)**: стандартизированный протокол подключения внешних LLM и сред разработки (Claude Desktop, Cursor, OpenCode, LangChain) к инструментам и данным CRM.

---

## 2. REST API: Нативный приём веб-форм в сделки CRM

Платформа предоставляет защищённый эндпоинт для мгновенного создания клиентов, сделок и диалогов без сторонних интеграторов и middleware:

- **Метод**: `POST`
- **URL**: `https://aitomaton.online/api/public/forms/{channel_token}`
- **Песочница**: `https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01`

### 2.1. Схема параметров запроса
```json
{
  "name": "Имя контакта (string, обязательно, 2-120 символов)",
  "phone": "+7 777 123 45 67 (string, обязательно, международный формат)",
  "message": "Комментарий или текст обращения (string, опционально)",
  "formname": "Название формы (string, опционально, например: Запись на демо)",
  "service": "Идентификатор услуги/интеграции (string, опционально, например: 1С, Asterisk)",
  "page": "URL страницы отправки (string, опционально)",
  "utm_source": "Рекламный источник (string, опционально, например: google, yandex, direct)",
  "consent": true
}
```

### 2.2. Примеры на языках программирования

#### cURL
```bash
curl -X POST https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Айдар Нургалиев",
    "phone": "+7 777 123 45 67",
    "message": "Тестовая заявка на демонстрацию платформы",
    "service": "Демо-доступ",
    "formname": "Запись на демо",
    "page": "https://aitomaton.online/#popup:myform",
    "utm_source": "google_cpc",
    "consent": true
  }'
```

#### JavaScript (Fetch в браузере / React / Vue / Tilda)
```javascript
const payload = {
  name: "Айдар Нургалиев",
  phone: "+7 777 123 45 67",
  message: "Тестовая заявка на демонстрацию платформы",
  service: "Демо-доступ",
  formname: "Запись на демо",
  page: document.URL,
  utm_source: new URLSearchParams(location.search).get("utm_source") || "direct",
  consent: true
};

// Отправка без CORS preflight (simple request)
fetch("https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01", {
  method: "POST",
  headers: { "Content-Type": "text/plain;charset=UTF-8" },
  body: JSON.stringify(payload),
  mode: "no-cors"
})
.then(() => console.log("Заявка успешно отправлена в CRM"))
.catch((err) => console.error("Ошибка сети:", err));
```

#### Python (requests)
```python
import requests

url = "https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01"
payload = {
    "name": "Айдар Нургалиев",
    "phone": "+7 777 123 45 67",
    "message": "Тестовая заявка на демонстрацию платформы",
    "service": "Демо-доступ",
    "formname": "Запись на демо",
    "page": "https://aitomaton.online/",
    "utm_source": "python_backend",
    "consent": True,
}

response = requests.post(url, json=payload, timeout=10)
if response.status_code == 200:
    data = response.json()
    print(f"Сделка создана: ID={data.get('deal')}, Клиент={data.get('client')}")
else:
    print(f"Ошибка {response.status_code}: {response.text}")
```

#### PHP (cURL)
```php
<?php
$webhookUrl = 'https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01';

$payload = [
    'name'       => 'Айдар Нургалиев',
    'phone'      => '+7 777 123 45 67',
    'message'    => 'Тестовая заявка на демонстрацию платформы',
    'service'    => 'Демо-доступ',
    'formname'   => 'Запись на демо',
    'page'       => 'https://aitomaton.online/',
    'utm_source' => 'php_backend',
    'consent'    => true,
];

$ch = curl_init($webhookUrl);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_TIMEOUT        => 10,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    echo "Сделка создана! ID: " . $result['deal'];
}
```

#### Node.js (Axios)
```javascript
import axios from 'axios';

const webhookUrl = 'https://app-sandbox.aitomaton.online/api/public/forms/whk_aitomaton-demo_sitelead01';
const payload = {
  name: 'Айдар Нургалиев',
  phone: '+7 777 123 45 67',
  message: 'Тестовая заявка на демонстрацию платформы',
  service: 'Демо-доступ',
  formname: 'Запись на демо',
  page: 'https://aitomaton.online/',
  utm_source: 'node_microservice',
  consent: true
};

try {
  const { data } = await axios.post(webhookUrl, payload, { timeout: 10000 });
  console.log(`Успех! Сделка: ${data.deal}, Чат: ${data.chat}, Клиент: ${data.client}`);
} catch (error) {
  console.error('Ошибка создания заявки:', error.response?.data || error.message);
}
```

### 2.3. Коды ответов сервера
- `200 OK`: `{"status":"ok","outcome":"written","chat":"...","client":"...","deal":"..."}`
- `400 Bad Request`: Отсутствует обязательное поле или некорректный JSON.
- `404 Not Found`: Неизвестный или деактивированный токен канала.
- `429 Rate Limited`: Превышен лимит частоты запросов.

---

## 3. Booking API: Публичный API онлайн-записи и расписания

- **Получение свободных слотов**:
  `GET https://aitomaton.online/api/public/booking/{company_slug}/slots?resource_id={uuid}&date=YYYY-MM-DD`

- **Создание бронирования**:
  `POST https://aitomaton.online/api/public/booking/{company_slug}/book`
  Тело:
  ```json
  {
    "client_name": "Карина Ахметова",
    "client_phone": "+77028889900",
    "service_id": "srv_dentistry_consult_01",
    "resource_id": "01a187a2-629b-73f2-9f3f-878a5f1b92c5",
    "slot_start": "2026-11-15T15:30:00+05:00"
  }
  ```

---

## 4. Model Context Protocol (MCP) — Интеграция с ИИ-агентами

Платформа Aitomaton поддерживает стандарт **Model Context Protocol (MCP)**, позволяя внешним LLM и средам разработки выполнять защищённые операции над рабочим пространством компании.

- **Эндпоинт MCP-сервера**: `https://aitomaton.online/api/assistant/mcp`
- **Протокол**: JSON-RPC 2.0 через SSE / POST
- **Аутентификация**: Bearer-токен сессии или API-ключ компании (`Authorization: Bearer <token>`)

### 4.1. Каталог инструментов CRM Tools:
1. `crm_create_deal`: создание сделки в CRM с привязкой к клиенту и сумме.
2. `crm_find_client`: поиск карточки клиента по номеру телефона, имени или email.
3. `crm_query_data`: выполнение структурированных запросов к таблицам данных (Door v1).
4. `crm_book_slot`: запись клиента к мастеру или специалисту в свободный слот.
5. `crm_send_message`: отправка сообщения клиенту через WhatsApp Business API или Telegram.

### 4.2. Конфигурация для клиентов
#### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "aitomaton": {
      "command": "npx",
      "args": [
        "-y",
        "@aitomaton/mcp-bridge",
        "--endpoint=https://aitomaton.online/api/assistant/mcp",
        "--api-key=ВАШ_КЛЮЧ_ДОСТУПА_CRM"
      ]
    }
  }
}
```

#### Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "aitomaton-crm": {
      "url": "https://aitomaton.online/api/assistant/mcp",
      "headers": {
        "Authorization": "Bearer ВАШ_КЛЮЧ_ДОСТУПА_CRM"
      }
    }
  }
}
```

### 4.3. Примеры подключения через SDK
#### Python (mcp)
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_agent():
    params = StdioServerParameters(
        command="npx",
        args=["-y", "@aitomaton/mcp-bridge", "--endpoint=https://aitomaton.online/api/assistant/mcp", "--api-key=test_key"]
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("Доступные инструменты:", [t.name for t in tools.tools])
```

---

## 5. Телефония и голосовые агенты (SIP / Asterisk)

- **Сетевой стек**: SIP RFC 3261, RTP/SRTP, TLS.
- **Интеграция с Asterisk**: поддержка ARI (Asterisk REST Interface) и AMI (Asterisk Manager Interface).
- **Провайдеры РК**: прямое сопряжение с Казахтелеком, Beeline Business, Kcell, Tele2/Altel.
- **Вебхуки событий**: `call.started`, `call.transcribed`, `call.completed`, `call.analyzed`.

---

## 6. Песочница для тестов (Sandbox)

- **Вход в веб-клиент CRM**: `https://app-sandbox.aitomaton.online/`
- **Логин**: `sandbox@aitomaton.online`
- **Пароль**: `Aitomaton2026SafePassword!`
- **Компания**: `Aitomaton Демо Стенд` (`aitomaton-demo`)
- **Токен вебхука**: `whk_aitomaton-demo_sitelead01`

---

## 7. Безопасность и соответствие Закону РК № 94-V

- Все базы данных и серверы физически размещены в Республике Казахстан (Алматы).
- Изоляция данных на уровне тенантов (multi-tenant) гарантируется ядром Door v1.
- Все внешние запросы защищены TLS 1.3, пароли хэшируются Argon2id.