API и MCP

Первый запрос

Создайте ключ и проверьте подключение.

1. Откройте «API и подключения» в настройках аккаунта.
2. Создайте ключ, выберите собственный профиль и право profiles:read. Оставьте режим с подтверждением владельца.
3. Сохраните ключ в секретах сервера или переменной окружения ZUMZAM_API_KEY. Полный ключ показывается при выдаче.
4. Выполните запрос capabilities. Ответ покажет среду, права, режим записи и доступные пути.

curl "https://zumzam.ru/api/v1/capabilities" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY"

{
  "api_version": "1",
  "environment": "production",
  "scopes": ["profiles:read"],
  "write_mode": "review",
  "policy_version": 1
}

Это сокращённый пример ответа. Для следующих запросов получите UUID профиля через GET /api/v1/profiles. Публичный номер вида IDP-000001 не заменяет UUID.

curl "https://zumzam.ru/api/v1/profiles" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY"

Ключи и права доступа

Ограничьте интеграцию нужными профилями и действиями.

Каждый запрос API и MCP использует Authorization: Bearer <ключ>. Ключ связан с владельцем, выбранными profile_ids и набором scopes. Он не открывает каталог чужих профилей и не даёт административных прав.

Управление ключами, смена режима и подтверждение изменений доступны владельцу в кабинете. API-ключ не может сам расширить свои права. Банковское OAuth-согласие и принятие приглашения другим человеком также остаются отдельными действиями.

Запись и подтверждение

Владелец выбирает режим отдельно для каждого ключа.

Действия отправляются в POST /profiles/{profileId}/actions. В input передаются поля конкретной операции. Ответ содержит change, его статус и сведения о подтверждении. В примере ZUMZAM_PROFILE_ID содержит UUID выбранного профиля.

curl "https://zumzam.ru/api/v1/profiles/$ZUMZAM_PROFILE_ID/actions" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "operation": "profile.update",
    "idempotency_key": "crm:profile:title:revision-42",
    "input": { "display_name": "Кондитерская Алиас" }
  }'

Публикация — отдельное действие. Добавление услуги или восстановление профиля не означает автоматическую публикацию всего профиля. Операции проверяют те же ограничения и доступ к инструментам, что и кабинет.

Каталог без дублей

Перенесите позицию с фото, проверьте результат и обновляйте её по внешнему ID.

1. Один раз создайте источник через POST /profiles/{profileId}/sources и сохраните source.id.
2. Передайте source_id, устойчивый external_id и поля позиции в POST /profiles/{profileId}/imports.
3. Откройте preview_url. Сохранение выполняется в соответствии с режимом ключа; нужное подтверждение делает владелец.
4. Для обновления сохраните source_id и external_id, измените данные и передайте новый Idempotency-Key.

curl "https://zumzam.ru/api/v1/profiles/$ZUMZAM_PROFILE_ID/sources" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"Каталог сайта"}'

curl "https://zumzam.ru/api/v1/profiles/$ZUMZAM_PROFILE_ID/imports" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: cake-42:revision-1" \
  --data @item.json

{
  "source_id": "00000000-0000-4000-8000-000000000001",
  "item": {
    "external_id": "cake-42",
    "name": "Шоколадный торт",
    "description": "Шоколадный бисквит с ягодами",
    "price_minor": 180000,
    "currency": "RUB",
    "price_type": "from",
    "price_unit": "kg",
    "photo_url": "https://example.com/catalog/cake-42.jpg"
  }
}

В этом запросе 180000 означает 1800 рублей за килограмм. example.com — пример: подставьте собственную доступную HTTPS-фотографию. Сервис проверит и перенесёт фото в управляемое хранилище. Внутренние адреса и произвольные локальные пути не принимаются.

Пропущенные позиции не удаляются. Неизменившиеся данные источника не должны затереть ручную правку. Если одно поле изменили и в источнике, и в кабинете, импорт получает conflicted и требует согласования.

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

Те же права и режим записи для нейросетей и MCP-клиентов.

Адрес сервера: https://zumzam.ru/api/v1/mcp. Транспорт — Streamable HTTP с JSON-ответами, авторизация — Bearer-ключ. Выберите клиент, который умеет передавать Authorization. OAuth-авторизация MCP пока не предоставляется.

{
  "url": "https://zumzam.ru/api/v1/mcp",
  "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
}

Это параметры соединения, а не универсальный формат конфигурации для всех приложений. Клиент выполняет initialize, принимает согласованную версию, отправляет notifications/initialized, затем tools/list. Пример ниже использует версию 2025-11-25.

curl "https://zumzam.ru/api/v1/mcp" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-integration","version":"1.0.0"}}}'

curl "https://zumzam.ru/api/v1/mcp" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl "https://zumzam.ru/api/v1/mcp" \
  --header "Authorization: Bearer $ZUMZAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Поддержаны версии 2025-03-26, 2025-06-18, 2025-11-25 и stateless discovery 2026-07-28. Для 2026-07-28 используются server/discover, версия в _meta, clientCapabilities и согласованные Mcp-Method / Mcp-Name. Не смешивайте этот lifecycle с initialize. Сервер не выдаёт MCP-сессии; отдельного GET SSE-потока нет.

Имя инструмента записи соответствует операции с заменой точки на подчёркивание: profile.update → profile_update. Аргументы записи: profile_id, input, idempotency_key. У именованного чтения есть собственное имя; точные аргументы возвращает tools/list. structuredContent содержит результат; ошибки инструмента нужно проверять по isError.

curl --fail --output zumzam-mcp.mjs \
  "https://zumzam.ru/developers/mcp-stdio.mjs"
node /absolute/path/zumzam-mcp.mjs

Проверка интеграции

Начните с отдельного профиля и режима подтверждения.

Для первых запросов выберите отдельный собственный неопубликованный профиль, выдайте минимальные права и режим review. Прочитайте данные, подготовьте изменение, изучите предпросмотр и отмените ненужный запрос в кабинете. Direct включайте для ключа после проверки синхронизации.

Для разработчиков с доступом к исходникам есть локальный изолированный контур. Команды выполняются из корня проекта. setup создаёт отдельные тестовые данные; реальные пароли аккаунтов и ключи провайдеров не нужны.

node scripts/developer-api/sandbox.mjs setup
node scripts/developer-api/sandbox.mjs start

# API: http://localhost:4016/api/v1
# MCP: http://localhost:4016/api/v1/mcp

Локальные ключи имеют префикс zz_test_, production-ключи — zz_live_. Значение environment возвращает capabilities. Данные и ключи разных сред не взаимозаменяемы.

Повторы и конфликты

Сохраняйте идентификатор запроса до получения результата.

У actions ключ повтора передаётся в поле idempotency_key. У импорта и бинарных загрузок используется заголовок Idempotency-Key. Не помещайте в ключи повтора пароли, токены или персональные данные.

Отправка письма и действие во внешнем канале могут выполняться после подтверждения через очередь. Проверяйте communication_jobs: pending, processing, succeeded, cancelled, unknown. Отзыв ключа запрещает новые запросы, но уже подтверждённое намерение отменяется отдельно, пока выполнение не началось.

Файлы и секреты

Передавайте подготовленные ссылки вместо закрытых данных в истории изменений.

capabilities возвращает пути загрузки фотографий, документов, материалов сделки и внешних вложений. Отправляйте байты с нужным Content-Type. Передайте полученный file_ref или asset_id в соответствующее действие без изменения ссылки.

Подготовка вложения не отправляет его клиенту. Приватные файлы доступны только с правами на профиль и конкретный ресурс. MCP читает их ограниченными частями base64; это не открывает общедоступную ссылку.

Пароль почты или секрет подключения передавайте в POST /profiles/{profileId}/secrets. В действие передаётся secret_ref. Ссылка связана с конкретным ключом, профилем и версией политики и имеет срок действия. Не вкладывайте пароль в обычный input или описание задачи.

Вебхуки калькуляторов

Принимайте события в своём обработчике и проверяйте подпись.

Создавайте и настраивайте подписки через quizzes.create_webhook и связанные операции. URL должен быть доступен по HTTPS и пройти проверку внешнего адреса. Набор событий указан в схеме операции. Универсальной подписки на все события CRM пока нет.

Обработчик получает X-Quiz-Signature: sha256=<HMAC-SHA256>. Подпись вычисляется от исходных байтов тела с секретом вебхука. Сравнивайте её безопасным способом до обработки JSON. X-Quiz-Delivery идентифицирует доставку: сохраняйте его, чтобы повтор не создал дубль.

Секрет подписи приходит в результате создания. Храните его отдельно от API-ключа. Быстро подтверждайте принятый запрос успешным HTTP-ответом, а тяжёлую обработку выполняйте в своей очереди.

Ошибки

Проверяйте HTTP-статус, код ошибки и идентификатор запроса.

{
  "error": {
    "code": "insufficient_scope",
    "message": "У ключа недостаточно прав"
  },
  "request_id": "идентификатор-запроса"
}

Пример показывает структуру, а не полный список кодов. При ошибке полей ответ может содержать error.fields. Сохраните request_id для обращения в поддержку, не передавая секретный ключ.

У MCP есть два уровня ошибок: HTTP-ошибка подключения и JSON-RPC error либо result.isError. HTTP 200 сам по себе не означает успешное выполнение инструмента.

Лимиты и версии

Проверяйте действующие возможности перед синхронизацией.

Превышение сложности возвращает 413 request_too_complex до проверки схемы, включая MCP. Разделяйте большие пакеты на запросы. У файлов свои ограничения: используйте capability конкретной загрузки и схему операции.

Версия REST API указана в пути /api/v1. Читайте нужные поля ответа и сохраняйте неизвестные поля совместимыми с клиентом. Там, где список возвращает next_cursor, передайте его следующим параметром cursor; не все списки поддерживают пагинацию.

GET /profiles/{profileId}/actions возвращает актуальные операции и схемы, tools/list — инструменты для текущего ключа. Проверяйте discovery после смены прав, подключения нового профиля или обновления интеграции. В справочнике показан контракт платформы; текущий ключ может видеть только его часть.