Akeda Stock exports API

openapi: 3.2.0
info:
  title: Akeda ERP Client Stock exports 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 exports
  description: Модуль stock (склад) — выгрузка данных файлом
paths:
  /api/v1/stock/exports:
    post:
      tags:
      - Stock exports
      operationId: stockCreateExport
      summary: Сформировать складской снимок для скачивания
      description: 'reorder_rules выгружает правила пополнения кабинета целиком,

        kit_specs — действующие составы наборов тем же шаблоном, что у загрузки.

        stock_report выгружает отчёт остатков по отбору экрана: он приходит

        объектом report, и без него запрос отклоняется как 400. Обратное тоже

        верно — report у других видов отклоняется, чтобы отбор не применился

        молча к выгрузке, которая его не читает.

        series_sheet выгружает «Ведомость по партиям» раздела «Партии»: строки —

        товар и номер партии с датами выпуска и срока, колонки — места хранения,

        состояния или их пары, итоги по строке и колонке. Отбор приходит

        объектом series_sheet (те же параметры, что у GET /stock/batch-stock)

        и обязателен для этого вида.

        order_fulfillment выгружает «Исполнение заказа»: по каждой строке

        отгрузок заказа продажи — заявлено, отгружено или собрано,

        расхождение и причина недобора. Заказ приходит объектом

        order_fulfillment и обязателен для этого вида.

        Остальным видам target_document_id обязателен: без него запрос

        отклоняется как 400, а недоступный или несуществующий документ даёт 404.

        Экспорт принадлежит создавшему субъекту и защищает текстовые значения

        от исполнения как формул.'
      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/StockExportRequest'
      responses:
        '201':
          description: Готовый экспорт
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockExport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/stock/exports/{id}:
    get:
      tags:
      - Stock exports
      operationId: stockGetExport
      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: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Метаданные готового экспорта
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockExport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/stock/exports/{id}/content:
    get:
      tags:
      - Stock exports
      operationId: stockGetExportContent
      summary: Скачать файл своего складского экспорта
      description: Поток файла своего складского экспорта; чужой экспорт — 404. Агенту без токена API адрес выдаёт stockExportDownloadSession.
      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: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          $ref: '#/components/responses/TabularFile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/stock/exports/{id}/download-session:
    get:
      tags:
      - Stock exports
      operationId: stockExportDownloadSession
      summary: Временный адрес файла своего складского экспорта
      description: 'Файл своего складского экспорта подписанным адресом; чужой экспорт — 404. Подписанный адрес живёт 15 минут и открывается GET без заголовка авторизации — так файл забирает агент по MCP. direct=false — хранилище подписывать не умеет: адрес ведёт на поток этого API и требует авторизации (requires_authorization=true).'
      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: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Временный адрес файла
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockDownloadLink'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    StockOrderFulfillmentExportRequest:
      type: object
      additionalProperties: false
      required:
      - sales_order_id
      description: Заказ продажи для выгрузки «Исполнение заказа» (ERP-1979).
      properties:
        sales_order_id:
          allOf:
          - $ref: '#/components/schemas/UUID'
          description: Заказ продажи, по отгрузкам которого собирается файл
    StockReportExportRequest:
      type: object
      additionalProperties: false
      description: 'Отбор экрана остатков и его видимые колонки. Имена полей повторяют

        параметры GET /api/v1/stock/report/stocks: файл обязан содержать то

        же, что видел человек, и одно имя на два входа защищает от

        расхождения. Отличается только перенос: список складов идёт массивом,

        а не строкой через запятую, и дополнительные поля — объектом вместо

        параметров cf.*.

        Колонки берутся из перечня; неизвестная колонка — 400, а не молча

        пропущенная. Опознавательные колонки (бизнес, юрлицо, склад и зона с

        кодами, товар, SKU, единица) пишутся всегда, и порядок колонок в файле

        повторяет экран.

        Выборка обходится постранично целиком; слишком широкая отклоняется

        как 400 — книга собирается в памяти, и потолок общий с загрузкой.

        Сводная клетка (column_axis warehouse или company, режим matrix) не

        выгружается — 400: файл плоский, а те же ячейки строками дают формы

        warehouse_company и company.

        '
      properties:
        mode:
          type: string
          enum:
          - products
          - warehouses
          - companies
          default: warehouses
        row_axis:
          type: string
          enum:
          - product
          - warehouse
          - company
          - warehouse_company
        column_axis:
          type: string
          enum:
          - metrics
          - warehouse
          - company
          default: metrics
        q:
          type: string
        as_of:
          type: string
          format: date
        business_id:
          $ref: '#/components/schemas/UUID'
        company_id:
          $ref: '#/components/schemas/UUID'
        warehouse_id:
          $ref: '#/components/schemas/UUID'
        warehouse_ids:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
        product_id:
          $ref: '#/components/schemas/UUID'
        custom_fields:
          type: object
          additionalProperties:
            type: string
        without_company:
          type: boolean
          default: false
        rollup_zones:
          type: boolean
          default: false
        below_minimum:
          type: boolean
          default: false
        with_reserve:
          type: boolean
          default: false
        include_empty:
          type: boolean
          default: false
        sort:
          type: string
          enum:
          - name
          - on_hand
          - physical_on_hand
          - blocked
          - unavailable
          - in_transit
          - reserved
          - available
          - expected
          - forecast
          - minimum
          - suggested
          - unit_cost
          - amount
          default: name
        direction:
          type: string
          enum:
          - asc
          - desc
          default: asc
        columns:
          type: array
          items:
            type: string
            enum:
            - on_hand
            - physical_on_hand
            - blocked
            - unavailable
            - in_transit
            - expired
            - reserved
            - available
            - expected
            - forecast
            - minimum
            - suggested
            - unit_cost
            - amount
    StockSeriesSheetExportRequest:
      type: object
      additionalProperties: false
      description: Отбор и вид «Ведомости по партиям» (ERP-2423). Имена отборов — как у GET /stock/batch-stock.
      properties:
        search:
          type: string
          description: Товар, артикул, штрихкод или серия
        as_of:
          type: string
          format: date
          description: Остаток на дату; пусто — сегодня
        business_id:
          $ref: '#/components/schemas/UUID'
        company_id:
          $ref: '#/components/schemas/UUID'
        product_id:
          $ref: '#/components/schemas/UUID'
        warehouse_ids:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Места хранения; зоны склада входят в него
        condition_id:
          type: string
          description: Пусто — все состояния, main — «Основное», иначе id состояния
        columns:
          type: string
          enum:
          - warehouse
          - condition
          - warehouse_condition
          default: warehouse
          description: 'Колонки ведомости: места хранения, состояния или их пары'
        value:
          type: string
          enum:
          - qty
          - amount
          default: qty
          description: Количество или себестоимость в ячейках
    StockExport:
      type: object
      additionalProperties: false
      required:
      - id
      - kind
      - format
      - file_name
      - size
      - row_count
      - created_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        kind:
          $ref: '#/components/schemas/StockExportKind'
        format:
          $ref: '#/components/schemas/CoreProductTransferFormat'
        target_document_id:
          $ref: '#/components/schemas/UUID'
        file_name:
          type: string
        size:
          type: integer
          format: int64
          minimum: 0
        row_count:
          type: integer
          minimum: 0
        created_by:
          type: integer
          format: int64
          minimum: 1
        created_at:
          type: string
          format: date-time
    StockExportRequest:
      type: object
      additionalProperties: false
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/StockExportKind'
        format:
          $ref: '#/components/schemas/CoreProductTransferFormat'
          default: xlsx
        target_document_id:
          allOf:
          - $ref: '#/components/schemas/UUID'
          description: Обязателен для всех видов, кроме reorder_rules, kit_specs, stock_report, series_sheet и order_fulfillment
        report:
          $ref: '#/components/schemas/StockReportExportRequest'
          description: 'Обязателен для stock_report и запрещён остальным видам: без отбора запрос означал бы «выгрузите весь кабинет»'
        series_sheet:
          $ref: '#/components/schemas/StockSeriesSheetExportRequest'
          description: Обязателен для series_sheet и запрещён остальным видам
        order_fulfillment:
          $ref: '#/components/schemas/StockOrderFulfillmentExportRequest'
          description: Обязателен для order_fulfillment и запрещён остальным видам
    StockExportKind:
      type: string
      description: 'Вид складской выгрузки. Шире вида загрузки: отчёт остатков

        выгружается, но не загружается — читателя такого файла нет вовсе, и

        вид в общем перечне открыл бы себе путь загрузки.

        '
      enum:
      - initial_stock
      - inventory_count
      - document_items
      - reorder_rules
      - stock_report
      - kit_specs
      - series_sheet
      - order_fulfillment
    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.
    StockDownloadLink:
      type: object
      additionalProperties: false
      description: 'Временный адрес файла склада: подписанный адрес хранилища или адрес этого API.'
      required:
      - url
      - method
      - direct
      - requires_authorization
      - name
      - mime_type
      - size_bytes
      properties:
        url:
          type: string
        method:
          type: string
          enum:
          - GET
        direct:
          type: boolean
          description: true — подписанный адрес хранилища, без заголовка авторизации; false — адрес этого API, с авторизацией
        requires_authorization:
          type: boolean
          description: true — адрес требует токен API, агенту по MCP он недоступен
        expires_at:
          type: string
          format: date-time
          description: Срок подписанного адреса; у адреса API его нет
        name:
          type: string
        mime_type:
          type: string
        size_bytes:
          type: integer
          format: int64
          minimum: 0
        sha256:
          type: string
          description: Контрольная сумма SHA-256, если известна
    UUID:
      type: string
      format: uuid
    CoreProductTransferFormat:
      type: string
      enum:
      - xlsx
      - xls
      - ods
      - csv
      - tsv
  parameters:
    TenantHeader:
      name: X-Tenant
      in: header
      required: true
      description: Slug выбранного кабинета; кабинет не является юрлицом
      schema:
        type: string
        minLength: 1
  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'
    TabularFile:
      description: XLSX, XLS, ODS, CSV или TSV-файл из tenant-scoped object storage
      headers:
        Content-Disposition:
          schema:
            type: string
        Cache-Control:
          schema:
            type: string
            const: private, no-store
      content:
        application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
          schema:
            type: string
            format: binary
        application/vnd.ms-excel:
          schema:
            type: string
            format: binary
        application/vnd.oasis.opendocument.spreadsheet:
          schema:
            type: string
            format: binary
        text/csv:
          schema:
            type: string
            format: binary
        text/tab-separated-values:
          schema:
            type: string
            format: binary
  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
- platform-health
- settings-apps
- docflow-connections
- docflow-mirror
- docflow-signing
- docflow-actions
- docflow-outgoing
- docflow-intake
- docflow-flow
- docflow-approvals
- docflow-flow-accounting
- mail-accounts
- mail-folders
- mail-messages
- mail-rules
- mail-outbound
- mail-attachments
- billing-plans
- billing-subscriptions
- billing-invoices
- billing-analytics
- settings-subscription
- billing-payments
- billing-public
x-akeda-docs-path: /docs
x-akeda-default-release-stage: internal
x-akeda-default-audience: operator