Akeda Stock product units API

openapi: 3.2.0
info:
  title: Akeda ERP Client Stock product units 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: Stock product units
  description: Модуль stock (склад) — единицы измерения товара и их пересчёт
paths:
  /api/v1/stock/products/{productId}/bins:
    get:
      tags:
      - Stock product units
      operationId: stockGetProductBins
      summary: Получить, в каких ячейках лежит товар
      description: 'По каждому месту, где товар лежит в ячейках или где включены ячейки: ячейки с количеством, партией со сроком и состоянием, а также количество «не размещено» по месту.'
      x-akeda-module: stock
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:read
      security:
      - erpUserToken: []
      - tenantApiKey: []
      - mcpOAuth:
        - akeda:delegate
      - installationToken: []
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: productId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Места и ячейки товара
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockProductBins'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/stock/product-uoms:
    put:
      tags:
      - Stock product units
      operationId: stockSaveProductUOM
      summary: Завести или изменить товарную единицу ввода
      description: Пересчёт в базовую единицу хранится у товара, потому что одна и та же по названию упаковка вмещает разное содержимое для разных товаров.
      x-akeda-module: stock
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:write
      security:
      - erpUserToken: []
      - tenantApiKey: []
      - mcpOAuth:
        - akeda:delegate
      - installationToken: []
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockProductUOMInput'
      responses:
        '200':
          description: Сохранённая товарная единица
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockProductUOM'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
  /api/v1/stock/products/scan:
    get:
      tags:
      - Stock product units
      operationId: stockScanProduct
      summary: Определить товар и единицу ввода по штрихкоду
      description: Документ всё равно хранит количество в базовой единице; factor_to_base управляет только представлением ввода оператора.
      x-akeda-module: stock
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:read
      security:
      - erpUserToken: []
      - tenantApiKey: []
      - mcpOAuth:
        - akeda:delegate
      - installationToken: []
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: code
        in: query
        required: true
        description: Штрихкод; нормализуется перед поиском
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Товар и единица ввода штрихкода
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockScanResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/stock/price-suggestions:
    get:
      tags:
      - Stock product units
      operationId: stockPriceSuggestions
      summary: Подобрать цену по умолчанию для прихода без цены поставщика
      description: 'Цена по умолчанию для излишка инвентаризации, ввода остатков и оприходования: себестоимость единицы на складе, по юрлицу (без юрлица — по бизнесу), цена последнего прихода, закупочная цена карточки — первая найденная, с источником. Нет ни одной — 0 и source none: строку надо оценить до закрытия месяца (по ФСБУ 5 излишки приходуются по справедливой стоимости). Не больше 200 товаров за раз. Без права `stock.valuation:read` («Себестоимость и суммы склада», ERP-1978) список пуст.'
      x-akeda-module: stock
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:read
      security:
      - erpUserToken: []
      - tenantApiKey: []
      - mcpOAuth:
        - akeda:delegate
      - installationToken: []
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: products
        in: query
        required: true
        description: Товары через запятую
        schema:
          type: string
          minLength: 1
      - name: company
        in: query
        description: Юрлицо
        schema:
          $ref: '#/components/schemas/UUID'
      - name: business
        in: query
        description: Бизнес — если юрлицо не задано
        schema:
          $ref: '#/components/schemas/UUID'
      - name: warehouse
        in: query
        description: Склад
        schema:
          $ref: '#/components/schemas/UUID'
      - name: date
        in: query
        description: Дата ГГГГ-ММ-ДД; пусто — сегодня
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Цена и источник по каждому товару
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockPriceSuggestions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/stock/products/{productId}/uoms:
    get:
      tags:
      - Stock product units
      operationId: stockListProductUOMs
      summary: Получить товарные единицы ввода товара
      description: Возвращает товарные единицы ввода для указанной позиции номенклатуры.
      x-akeda-module: stock
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:read
      security:
      - erpUserToken: []
      - tenantApiKey: []
      - mcpOAuth:
        - akeda:delegate
      - installationToken: []
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: productId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Товарные единицы ввода
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockProductUOMPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Forbidden:
      description: Текущая роль не имеет требуемого права
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Запись не найдена или не видима текущему пользователю
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Некорректный запрос или нарушение бизнес-правила
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Сессия, ключ или кабинет не подтверждены
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Конфликт версии, идемпотентности или бизнес-состояния
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StockScanResult:
      type: object
      additionalProperties: false
      required:
      - identifier_id
      - barcode
      - product_id
      - product_sku
      - product_name
      - base_unit
      - product_uom_id
      - product_uom_name
      - input_unit_id
      - input_unit_label
      - factor_to_base
      properties:
        identifier_id:
          $ref: '#/components/schemas/UUID'
        barcode:
          type: string
        product_id:
          $ref: '#/components/schemas/UUID'
        product_sku:
          type: string
        product_name:
          type: string
        base_unit:
          type: string
        product_uom_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        product_uom_name:
          type: string
        input_unit_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        input_unit_label:
          type: string
        factor_to_base:
          type: string
        gs1:
          $ref: '#/components/schemas/StockScanGS1'
        marking_group:
          $ref: '#/components/schemas/StockScanMarkingGroup'
    StockBinSlice:
      type: object
      required:
      - warehouse_id
      - product_id
      - product_sku
      - product_name
      - unit
      - batch_id
      - batch_code
      - produced_at
      - expires_at
      - condition_id
      - condition_name
      - handling_unit_id
      - handling_unit_code
      - business_id
      - company_id
      - quantity
      properties:
        warehouse_id:
          allOf:
          - $ref: '#/components/schemas/UUID'
          description: Склад или зона
        product_id:
          $ref: '#/components/schemas/UUID'
        product_sku:
          type: string
        product_name:
          type: string
        unit:
          type: string
        batch_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        batch_code:
          type: string
          description: Серия партии поставщика; пусто — серии нет
        produced_at:
          type:
          - string
          - 'null'
          format: date
        expires_at:
          type:
          - string
          - 'null'
          format: date
          description: Годен до
        condition_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
          description: Состояние товара; пусто — «Основное»
        condition_name:
          type: string
          description: Название состояния; пусто у «Основного»
        handling_unit_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        handling_unit_code:
          type: string
        business_id:
          $ref: '#/components/schemas/UUID'
        company_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
        quantity:
          type: string
          description: Десятичное число строкой
    StockBinContentRow:
      allOf:
      - $ref: '#/components/schemas/StockBinSlice'
      - type: object
        required:
        - bin_id
        - bin_code
        - bin_name
        properties:
          bin_id:
            $ref: '#/components/schemas/UUID'
          bin_code:
            type: string
          bin_name:
            type: string
    StockScanGS1:
      type: object
      description: Разобранный код GS1 — код маркировки или логистическая этикетка. У обычного штрихкода блока нет. Поля, которых в коде не было, пусты. Блок криптохвост маркировки не несёт; поле barcode — сохранённое значение идентификатора как есть.
      additionalProperties: false
      required:
      - gtin
      - serial
      - identification_code
      - batch
      - expires_on
      - sscc
      - has_crypto_tail
      properties:
        gtin:
          type: string
          description: GTIN из кода — четырнадцать цифр
        serial:
          type: string
          description: Серийный номер экземпляра
        identification_code:
          type: string
          description: Код идентификации экземпляра — 01, GTIN, 21 и серийный номер, без криптохвоста
        batch:
          type: string
          description: Партия производителя
        expires_on:
          type: string
          description: Срок годности из кода датой ГГГГ-ММ-ДД; пусто — срока в коде нет
        produced_on:
          type: string
          description: Дата изготовления из кода (идентификатор 11) датой ГГГГ-ММ-ДД; нет поля — даты в коде нет (ERP-2199)
        sscc:
          type: string
          description: Код транспортной упаковки — восемнадцать цифр
        has_crypto_tail:
          type: boolean
          description: Код считан вместе с криптохвостом маркировки
    StockProductBins:
      type: object
      additionalProperties: false
      required:
      - product_id
      - places
      - slice_count
      - truncated
      properties:
        product_id:
          $ref: '#/components/schemas/UUID'
        places:
          type: array
          items:
            $ref: '#/components/schemas/StockProductBinsPlace'
        slice_count:
          type: integer
          minimum: 0
          description: Сколько срезов товара лежит в ячейках всего
        truncated:
          type: boolean
          description: 'Срезов больше предела ответа: показаны не все места, экран обязан это сказать'
    StockScanMarkingGroup:
      type: object
      description: 'Действующая группа маркировки найденного товара — своя или от категории. Поле про товар, а не про код: оно есть и у обычного штрихкода. У товара, который не маркируется, поля нет.'
      additionalProperties: false
      required:
      - id
      - name
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/UUID'
          description: Идентификатор группы маркировки
        name:
          type: string
          description: Название группы маркировки
    StockProductUOMPage:
      type: object
      additionalProperties: false
      required:
      - count
      - results
      properties:
        count:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/StockProductUOM'
    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.
    StockProductUOMInput:
      type: object
      additionalProperties: false
      required:
      - product_id
      - code
      - name
      - input_unit_id
      - factor_to_base
      properties:
        id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
          description: Без идентификатора заводится новая товарная единица
        product_id:
          $ref: '#/components/schemas/UUID'
        code:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        input_unit_id:
          $ref: '#/components/schemas/UUID'
        usage:
          $ref: '#/components/schemas/StockProductUOMUsage'
        factor_to_base:
          type: string
          description: Положительное число; десятичный разделитель — точка или запятая, хранится запись с точкой
        creates_handling_units:
          type: boolean
          description: Требует единицы измерения с целой точностью
        variable_measure:
          type: boolean
          description: 'Переменная мера: приход складывает количество из фактических мер конкретных единиц, цена за базовую единицу; расход в такой единице невозможен. Требует creates_handling_units'
        qty_step:
          type: string
          description: 'Положительное число (точка или запятая) или пусто: количество строки в этой единице обязано быть кратно шагу'
        remnant_threshold:
          type: string
          description: Положительное число (точка или запятая) или пусто. Требует creates_handling_units
        is_default_receipt:
          type: boolean
        is_active:
          oneOf:
          - type: boolean
          - type: 'null'
          description: По умолчанию единица активна
    StockProductBinsPlace:
      type: object
      additionalProperties: false
      required:
      - warehouse_id
      - warehouse_name
      - warehouse_parent_name
      - bins_mode
      - placed_qty
      - unplaced_qty
      - bins
      - unplaced
      properties:
        warehouse_id:
          $ref: '#/components/schemas/UUID'
        warehouse_name:
          type: string
        warehouse_parent_name:
          type: string
          description: Склад зоны; пусто, если это сам склад
        bins_mode:
          type: string
          enum:
          - 'off'
          - soft
          - strict
        placed_qty:
          type: string
        unplaced_qty:
          type: string
        bins:
          type: array
          items:
            $ref: '#/components/schemas/StockBinContentRow'
        unplaced:
          type: array
          items:
            $ref: '#/components/schemas/StockBinSlice'
    UUID:
      type: string
      format: uuid
    StockProductUOM:
      type: object
      additionalProperties: false
      required:
      - id
      - product_id
      - code
      - name
      - input_unit_id
      - unit_code
      - unit_label
      - usage
      - factor_to_base
      - precision
      - creates_handling_units
      - is_default_receipt
      - is_active
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        product_id:
          $ref: '#/components/schemas/UUID'
        code:
          type: string
        name:
          type: string
        input_unit_id:
          $ref: '#/components/schemas/UUID'
        unit_code:
          type: string
        unit_label:
          type: string
        usage:
          $ref: '#/components/schemas/StockProductUOMUsage'
        factor_to_base:
          type: string
          description: Положительный decimal — сколько базовых единиц товара содержит одна единица ввода
        precision:
          type: integer
        creates_handling_units:
          type: boolean
        variable_measure:
          type: boolean
          description: 'Коэффициент — номинал: фактическая мера у каждой конкретной единицы своя (рулон ~50 м)'
        qty_step:
          type: string
          description: 'Шаг количества в этой единице: «режем по 10 см». Пусто — без ограничения'
        remnant_threshold:
          type: string
          description: 'Порог обрезка: остаток конкретной единицы меньше порога считается обрезком. Только для единиц с учётом конкретных единиц'
        is_default_receipt:
          type: boolean
        is_active:
          type: boolean
        updated_at:
          type: string
          format: date-time
    StockProductUOMUsage:
      type: string
      enum:
      - purchase
      - receipt
      - packaging
      - consumption
      - sale
      description: 'Где единицу предлагают первой: purchase — закупка, receipt — поступление, consumption — комплектация и списание, sale — отгрузка, packaging — тара без своего места. Выбор в документах не ограничивает'
    StockPriceSuggestions:
      type: object
      additionalProperties: false
      required:
      - results
      properties:
        results:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - product_id
            - price
            - source
            properties:
              product_id:
                $ref: '#/components/schemas/UUID'
              price:
                type: string
                description: Цена единицы; 0 — цены нет
              source:
                type: string
                enum:
                - warehouse
                - company
                - last_receipt
                - card
                - none
                description: Откуда цена
  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
- marketplace-wildberries
- marketplace-yandex
- marketplace-product-groups
- marketplace-accounting
- marketplace-catalog
- settings-companies
- settings-roles
- settings-members
- settings-fields
- settings-api-keys
- finance-payroll
- finance-report-details
- knowledge-tags
- knowledge-revisions
- knowledge-approval
- chat-attachments
- chat-reactions
- chat-folders
- platform-apps
- platform-app-installations
- platform-app-tokens
- platform-app-deliveries
- platform-app-publishers
- platform-app-publication
- platform-app-rollouts
- platform-app-runtime
- platform-app-access
- platform-app-blocks
- platform-demo-data
- billing-usage
- platform-analytics
- finance-staffing
- platform-tenants
- platform-users
- platform-access
- platform-mcp-publication
- platform-incidents


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/akeda-ru/openapi/akeda-ru-stock-product-units-api-openapi.yml