Для AI-агентов: markdown этой страницы — /docs/business-settings.md · индекс документации — /llms.txt

Команда и настройки бизнеса

Обновлено 2 октября 2026 г.

Настройте команду, юридический профиль и интеграции своего AI-фронт-офиса в Telegram. Владелец управляет доступом, операторы работают в Telegram-супергруппах Открытых линий, Настроек и Операций. Подключение собственного агента помогает выполнить настройки с рабочего места и сохраняет действующие права человека.

#Перед изменением

Пройдите авторизацию, проверьте активный бизнес и обновите tools/list. Для нового бизнеса сначала завершите нужные шаги первой настройки. Владелец может иметь несколько бизнесов: изменение применяется к контексту credential, а не к произвольному client_id в запросе.

Для MCP используйте реальный предоставленный доступ: person OAuth владельца, tenant API key или headless credential в пределах их полномочий. Для перечисленных ниже REST-маршрутов принимается X-Api-Key либо Authorization: Bearer tgf_*; surface-session JWT и публичный checkout key не подходят. Не передавайте два разных credential одновременно. Точные scopes и live проверки описаны в правах.

Примеры ниже — обезличенные контрактные значения. Адреса example.com, имена и номера иллюстрируют форму запроса; они не подтверждают подключённый сервис или живой аккаунт. REST отвечает DTO непосредственно, без придуманной оболочки {success,data}. MCP возвращает результат через свой стандартный result envelope.

#Приглашение и права оператора

1. Прочитайте list_team_members с {} или GET /api/v1/tools/team. Список возвращает members, статус, идентичность приглашения, флаги и внешний номер seqNum.

2. Согласуйте с владельцем человека и минимальные права. invite_team_member или POST /api/v1/tools/team принимает tg_username и/или email: нужен хотя бы один. Пустая идентичность отклоняется.

3. Для REST POST с телом передайте непустой Idempotency-Key. Пример тела приглашения:

{
  "email": "invite@example.com",
  "permissions": {
    "is_orders_write_allowed": true
  }
}

Ответ REST имеет статус 201. Полный пример: разрешение записи заказов задано явно, остальные флаги остаются выключены.

{
  "seqNum": 8,
  "tgUsername": null,
  "email": "invite@example.com",
  "displayName": "invite@example.com",
  "status": "invited",
  "permissions": {
    "is_contacts_read_allowed": false,
    "is_contacts_write_allowed": false,
    "is_orders_read_allowed": false,
    "is_orders_write_allowed": true,
    "is_orders_status_change_allowed": false,
    "is_payments_read_allowed": false,
    "is_payments_refund_allowed": false,
    "is_catalog_read_allowed": false,
    "is_catalog_write_allowed": false,
    "is_settings_access_allowed": false,
    "is_ai_settings_allowed": false,
    "is_reports_allowed": false
  }
}

Статус invited ещё не даёт доступ. Приглашение по Telegram username связывается с фактически наблюдённым участником операторской супергруппы. Запись с адресом email не означает автоматически подтверждённую Telegram-идентичность.

4. Изменяйте нужного участника по полученному seqNum, передавая его как числовой seq_num в update_team_member или PATCH /api/v1/tools/team. Строка "7" вместо числа 7, внутренний id и поля идентичности в update отклоняются. Пример частичного изменения:

{
  "seq_num": 7,
  "status": "active",
  "permissions": {
    "is_reports_allowed": false,
    "is_orders_write_allowed": true
  }
}

REST PATCH возвращает 200 и полный обновлённый DTO. Неуказанные permission flags сохраняются; tg_username и email в этом запросе изменить нельзя. Допустимые статусы — invited, active, revoked. Участник не становится владельцем через это поле.

5. Для отзыва вызовите revoke_team_member с {"seq_num":7} либо POST /api/v1/tools/team/revoke с тем же телом и новым HTTP idempotency key. Успех REST 201:

{
  "seqNum": 7,
  "revoked": true
}

Отзыв сохраняет запись для аудита. Повторный отзыв уже отозванного участника возвращает revoked:true. Обновление прав и отзыв очищают кеш полномочий tenant: следующий запрос заново проверяет live доступ. Ранее показанный инструмент или уже открытая вкладка не сохраняют отозванное право. Если запись была выполнена, но очистка кеша завершилась ошибкой, не считайте доступ подтверждённым: перечитайте состояние и обработайте отказ.

#Юридический и налоговый профиль

Профиль один на бизнес: get_legal_profile с {} / GET /api/v1/tools/legal. У него нет внешнего идентификатора, который нужно передавать. Платформа не становится продавцом: корректность реквизитов и налоговых настроек относится к вашему бизнесу. Согласуйте данные с ответственным человеком до записи.

update_legal_profile / PATCH /api/v1/tools/legal — частичный строгий patch. Пропущенное поле сохраняется, null очищает значение. Пример тела из контрактной проверки, с вымышленными реквизитами:

{
  "ru_legal_name": "Example RU",
  "ru_inn": "7712345678",
  "ru_taxation_system": "usn_income",
  "ru_default_vat_rate": "vat_22",
  "world_legal_name": "Example World",
  "world_tax_id": "EIN-99",
  "world_default_tax_rate_percent": 8.25
}

Ответ 200 возвращает весь профиль, включая updated_at, блоки ru_*, world_* и ru_zone_activated / world_zone_activated. Указание ru_inn активирует RU-блок, world_tax_id — World-блок. Это состояние профиля не подтверждает готовность платёжного провайдера, фискализацию или законность конкретной продажи; проверьте платежи.

Для РФ ru_taxation_system: osn, usn_income, usn_income_outcome, esn, patent. ru_default_vat_rate: none, vat_0, vat_5, vat_7, vat_10, vat_20, vat_22. Валидатор ограничивает ИНН 12 символами, ОГРН 15, юридический адрес 512, email256 и корректным форматом. Для World ставка — число от 0 до 999; налоговый идентификатор до 64 символов. Схема проверяет форму данных, а не достоверность реквизитов.

#CRM-интеграции

1. Прочитайте list_integrations с {} / GET /api/v1/tools/integrations. Проверяйте isActive, hasCredentials, isAutoDisabled, причину автоматического отключения и статистику отправок. Секреты в ответ не входят.

2. configure_integration / POST /api/v1/tools/integrations принимает дискриминированный credential: Bitrix24 (type:"bitrix24", webhookUrl) или GetCourse (type:"getcourse", account, apiKey). Передавайте реальные секреты только в разрешённом защищённом запросе. Не помещайте их в публичную документацию или чат с посторонними.

3. Сначала согласуйте события и настройки маршрутизации. Этот пример оставляет интеграцию выключенной; URL — искусственный контрактный адрес, а не действующий webhook. Для REST нужен HTTP idempotency key.

{
  "credentials": {
    "type": "bitrix24",
    "webhookUrl": "https://crm.example.com/rest/hook"
  },
  "settings": {
    "pipelineId": "sales",
    "paidStageId": "paid",
    "emailStrategy": "username"
  },
  "subscribed_events": [
    "order.paid"
  ],
  "is_active": false
}

Успех REST 201 возвращает описание настройки, а не credential:

{
  "crmType": "bitrix24",
  "isActive": false,
  "hasCredentials": true,
  "subscribedEvents": [
    "order.paid"
  ],
  "settings": {
    "pipelineId": "sales",
    "paidStageId": "paid",
    "emailStrategy": "username"
  },
  "isAutoDisabled": false,
  "autoDisabledReason": null,
  "statPushesTotal": 17,
  "statPushesFailed": 3,
  "lastPushAt": "2026-09-29T12:00:00.000Z",
  "updatedAt": "2026-09-30T00:00:00.000Z"
}

Настройки имеют закрытый набор полей: pipelineId, defaultStageId, paidStageId, subscriptionCanceledStageId, subscriptionExpiredStatusId, offerCode, emailStrategy. Для emailStrategy допустимы collect, synthetic, username; это настройка интеграции, а не подтверждённая личность покупателя. subscribed_events — до 50 строк длиной до 100 символов. Пропущенные существующие настройки не следует заменять выдуманными пустыми значениями.

4. Для отключения с сохранением конфигурации задайте is_active:false. Для мягкого удаления используйте delete_integration с {"crm_type":"bitrix24"} / POST /api/v1/tools/integrations/delete; REST 201 возвращает {"crmType":"bitrix24","deleted":true}. Это не отзыв credential на стороне внешней CRM: такой доступ отзывают также у её владельца.

#Общие настройки, язык и лимиты

get_client_config / GET /api/v1/tools/client-config возвращает язык операторской зоны, timezone, reporting currency, окна атрибуции, закрытие диалога, настройки AI и остатки токенов. update_client_config / PATCH /api/v1/tools/client-config меняет только разрешённые поля, например:

{"default_language":"ru","timezone":"Europe/Moscow","dialog_auto_close_days":14}

Прочитайте ответ 200 и убедитесь, что значения defaultLanguage, timezone, dialogAutoCloseDays соответствуют решению владельца. tokens_weekly_limit_per_user и tokens_5h_limit_per_user принимают неотрицательное целое или null; null означает отсутствие данного лимита,0 нельзя заменять на пропуск. Остатки tokensAvailableSubscription, tokensAvailablePackage, tokensAvailableBonus доступны только для чтения.

Русский — язык по умолчанию. Язык операторов берётся из настройки бизнеса; язык покупателя — из его пользовательского контекста с RU fallback. .ru и .com — две обязательные зоны запуска с разными юридическими/платёжными требованиями, а не источник прав или язык конкретного оператора. Архитектура допускает расширение языков; эта страница описывает текущий RU-интерфейс.

#Повторы и ошибки

В этих REST-списках нет cursor pagination и условного ETag. Не добавляйте If-Match по аналогии с каталогом. Для POST с непустым телом нужен Idempotency-Key; для PATCH он необязателен. Когда ключ передан, ответ и исходный status сохраняются 24 часа отдельно по tenant, credential, handler и ключу. Изменение тела под тем же ключом —422 IDEMPOTENCY_KEY_MISMATCH, выполняющийся запрос —409 CONFLICT. Для согласованного нового изменения используйте новый ключ. Эти HTTP правила не создают автоматическую идемпотентность каждого MCP вызова.

Для показанного выше приглашения POST /api/v1/tools/team с тем же телом аутентифицированный credential в активном бизнесе, у которого нет team:write, получает следующий отказ на поверхности P3. Это составленный контрактный пример: основные поля подтверждены принятой boundary fixture, а hint добавлен текущим каноническим фильтром ошибок. Он не является записью запроса к живому хосту или подтверждением созданного приглашения.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

Полное тело ответа:

{
  "type": "https://telegafirst.ru/docs/errors#INSUFFICIENT_SCOPE",
  "title": "Forbidden",
  "status": 403,
  "instance": "/api/v1/tools/team",
  "code": "INSUFFICIENT_SCOPE",
  "traceId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "detail": "Missing required scope(s): team:write",
  "hint": {
    "reason": "The credential lacks a scope this operation requires.",
    "recovery": "Compare missing_scopes at GET /api/v1/me with this operation and use a key that includes them."
  }
}

Сравните отсутствующий team:write с описанием доступа и используйте credential с этим scope, выданный для нужного бизнеса. Полномочия владельца и текущие права всё равно проверяются; наличие другого scope не разрешает приглашение. Разберите отказ до повторной попытки.

Успешные REST-ответы несут X-Client-Slug, X-Bot-Username, когда они доступны, и X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Сначала проверьте бизнес, затем status и тело. Числовой seqNum участника — адрес P3 за проверкой tenant; он не превращается в публичную ссылку. Внутренние PK никогда не нужны клиенту.

Управление деньгами рассматривается отдельно в продажах и платежах: агент клиента использует scoped Hub, подготовку сценария, проверку человеком и финальное подтверждение перед исполнением. Внутренние Qualifier/Manager/Coach только советуют и передают разговор человеку. Для сайта и форм продолжите публикацию.