DEVELOPER PLATFORM · V1

Ваши сервисы. Общий контекст.

Используйте BotDock как сервер диалогов и автоматизации: читайте профили, отправляйте сообщения, запускайте операции и принимайте внешние события.

OpenAPI JSON ↗SDK Python ↓SDK JavaScript ↓

1. Создайте ключ проекта

В проекте откройте «Журнал и API». Выберите только необходимые права. Ключ показывается один раз, действует в пределах проекта и отзывается там же. Ключи предназначены для серверов, не для кода в браузере или мобильном приложении.

Authorization: Bearer bd_…

Права: profiles:read, profiles:write, messages:write, events:write, integrations:read, integrations:run, payments:read, payments:write, audit:read. Лимит — 120 запросов в минуту на ключ. Очереди и дневной лимит проекта ограничиваются отдельно.

2. Найдите аккаунт клиента

Профиль объединяет подтверждённые аккаунты. Для отправки сообщения или события выберите identities[].id из нужного канала.

GET /api/v1/projects/PROJECT_ID/profiles?channel_id=CHANNEL_ID&external_id=USER_ID
GET /api/v1/projects/PROJECT_ID/profiles/PROFILE_ID
PATCH /api/v1/projects/PROJECT_ID/profiles/PROFILE_ID
{"state":{"customer_id":"42"},"access":{"premium":{"enabled":true}}}

PATCH заменяет переданные поля целиком. access — ручные права; оплаченный доступ хранится отдельно. Состояние общего профиля доступно во всех связанных каналах.

3. Отправьте сообщение или запустите операцию

POST /api/v1/projects/PROJECT_ID/messages
Idempotency-Key: order-42-notification-v1
{"identity_id":"IDENTITY_ID","text":"Заказ готов!"}

POST /api/v1/projects/PROJECT_ID/operations/OPERATION_ID/runs
Idempotency-Key: order-42-sync-v1
{"input":{"customer_id":"42"},"environment":"sandbox"}

GET /api/v1/projects/PROJECT_ID/jobs/JOB_ID

Ответ 202 означает постановку в очередь. Повторяйте запрос с тем же Idempotency-Key и тем же телом. sandbox возвращает mock без сети; live выполняет действие. Для платежа обязательны identity_id и права integrations:run + payments:write. Неизвестный результат записи не повторяется автоматически.

4. События, расписания и вебхуки

POST /api/v1/projects/PROJECT_ID/events
{"event_id":"order-42-paid","identity_id":"IDENTITY_ID","text":"/order_paid","data":{"order_id":"42"}}

GET /api/v1/projects/PROJECT_ID/audit?after=0

event_id защищает от дублей. Событие проходит опубликованный сценарий с текущим состоянием диалога; если он ждёт ответ, текст события заполнит ожидаемое поле. Системные команды привязки из внешних событий не выполняются. Данные доступны в шаблоне входа интеграции: {{event.order_id}}. Журнал возвращает next_cursor для следующего опроса.

Для входящего вебхука создайте получателя во вкладке интеграций и подпишите исходные байты JSON: HMAC-SHA256(secret, timestamp + "." + body). Передайте X-BotDock-Timestamp (Unix seconds) и X-BotDock-Signature (hex). Допуск времени — 5 минут. Исходящие подписанные вебхуки настраиваются как HTTP POST с signing_secret в подключении.

Платежи

Готовый адаптер ЮKassa: создание ссылки, сверка с API, срок доступа и полный возврат. Конечная стоимость задаётся владельцем операции. Уведомление о платеже лишь запускает сверку — не выдаёт доступ. Тестовый магазин никогда не выдаёт реальное право. Автосписания и частичные возвраты не реализованы.

GET /api/v1/projects/PROJECT_ID/payments
POST /api/v1/projects/PROJECT_ID/payments/ORDER_ID/refund
Idempotency-Key: refund-order-42-v1
{"receipt":null}

Формат receipt соответствует API ЮKassa. Настройте чеки под свой магазин. Для возврата требуется payments:write; уже поставленный возврат не создаётся повторно.

Ваши методы и чат сайта

В проекте появился «Конструктор API»: входные поля, сохранённая операция, поля результата, версии и отдельные ключи ep_. Кнопка OpenAPI скачивает контракт конкретной версии. POST /api/published/PROJECT/SLUG/vVERSION принимает задание, GET возвращённого status_url показывает результат. Ключи методов предназначены для вашего backend.

Раздел «Сайты» создаёт отдельный webchat-канал: встраиваемый script, разрешённые домены, сессии посетителей и кнопка оператора. Есть WordPress-плагин, PHP-заготовка 1С-Битрикс и инструкции Tilda/HTML. Посетители не используют ключи проекта. Подробная инструкция поставляется в docs/EXPERIENCE.md.

Таблицы и аналитика

Новые права: data:read, data:write, analytics:read. GET /tables; GET /tables/TABLE_ID/rows?environment=live; POST /tables/TABLE_ID/rows с Idempotency-Key и JSON {environment, rows, replace, revision}; GET /analytics?environment=live&days=30. Запись по умолчанию использует sandbox. Для replace=true обязательна revision.

Полный справочник и примеры → · Google Sheets / Docs → · OpenAPI всей панели (требует входа) →

Процессы без ИИ

POST /workflows/WORKFLOW_ID/run (workflows:run, Idempotency-Key), GET /workflow-runs/RUN_ID (workflows:read), POST /automation-events (events:write, event_id, source=custom.*, environment, data). Пути относительно /api/v1/projects/PROJECT_ID. Схемы и SDK →

Профили и проверка черновика

Новые методы центра привязок, проверки черновика и готовности доступны через сессию владельца и CSRF-токен. Публичные ключи проекта не получают эти полномочия автоматически. Запрос Mini App VK проверяет подписи и одноразовый запрос. Контракт и ограничения →

Методы API

Загружаем спецификацию…

BotDock 0.12.0 · Пилот. Локальная документация не загружает сторонние скрипты.