Zapnoty — Virtual Projects — AI-настройка проекта

Virtual Projects — AI-настройка проекта

AI-агенты создают и настраивают проект Zapnoty от имени пользователя. Пользователю остаётся подтвердить готовый проект кнопкой Accept в кабинете — без чтения документации, без копирования API-ключей.

Сценарий

Пользователь говорит AI-агенту (Claude, Cursor): «Подключи мне Zapnoty для рассылок».
AI спрашивает email и вызывает POST /v1/virtual-projects с конфигом (permissions, templates, webhook).
В ответ получает temp_api_key (zn_virt_…), accept_url и virtual_project_id. Дополнительно настраивает через CRUD-эндпоинты с этим ключом.
AI сообщает пользователю: «Готово. Откройте app.zapnoty.ru с указанным email, нажмите Принять».
Пользователь логинится magic-link, видит проект с бейджем «AI подготовил», жмёт Accept — получает постоянный zn_live_ ключ. Старый zn_virt_ инвалидируется.

API

Публичный POST /v1/virtual-projects (без API-ключа). Rate-limit: 5/час и 30/сутки на IP создателя. UNIQUE на target_email среди pending: одновременно один pending проект на email.

POST /v1/virtual-projects

{

"owner_email": "user@example.com",

"name": "MyApp Notifications",

"slug": "myapp",

"config": {

"sender_name": "MyApp",

"permissions": [

{"key": "orders", "title": "Заказы", "required": true}

"webhook": {"url": "https://myapp.com/webhook"}

}

Ответ

{

"virtual_project_id": "550e8400-...",

"temp_api_key": "zn_virt_...",

"expires_at": "2026-05-20T19:00:00Z",

"accept_url": "https://app.zapnoty.ru/accept-virtual/{id}",

"status": "virtual_pending"

}

GET /v1/virtual-projects/{id}/status

Публичный, без auth. AI может polling-ом проверять — принял ли пользователь. Возвращает один из: virtual_pending / active / expired.

Ограничения временного ключа

zn_virt_<key> используется для настройки, но не для runtime-операций. Это снимает риск что AI начнёт слать кому-то спам до согласия пользователя.

Заблокировано: /v1/send, /v1/send/preview, /v1/otp/*, /v1/broadcast, /v1/auth/session, /v1/helpdesk/tickets, /v1/helpdesk/request — всё что отправляет / создаёт сессии.

Разрешено: CRUD permissions/templates/tags/webhook/sender/auto-messages/scheduled. AI может всё подготовить, проверить через zapnoty_list_setup.

TTL: 24 часа. Если пользователь не нажмёт Accept за это время — cleanup-воркер удалит проект автоматически. AI получит status=expired.

Защита от абьюза: 5 virtual-проектов в час и 30 в сутки на IP создателя. UNIQUE constraint на target_email — нельзя засрать чужой акаунт несколькими pending-проектами.

MCP-сервер (mcp.zapnoty.com)

Чтобы AI-агенты автоматически знали про Zapnoty API, мы предоставляем MCP-сервер. AI-клиент подключается один раз, потом инструменты доступны во всех диалогах.

Claude Desktop

claude mcp add zapnoty https://mcp.zapnoty.com/mcp

Cursor / Continue / Goose

{

"mcpServers": {

"zapnoty": {

"url": "https://mcp.zapnoty.com/mcp"

}

Доступные инструменты

zapnoty_create_virtual_project — создать pending-проект → вернуть temp_api_key и accept_url

zapnoty_check_status — проверить статус (pending / active / expired)

zapnoty_create_template — добавить шаблон сообщения

zapnoty_create_permission — добавить разрешение (категорию)

zapnoty_create_tag — добавить тег для сегментации

zapnoty_set_webhook — настроить webhook URL и события

zapnoty_list_setup — свести текущий setup (permissions + templates + tags)

Безопасность и защита от абьюза

До Accept проект не работает: нельзя отправить ни одного сообщения, ни OTP, ни webhook-события не отправляются.
При Accept zn_virt_<key> инвалидируется — генерируется новый zn_live_<key>. Если AI сохранил temp ключ, после Accept он бесполезен (401).
Публичные формы /f/{form_id} для virtual_pending проекта тихо возвращают 200 без записи — чтобы не палить факт pending перед внешним атакующим.
Один pending проект на email одновременно. Атакующий не может массово создавать virtual'ы для чужой почты.
Rate-limit 5/час, 30/сутки на IP создателя — защита от флуда БД. Cleanup-воркер удаляет expired записи через 24h.