# Команда и настройки бизнеса Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: f293274b4dacf24b6c28f5533493ad99837228d50838b09d8a340a00fabba2a9 Version: 1 Настройте команду, юридический профиль и интеграции своего AI-фронт-офиса в Telegram. Владелец управляет доступом, операторы работают в Telegram-супергруппах Открытых линий, Настроек и Операций. Подключение собственного агента помогает выполнить настройки с рабочего места и сохраняет действующие права человека. ## Перед изменением Пройдите [авторизацию](https://telegafirst.com/docs/authorization), проверьте активный бизнес и обновите `tools/list`. Для нового бизнеса сначала завершите нужные шаги [первой настройки](https://telegafirst.com/docs/getting-started#new-business). Владелец может иметь несколько бизнесов: изменение применяется к контексту 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 проверки описаны в [правах](https://telegafirst.com/docs/scopes-and-permissions). | Настройка | Чтение | Запись | Кто вправе менять | | -------------------- | -------------------- | --------------------- | --------------------------------------- | | Команда | `team:read` | `team:write` | Владелец; оператор не выдаёт себе права | | Юридический профиль | `legal:read` | `legal:write` | Владелец | | CRM-интеграции | `integrations:read` | `integrations:write` | Владелец | | Язык, время и лимиты | `client-config:read` | `client-config:write` | Владелец | Примеры ниже — обезличенные контрактные значения. Адреса `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`. Пример тела приглашения: ```json { "email": "invite@example.com", "permissions": { "is_orders_write_allowed": true } } ``` Ответ REST имеет статус 201. Полный пример: разрешение записи заказов задано явно, остальные флаги остаются выключены. ```json { "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 отклоняются. Пример частичного изменения: ```json { "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: ```json { "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` очищает значение. Пример тела из контрактной проверки, с вымышленными реквизитами: ```json { "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-блок. Это состояние профиля не подтверждает готовность платёжного провайдера, фискализацию или законность конкретной продажи; проверьте [платежи](https://telegafirst.com/docs/payments). Для РФ `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. ```json { "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: ```json { "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` меняет только разрешённые поля, например: ```json {"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 HTTP/1.1 403 Forbidden Content-Type: application/problem+json ``` Полное тело ответа: ```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 | Действие | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | 400 `VALIDATION_ERROR` | Исправьте конкретное поле: строгие схемы не принимают `id`, `client_id` и неизвестные permissions | | 400 `IDEMPOTENCY_KEY_REQUIRED` | Для POST с телом передайте непустой ключ | | 401 `INVALID_API_KEY` | Проверьте credential, его отзыв и транспорт; surface JWT не подходит | | 403 `INSUFFICIENT_SCOPE`, `NO_ACTIVE_BOT`, `PUBLISHABLE_KEY_NOT_ALLOWED` | Восстановите предусмотренные права/контекст; публичный ключ не становится ключом настроек | | 404 `NOT_FOUND` | Для team update/revoke перечитайте свой список и используйте номер участника своего tenant | | 409 `CONFLICT` | Разберите конфликт приглашения или выполняющегося запроса до повтора | | 413 `PAYLOAD_TOO_LARGE`, `ITEM_COUNT_EXCEEDED` | Уменьшите запрос согласно бюджету операции | | 429 `RATE_LIMIT_EXCEEDED`, `RATE_LIMIT_UNAVAILABLE` | Соблюдайте `Retry-After`, если он присутствует; отказ подсистемы не обходят | | 500 `INTERNAL_ERROR` | Сохраните `traceId` для диагностики; успех изменения не предполагается | Успешные REST-ответы несут `X-Client-Slug`, `X-Bot-Username`, когда они доступны, и `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Сначала проверьте бизнес, затем status и тело. Числовой `seqNum` участника — адрес P3 за проверкой tenant; он не превращается в публичную ссылку. Внутренние PK никогда не нужны клиенту. Управление деньгами рассматривается отдельно в [продажах](https://telegafirst.com/docs/catalog-and-sales) и [платежах](https://telegafirst.com/docs/payments): агент клиента использует scoped Hub, подготовку сценария, проверку человеком и финальное подтверждение перед исполнением. Внутренние Qualifier/Manager/Coach только советуют и передают разговор человеку. Для сайта и форм продолжите [публикацию](https://telegafirst.com/docs/sites-storefront-and-forms).