Документация Site-Inbox

Приём событий сайта и управление входящими. Site Token и управляющий API-ключ имеют разные назначения.

Быстрый старт

Добавьте сайт в мастере подключения.
Сохраните выданный Site Token.
Отправьте событие на endpoint нужного типа.
Проверьте входящую запись и настройте Telegram.

curl -X POST https://api.site-inbox.ru/api/v1/ingest/lead \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_SITE_TOKEN' \
  -d '{"external_id":"contact-1042","name":"Иван","email":"ivan@example.com","message":"Нужна консультация","source":"contact-form","utm_source":"yandex"}'

Входящие сущности

Endpoint POST	Поля	Раздел
`/api/v1/ingest/lead`	name, email, phone, message	Лиды
`/api/v1/ingest/access_request`	name, email, message	Лиды: запрос доступа
`/api/v1/ingest/registration`	name, email, metadata	Регистрации
`/api/v1/ingest/comment`	author_name, author_email, content, post_id	Комментарии
`/api/v1/ingest/review`	author_name, rating, rating_max, title, content, post_id	Отзывы
`/api/v1/ingest/payment`	external_id, amount, currency, status, order_id	Оплаты

Для лида достаточно полей, доступных вашей форме; email не обязателен для телефонного обращения. Для комментария обязателен непустой content. Передавайте external_id для надёжной защиты от повторов. Без ID идентичные обращения объединяются в течение пяти минут.

В настройках сайта можно включить создание связанного лида из регистрации или успешной оплаты. Исходная запись остаётся в своём разделе. Существующие исторические записи автоматически не переносятся.

Любые поля форм

Отправляйте форму как есть: JSON, application/x-www-form-urlencoded или multipart/form-data. Стандартные поля распознаются по названию, в том числе по русским подписям и именам полей Tilda, Contact Form 7, Elementor: «Ваше имя», «Контактный телефон», «E-mail», «Сообщение», fio, tel, your-email и подобные. Все остальные поля сохраняются в metadata под исходными названиями и видны в карточке записи.

{
  "Ваше имя": "Ольга",
  "tel": 79001112233,
  "Город": "Казань",
  "Площадь, м²": 54,
  "Услуги": ["Ремонт", "Дизайн"]
}
→ name: "Ольга", phone: "79001112233",
  metadata: { "Город": "Казань", "Площадь, м²": 54, "Услуги": ["Ремонт", "Дизайн"] }

Поддерживаются массивы вида [{"name": "…", "value": "…"}] и контейнер fields конструкторов форм. Пароли, токены капчи, CSRF-токены и данные банковских карт не сохраняются. Числа и списки в стандартных полях приводятся к тексту. Слишком большие наборы полей сокращаются до 64 КБ.

Отзывы

Отзывы с оценкой хранятся отдельно от комментариев и показываются в разделе «Отзывы». Модерация такая же: pending, approved, rejected. Оценка принимается числом, дробью 4/5, текстом 8 из 10 или звёздами ★★★★☆. Шкала по умолчанию — 5; для оценок до 10 и до 100 она определяется автоматически, либо передайте rating_max. Текст отзыва не обязателен.

curl -X POST https://api.site-inbox.ru/api/v1/ingest/review \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_SITE_TOKEN' \
  -d '{"author_name":"Анна","rating":5,"title":"Быстрая доставка","content":"Всё пришло вовремя","post_id":"product-17","Достоинства":"цена"}'

Через вебхук отзыв отправляется с полем type=review. Уведомления об отзывах подчиняются настройкам уведомлений о комментариях; лимит тарифа общий с комментариями.

Оплаты и события заказа

{
  "external_id": "order-1042-paid",
  "order_id": "1042",
  "amount": "4900.00",
  "currency": "RUB",
  "status": "succeeded",
  "name": "Иван",
  "email": "ivan@example.com",
  "source": "woocommerce",
  "metadata": {
    "product": "Подписка",
    "tariff": "Про"
  }
}

Сумму рекомендуется передавать десятичной строкой с максимум двумя знаками после точки; запись вида «1 234,50 ₽» тоже принимается. Валюта — трёхбуквенный код. Статусы: checkout, pending, succeeded, failed, refunded; значения paid, success, canceled, refund и подобные приводятся к ним, а нераспознанный статус сохраняется в metadata. external_id идентифицирует событие, order_id связывает разные состояния одного заказа. Для изменения состояния отправляйте новое событие с новым external_id.

Site-Inbox учитывает переданные события. Подтверждать платежи у платёжного провайдера должен ваш сервер; сервис не проводит денежные операции.

Источник и дополнительные поля

Поле	Назначение	Поведение
`external_id`	ID события	Для оплат обязателен. Повтор ID в пределах сайта и типа возвращает ту же запись.
`page_url`	URL страницы	Адрес страницы источника.
`source`	Источник	Название обработчика или сервиса.
`form_id`	Форма	ID или название формы.
`referrer`	Реферер	Адрес страницы, с которой пришёл посетитель.
`utm_source / utm_medium`	UTM	Источник и канал кампании.
`utm_campaign / utm_content / utm_term`	UTM	Кампания, объявление и ключевая фраза.
`metadata`	Объект JSON	Ваши дополнительные поля; сохраняются без потери структуры. Поля верхнего уровня, которых нет в этом списке, тоже попадают сюда.

Поля источника доступны для всех потоков. Явное поле запроса имеет приоритет перед metadata; UTM также извлекаются из page_url, если не переданы отдельно. JS-скрипт сохраняет UTM посещения и добавляет их к форме.

Управляющий API

Создайте ключ в «Коннекторах». Передавайте Authorization: Bearer YOUR_API_KEY. Ключ можно ограничить конкретным сайтом и сроком действия. Site Token не даёт доступ к управлению чужими входящими.

Ключ без привязки к сайту управляет всем аккаунтом: добавляет и настраивает сайты, выпускает и отзывает ключи. Ключ сайта видит только свой сайт и может менять его настройки приёма и уведомлений.

GET    /api/v1/account                      тариф, лимиты, расход за месяц
GET    /api/v1/sites                        сайты с настройками и URL вебхука
POST   /api/v1/sites                        {name, url, ...настройки} → ingestKey и инструкция
GET    /api/v1/sites/UUID
PATCH  /api/v1/sites/UUID                   accept_reviews, notify_telegram_leads, telegram_connector_ids…
DELETE /api/v1/sites/UUID?confirm=true      удаляет сайт и все его записи
GET    /api/v1/sites/UUID/integration       endpoints, поля, примеры кода
POST   /api/v1/sites/UUID/rotate-ingest-key
POST   /api/v1/sites/UUID/rotate-webhook
GET    /api/v1/api-keys
POST   /api/v1/api-keys                     {name, site_id?, expires_at?} → key
DELETE /api/v1/api-keys/UUID
GET    /api/v1/connectors                   Telegram-чаты для маршрутизации

GET    /api/v1/leads | registrations | comments | reviews | payments
         ?site_id=UUID&status=…&search=…&since=…&until=…&limit=50&cursor=…
GET    /api/v1/{раздел}/UUID
DELETE /api/v1/{раздел}/UUID
POST   /api/v1/{раздел}                     site_id + поля события
PATCH  /api/v1/leads/UUID
GET    /api/v1/leads/UUID/notes
POST   /api/v1/leads/UUID/notes
PATCH  /api/v1/comments/UUID | reviews/UUID {status}

Списки отдаются от новых к старым. Если в ответе есть nextCursor, передайте его в cursor для следующей страницы. Поиск идёт по имени, email, тексту и всем дополнительным полям; для отзывов есть фильтр min_rating.

Для POST передавайте site_id вместе с полями события. Для PATCH лида доступны status, assignee_name и reminder_at. Время напоминания должно содержать часовой пояс: 2026-10-05T15:00:00+07:00. Значение null отменяет напоминание.

Статусы лида: new, in_progress, replied, archived, spam, won, lost. Статусы комментария: pending, approved, rejected. Массовые действия и экспорт всех результатов доступны в кабинете.

MCP для AI-ассистентов

{
  "mcpServers": {
    "site-inbox": {
      "url": "https://api.site-inbox.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Транспорт — HTTP POST JSON-RPC. Доступен на тарифах Про и Агентский. Через MCP ассистент управляет аккаунтом полностью, без входа в кабинет.

Аккаунт и сайты: get_account, list_sites, find_site, get_site, create_site, update_site, delete_site, get_site_integration, rotate_site_ingest_key, rotate_site_webhook.
Ключи и уведомления: list_api_keys, create_api_key, revoke_api_key, list_connectors, list_telegram_chats, get_delivery_status.
Данные: list_leads, list_registrations, list_comments, list_reviews, list_payments, get_record, delete_record, create_lead, create_registration, create_comment, create_review, create_payment, update_lead, update_lead_status, add_lead_note, moderate_comment, moderate_review.

Поля источника и metadata возвращаются вместе с сущностями. При создании события используйте site_id и объект data с теми же полями, что у Ingest API. Все операции ограничены областью ключа.

Telegram, очередь и напоминания

Укажите Bot Token и Chat ID в «Коннекторах». Выберите виды событий. Уведомление сохраняется в PostgreSQL вместе с событием, затем отправляется рабочим процессом. Временные ошибки и HTTP 429 повторяются до десяти попыток с увеличением интервала; постоянные ошибки доступа попадают в журнал сразу.

Очередь выдерживает перезапуск процесса. В разделе «Доставка уведомлений» можно увидеть состояние и повторить неудачную отправку. Напоминание создаёт отдельное уведомление в установленный момент; если Telegram не подключён, оно остаётся просроченной задачей в панели.

После сетевого обрыва на границе успешного ответа Telegram повтор теоретически может доставить уведомление второй раз: Telegram sendMessage не предоставляет идемпотентность. Входящая запись при этом остаётся единственной.

Ответы и ошибки

201: { "success": true, "data": { "id": "UUID", "deduplicated": false } }
200: { "success": true, "data": { "id": "UUID", "deduplicated": true } }
400: некорректные поля
401: неверный токен
402: месячный лимит
403: поток отключён или нет доступа
429: слишком много запросов
500: временная ошибка сервера

Повторяйте временно неудавшиеся запросы с тем же external_id. Site Token ограничен 100 запросами в минуту. Управляющий API и MCP имеют отдельные лимиты тарифа.