API управления бизнесом

Раздел «Платформа» описывает административный API Gigma. Через него сотрудники, внутренние сервисы и MCP-агенты управляют бизнесом: настраивают приложения, ведут каталог и остатки, работают с клиентами и заказами, публикуют контент и получают операционные справочники.

Клиентский интерфейс сайта или приложения использует другой контур — «Сайты и приложения». Не передавайте Bearer сотрудника или агента в браузерную витрину и не заменяйте им App Token или Counterparty Bearer. App Token в прямой frontend-интеграции виден пользователю и сам по себе не подтверждает личность клиента, оплату или право доступа.

Что можно автоматизировать

• доступ сотрудников и MCP-агентов, роли и проектные ограничения;
• бизнесы, реквизиты, приложения и webhooks;
• товары, услуги, категории, бренды и подписочные тарифы;
• склады, остатки, импорт, резервы и точки выдачи;
• стратегии продаж, акции, скидки и промокоды;
• клиентов, заказы, возвраты и задачи команды;
• страницы, контентные блоки, меню и файлы.

Кто обращается к API

Большинство методов платформы требуют заголовок:

Authorization: Bearer <access_token>

Для сотрудника это токен после обычного входа. Для MCP-агента — отдельный токен, выданный через согласование владельца или административный API. Точные права, обязательные заголовки и ограничения смотрите в карточке конкретного endpoint.

Основная модель

Project задаёт границу доступа. Наличие числового id не подтверждает право на объект: backend и интеграция должны проверять, что пользователь или агент и ресурс относятся к одному проекту.

С чего начать

Подключить сотрудника

1. Создайте сотрудника в нужном проекте и выдайте минимально необходимые права.
2. Запросите одноразовый пароль через POST /api/send_password.
3. Выполните вход через POST /api/login и сохраните Bearer как секрет.
4. Получите GET /api/user, чтобы проверить текущего пользователя, роль и permissions.

Подробный контракт находится на странице «Доступ сотрудников».

Подключить MCP-агента

Парольный вход агенту запрещён: /api/send_password и /api/login возвращают 403 для учётных записей с is_agent = true.

Используйте один из двух flow:

1. MCP-клиент создаёт POST /api/agent-access-requests, владелец подтверждает запрос, клиент проверяет статус и один раз забирает Agent Token через consume.
2. Сотрудник с правами управления агентами создаёт POST /api/agents, затем выпускает токен через POST /api/agents/{agent}/tokens.

После выдачи токена внешний MCP-сервер выполняет обычные ERP endpoints — например, /api/orders, /api/counterparties и /api/nomenclatures. Отдельного /api/mcp/* в backend нет. Проверку подключения и рабочие allowlist-профили смотрите в разделе «MCP: рабочие методы», самостоятельное согласование — в [«Получении доступа»](/ERP/МСП/Получение доступа/), а ручное создание и ротацию токенов — в [«Управлении агентами»](/ERP/МСП/Управление агентами/).

Запустить сайт, приложение или новый канал

1. Создайте или выберите бизнес и реквизиты.
2. Создайте Application и настройте webhooks.
3. Подготовьте каталог товаров и услуг.
4. Настройте склады и остатки.
5. При необходимости добавьте стратегии продаж, акции и скидки и магазины.
6. Для клиентского интерфейса перейдите в раздел «Сайты и приложения».

Автоматизировать работу с заказами

1. Получите или создайте клиента или контрагента.
2. Создайте либо найдите заказ.
3. Проверьте доступность товара по остаткам и существующим резервам.
4. Назначьте задачу сотруднику, если заказ требует ручного действия.
5. После неизвестного результата записи сначала повторно прочитайте состояние, а не создавайте вторую операцию вслепую.

Управлять контентом продукта

Используйте контентные блоки для отдельных элементов интерфейса, страницы и публикации для материалов по slug, меню сотрудников для административной навигации и файлы для загрузки медиа и документов.

Меню сотрудников из платформенного API и клиентское меню из раздела «Сайты и приложения» — разные модели. Не смешивайте их в одной интеграции.

Ресурсный и табличный ответы

Для части сущностей Gigma предоставляет две поверхности:

Табличный ответ может содержать UI-обёртки вида { icon, value, link } и не обязан совпадать с ресурсным ответом. Для серверной интеграции выбирайте ресурсный endpoint, если он поддерживает нужный сценарий; табличный используйте, когда действительно нужны колонки и представление административного интерфейса.

Навигация называет пользовательскую задачу, поэтому пункт «Доступ сотрудников» ведёт на каноническую страницу ресурса «Авторизация», а «Каталог товаров и услуг» — на страницу «Номенклатура». Заголовок подробной страницы и карточка endpoint остаются источником истины для конкретного HTTP-контракта. Обзор /ERP/ объясняет порядок работы, но не дублирует и не переопределяет endpoint.

Карта документации

Правила безопасной интеграции

• храните Bearer сотрудника или агента как секрет и не помещайте его в URL, аналитику или публичные клиентские логи;
• создавайте отдельный agent account для каждого профиля permissions; отдельный Agent Token используйте для каждой установки и ротации, а не как замену отдельным правам;
• выдавайте только те permissions, которые нужны конкретному сценарию;
• не выбирайте project_id произвольно и не пытайтесь обходить 403 или 404 подбором других ID;
• значения справочников получайте из API, а не фиксируйте по примерам документации;
• перед массовым изменением, возвратом денег или удалением добавляйте подтверждение и журналирование;
• при сетевом сбое после write-запроса сначала сверяйте текущее состояние ресурса.