Akeda Settings members API

openapi: 3.2.0
info:
  title: Akeda ERP Client Settings members API
  version: 0.21.0-core-public
  summary: Проверяемый публичный контракт Go API Akeda ERP
  license:
    name: Proprietary
    identifier: LicenseRef-Akeda-Proprietary
  description: 'Этот контракт описывает API Akeda ERP. Полный исходный файл используют

    проверки живых Go-маршрутов, внутренние клиенты и реестр MCP. Скачиваемый

    клиентский контракт в `/docs` содержит только отобранные внешние методы;

    административные методы кабинета показаны отдельно после входа, а

    платформенные операторские методы остаются во внутреннем источнике.

    Стадия `public` означает обещание совместимости; `preview` допускает

    изменение формы. Аудитория, стадия и `security` — разные признаки:

    наличие метода в полном файле само по себе не выдаёт вызывающему право.

    Сервер отдельно проверяет тип токена, кабинет, scope и права на запись.

    Актуальные числа покрытия берите из генерируемой карты маршрутов и

    каталога покрытия, а не из описательного текста.'
servers:
- url: https://erp.akeda.ru
  description: PROD
security:
- erpUserToken: []
- tenantApiKey: []
- mcpOAuth:
  - akeda:delegate
tags:
- name: Settings members
  description: Модуль settings (участники, роли, юрлица) — участники кабинета
paths:
  /api/v1/settings/members:
    get:
      tags:
      - Settings members
      operationId: settingsListMembers
      summary: Получить участников кабинета
      description: Отдаёт участников кабинета по логину без страниц. Без параметра status в выдачу попадают только действующие участники.
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - disabled
          - all
        description: Умолчание — active; disabled отдаёт только отключённых участников
      responses:
        '200':
          description: Участники кабинета
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsMemberPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Settings members
      operationId: settingsCreateMember
      summary: Завести участника кабинета
      description: 'Заводит нового человека в общем реестре платформы и его членство в кабинете. Занятый логин отклоняется с 409 до создания учётной записи: прицепить чужого человека к своему кабинету этим маршрутом нельзя. Тем же 409 отвечает исчерпанная квота мест тарифа — и тоже ДО создания учётной записи, иначе в реестре осталась бы висячая identity, которой некуда войти. Если внешний сервис входа не смог создать учётную запись, ответ 502.'
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings:write
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsMemberCreateInput'
      responses:
        '201':
          description: Созданный участник
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsMember'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          description: Сервис входа не создал учётную запись
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/settings/members/{id}/access:
    put:
      tags:
      - Settings members
      operationId: settingsReplaceMemberAccess
      summary: Заменить бизнесы сотрудника
      description: 'Записывает область сотрудника целиком: все бизнесы кабинета, включая заведённые позже, или перечисленные бизнесы, внутри бизнеса — при желании только выбранные юрлица. Роль у сотрудника одна и меняется правкой участника; область сужает данные каждого права роли. Отказ с кодом settings.access.* — 400: нет бизнесов, бизнес не найден, юрлицо чужого бизнеса. Администратор кабинета работает во всех бизнесах, сузить его область нельзя — 409 settings.access.admin_all_businesses.'
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings:write
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsMemberAccessInput'
      responses:
        '200':
          description: Участник с новой областью
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsMember'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          description: Справочник бизнесов кабинета недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/settings/members/{id}/activation:
    post:
      tags:
      - Settings members
      operationId: settingsSetMemberActive
      summary: Закрыть или вернуть доступ участника
      description: is_active false закрывает доступ в этом кабинете со следующего запроса; другие кабинеты человека остаются. true возвращает доступ и при занятых местах тарифа отвечает 409. Отключить себя или последнего действующего администратора нельзя — 409. Логин, имя и фото здесь не меняются.
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings.team:write
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - is_active
              properties:
                is_active:
                  type: boolean
                  description: false закрывает доступ, true возвращает
      responses:
        '200':
          description: Участник после изменения
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsMember'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /api/v1/settings/members/{id}/role:
    put:
      tags:
      - Settings members
      operationId: settingsSetMemberRole
      summary: Сменить роль участника
      description: 'Ставит участнику его единственную роль; null снимает роль. Область бизнесов участника не меняется: административная роль сама открывает все бизнесы. Снять роль с последнего действующего администратора нельзя — 409. Логин, имя и фото здесь не меняются.'
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings:write
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - role_id
              properties:
                role_id:
                  oneOf:
                  - $ref: '#/components/schemas/UUID'
                  - type: 'null'
                  description: Роль из списка ролей; null снимает роль
      responses:
        '200':
          description: Участник после изменения
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsMember'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /api/v1/settings/role-assignments:
    post:
      tags:
      - Settings members
      operationId: settingsAssignMemberRoles
      summary: Назначить роли участникам пачкой
      description: 'До 200 строк «участник → роль» за один вызов. Участник называется ровно одним способом: member_id (членство из списка участников), employee_id (карточка «Команды», уже связанная с учётной записью) или email (логин участника либо рабочая почта его карточки). Роль — role_id или role_name. all_businesses или businesses задают область, как у замены бизнесов участника; без них область не меняется, а административная роль сама открывает все бизнесы. Проверки — те же, что у одиночной смены роли и замены бизнесов: роль действующая и не шире прав назначающего, участник с ролью шире этих прав недоступен, бизнесы не шире своих, кабинет не остаётся без активного администратора (счёт идёт с учётом строк выше). Свою роль пачкой не меняют — строка settings.members.batch.self. Строки обрабатываются независимо, ответ 200 называет исход каждой: updated, unchanged или error с кодом. Человек, ещё не принявший приглашение, участником не считается: его роль задаёт приглашение. dry_run true ничего не записывает и отдаёт тот же отчёт.'
      x-akeda-module: settings
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: settings:write
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsRoleAssignmentBatchInput'
      responses:
        '200':
          description: Отчёт по строкам назначения
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsRoleAssignmentBatchResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    SettingsMemberAccessInput:
      type: object
      additionalProperties: false
      properties:
        all_businesses:
          type: boolean
          description: Все бизнесы кабинета; тогда businesses не передаётся
        businesses:
          type: array
          items:
            $ref: '#/components/schemas/SettingsMemberBusinessScope'
          description: Бизнесы сотрудника целиком; повторы и юрлица бизнеса, выданного целиком, сворачиваются
    SettingsRoleAssignmentBatchInput:
      type: object
      additionalProperties: false
      required:
      - assignments
      properties:
        dry_run:
          type: boolean
          default: false
          description: true — только отчёт, что изменится, без записи
        assignments:
          type: array
          minItems: 1
          maxItems: 200
          items:
            type: object
            additionalProperties: false
            properties:
              member_id:
                $ref: '#/components/schemas/UUID'
                description: Членство из списка участников кабинета
              employee_id:
                $ref: '#/components/schemas/UUID'
                description: Карточка «Команды», связанная с учётной записью
              email:
                type: string
                description: Логин участника или рабочая почта его карточки
              role_id:
                $ref: '#/components/schemas/UUID'
              role_name:
                type: string
                description: Название роли вместо role_id
              all_businesses:
                type: boolean
                description: Все бизнесы кабинета; тогда businesses не передаётся
              businesses:
                type: array
                items:
                  $ref: '#/components/schemas/SettingsMemberBusinessScope'
                description: Бизнесы участника, внутри бизнеса — при желании юрлицо
    SettingsRoleAssignmentBatchResult:
      type: object
      additionalProperties: false
      required:
      - dry_run
      - rows
      - updated
      - unchanged
      - failed
      properties:
        dry_run:
          type: boolean
        rows:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - index
            - status
            - role_changed
            - access_changed
            - all_businesses
            properties:
              index:
                type: integer
                minimum: 0
              status:
                type: string
                enum:
                - updated
                - unchanged
                - error
              code:
                type: string
                description: 'Код отказа строки: settings.members.batch.member_not_found, settings.members.batch.self, settings.roles.grant_beyond_own, settings.members.last_admin, settings.access.* и другие'
              detail:
                type: string
              member_id:
                $ref: '#/components/schemas/UUID'
              member_name:
                type: string
                description: ФИО участника, без него — логин
              username:
                type: string
              role_id:
                $ref: '#/components/schemas/UUID'
              role_name:
                type: string
              previous_role_id:
                $ref: '#/components/schemas/UUID'
              previous_role_name:
                type: string
              role_changed:
                type: boolean
              access_changed:
                type: boolean
              all_businesses:
                type: boolean
                description: 'Область участника после правки: все бизнесы'
              businesses:
                type: array
                items:
                  $ref: '#/components/schemas/SettingsMemberBusinessScope'
              refused_permissions:
                type: array
                items:
                  type: string
                description: Строки роли шире прав назначающего
        updated:
          type: integer
          minimum: 0
        unchanged:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
    SettingsMemberBusinessScope:
      type: object
      additionalProperties: false
      required:
      - business
      properties:
        business:
          $ref: '#/components/schemas/UUID'
        company:
          $ref: '#/components/schemas/UUID'
          description: Сужает доступ до юрлица этого бизнеса; без поля — бизнес целиком
    SettingsMember:
      type: object
      additionalProperties: false
      required:
      - id
      - user_id
      - username
      - full_name
      - birth_date
      - avatar_url
      - role
      - role_name
      - company_scope
      - companies
      - is_active
      - all_businesses
      - businesses
      - access_until
      - access_closed
      - is_guest
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: Идентификатор членства в кабинете, а не человека
        user_id:
          type: integer
          format: int64
          description: Идентификатор человека в общем реестре платформы
        username:
          type: string
        full_name:
          type: string
        birth_date:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        avatar_url:
          type: string
        role:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        role_name:
          oneOf:
          - type: string
          - type: 'null'
        company_scope:
          type: string
          enum:
          - all
          - selected
        companies:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Заполнен при company_scope selected
        is_active:
          type: boolean
        all_businesses:
          type: boolean
          description: Роль действует во всех бизнесах кабинета, включая заведённые позже. У администратора всегда true
        businesses:
          type: array
          items:
            $ref: '#/components/schemas/SettingsMemberBusinessScope'
          description: Бизнесы сотрудника; пуст при all_businesses
        access_until:
          oneOf:
          - type: string
            format: date
          - type: 'null'
          description: 'Последний день доступа в этом кабинете: после конца этого дня в поясе кабинета вход закрыт. null — доступ бессрочный'
        access_closed:
          type: boolean
          description: 'Последний день доступа уже прошёл: участник числится активным, но войти не может и места тарифа не занимает'
        is_guest:
          type: boolean
          description: 'Гость-подрядчик (карточка «Команды» с affiliation guest): права роли сужены до задач, чата и файлов «только где участник», места тарифа не занимает'
    SettingsMemberPage:
      type: object
      additionalProperties: false
      required:
      - count
      - results
      properties:
        count:
          type: integer
          minimum: 0
          description: Число строк в results, а не общее число участников кабинета
        results:
          type: array
          items:
            $ref: '#/components/schemas/SettingsMember'
    Error:
      type: object
      additionalProperties: false
      required:
      - detail
      properties:
        detail:
          type: string
          description: One human sentence in the request language (Accept-Language, echoed as Content-Language)
        code:
          type: string
          description: Stable module error code when the endpoint defines one
        field:
          type: string
          description: Request body path of the field the refusal is about, e.g. content.commercial.amount or due_date; present when the endpoint names the field
        reason:
          type: string
          description: Machine code of the field refusal reason, e.g. required, format, total_mismatch; present together with field when the endpoint defines reasons
        request_id:
          type: string
          format: uuid
          description: Case id. Always present on 5xx and on any error produced by the server itself; the same value is returned in the X-Request-ID header and recorded in the access log and the incident. Quote it to support instead of the cause, which the response never carries.
    SettingsMemberCreateInput:
      type: object
      additionalProperties: false
      required:
      - username
      - password
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          format: password
          minLength: 1
          description: Уходит во внешний сервис входа и в ответе не повторяется
        first_name:
          type: string
          description: Полное имя человека; в ответе это поле называется full_name
        birth_date:
          type: string
          format: date
          description: Строго ГГГГ-ММ-ДД; пустая строка означает «не указана»
        avatar_url:
          type: string
        role:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        company_scope:
          type: string
          enum:
          - all
          - selected
          description: 'Умолчание — all. selected отклоняется 400 settings.company_scope_retired: ограничение по бизнесам и юрлицам задают назначения участника'
        companies:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
    UUID:
      type: string
      format: uuid
  responses:
    BadRequest:
      description: Некорректный запрос или нарушение бизнес-правила
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Сессия, ключ или кабинет не подтверждены
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Текущая роль не имеет требуемого права
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Запись не найдена или не видима текущему пользователю
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Внутренняя ошибка без раскрытия server-only деталей
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Конфликт версии, идемпотентности или бизнес-состояния
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    TenantHeader:
      name: X-Tenant
      in: header
      required: true
      description: Slug выбранного кабинета; кабинет не является юрлицом
      schema:
        type: string
        minLength: 1
  securitySchemes:
    erpUserToken:
      type: http
      scheme: bearer
      bearerFormat: go_session
      description: Пользовательский ERP token, полученный через ORY Kratos session bridge
    tenantApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Tenant-scoped сервисный API-ключ Akeda
    installationToken:
      type: http
      scheme: bearer
      bearerFormat: akeda_installation_token
      description: 'Краткосрочный токен установки приложения (`ai_…`). Выдаёт его человек: публичной двери обмена учётных данных на токен нет и не будет, пока нет брокера долгой половины секрета, асимметричного подтверждения и ограничителя с аудитом неудачных попыток. Токен принимается и в заголовке X-Api-Key, и живёт минуты — вместо показа его ротируют'
    developerSessionToken:
      type: http
      scheme: bearer
      bearerFormat: akeda_developer_session
      description: 'Сессия аккаунта разработчика (`ad_…`). Своя схема, а не пользовательский токен ERP: у разработчика нет кабинета, роли и прав, а хеш этого токена лежит в отдельном хранилище — на кабинетных маршрутах он не находится ничем. Выдаёт его обмен одноразовой ссылки из письма; пароля в этом контуре нет вовсе'
    developerAppKey:
      type: http
      scheme: bearer
      bearerFormat: akeda_developer_app_key
      description: 'Учётные данные приложения (`adk_…`) — это машина конвейера издателя, а не человек. Ключ привязан к ОДНОМУ приложению внешним ключом, и достижимая им поверхность — маршруты `/api/v1/developer` этого приложения. Обменять его на токен установки нельзя: такой двери нет, и ни одного маршрута к данным кабинета за ним не существует. Выпуск, ротацию и отзыв учётных данных этот ключ не выполняет: ключ, умеющий выпустить следующий ключ, не отзывается никогда. Значение показывается один раз, при выдаче; в хранилище лежит хеш'
    mcpOAuth:
      type: oauth2
      description: OAuth 2.1 delegation для MCP; кабинетные права проверяются на каждом вызове
      flows:
        authorizationCode:
          authorizationUrl: https://erp.akeda.ru/oauth2/authorize
          tokenUrl: https://erp.akeda.ru/oauth2/token
          scopes:
            akeda:delegate: Делегировать текущие пользовательские права MCP-подключению
x-akeda-contract-coverage:
- dashboard-metrics
- tasks-lifecycle
- tasks-collaboration
- tasks-workflow
- tasks-organization
- tasks-automation
- tasks-planning
- tasks-project-hub
- tasks-files
- calendar-events
- calendar-availability
- calendar-booking
- calendar-notifications
- calendar-connectors
- chat-conversations
- chat-messages
- chat-receipts
- chat-mentions
- chat-realtime
- core-directories
- core-folders
- core-contacts
- core-products
- core-documents
- core-orders
- core-registers
- core-accounting
- core-ledger
- core-items
- core-employees
- core-employee-operations
- core-currency-rates
- core-preferences
- core-ui-state
- core-external-refs
- core-product-imports
- core-product-exports
- core-gl-opening-imports
- core-reference
- core-change-feed
- finance-accounts
- finance-statements
- finance-transactions
- finance-connectors
- finance-connector-sync
- finance-requisites
- finance-counterparty-terms
- finance-operations
- finance-settlements
- finance-trade
- finance-exchange
- finance-imports
- finance-payment-calendar
- finance-pnl-layouts
- finance-registers
- finance-reports
- crm-pipelines
- crm-deals
- crm-leads
- crm-customers
- crm-links
- crm-inbox
- crm-automation
- crm-analytics
- knowledge-spaces
- knowledge-pages
- knowledge-access
- knowledge-files
- knowledge-search
- files-drives
- files-content
- files-access
- files-uploads
- files-shares
- stock-documents
- stock-inventory
- stock-warehouses
- stock-handling-units
- stock-batches
- stock-product-units
- stock-references
- stock-imports
- stock-exports
- stock-reports
- stock-valuation
- stock-reorder-rules
- stock-settings
- stock-purchasing
- marking-settings
- marking-connections
- marking-products
- marking-codes
- marking-labels
- marking-stock-codes
- marking-orders
- marking-gismt-documents
- marking-boxes
- marketplace-stores
- marketplace-ozon


# --- truncated at 32 KB (33 KB total) ---
# Full source: https://artifacts.apis.io/akeda-ru/openapi/akeda-ru-settings-members-api-openapi.yml