Akeda Marking connections API

openapi: 3.2.0
info:
  title: Akeda ERP Client Marking connections 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: Marking connections
  description: Модуль marking (маркировка «Честный знак») — подключение юрлиц к ГИС МТ и СУЗ, баланс и места деятельности
paths:
  /api/v1/marking/connections:
    get:
      tags:
      - Marking connections
      operationId: markingListConnections
      summary: Получить подключения юрлиц к ГИС МТ и СУЗ
      description: 'Строка на каждое юрлицо в области доступа: контур ГИС МТ, есть ли живой вход и до какого времени, сертификат входа, сведения об участнике, итог последней проверки, а также OMS ID, идентификатор соединения и вход в СУЗ. Токенов True API и СУЗ нет ни в одном ответе: только признаки `has_token` / `oms_has_token` и сроки.'
      x-akeda-module: marking
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: marking:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      responses:
        '200':
          description: Подключения юрлиц
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingConnectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/marking/connections/{company_id}/oms/ping:
    post:
      tags:
      - Marking connections
      operationId: markingPingOMS
      summary: Проверить связь с СУЗ
      description: 'Пробует СУЗ входом юрлица и сохраняет итог у подключения (`oms_last_ping_*`). Заказов и кодов не трогает. Без живого входа в СУЗ — 409 `marking.oms.unauthorized`: войти может только человек по УКЭП.'
      x-akeda-module: marking
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: marking:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - $ref: '#/components/parameters/MarkingCompanyID'
      responses:
        '200':
          description: Подключение с итогом проверки
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingConnectionEnvelope'
        '400':
          description: Идентификатор юрлица не распознан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Юрлицо не подключено к ГИС МТ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '409':
          $ref: '#/components/responses/MarkingSignInRequired'
        '422':
          $ref: '#/components/responses/MarkingDeclined'
        '429':
          $ref: '#/components/responses/MarkingRateLimited'
        '503':
          $ref: '#/components/responses/MarkingUnavailable'
  /api/v1/marking/connections/{company_id}/balance:
    get:
      tags:
      - Marking connections
      operationId: markingListBalances
      summary: Получить баланс лицевых счетов «Честного знака»
      description: 'Баланс лицевых счетов юрлица по товарным группам из ГИС МТ: рубли строкой с двумя знаками («12480.00»), `null` — счёта по группе нет. С баланса списывается оплата заказанных кодов.'
      x-akeda-module: marking
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: marking:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - $ref: '#/components/parameters/MarkingCompanyID'
      responses:
        '200':
          description: Балансы по группам
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingBalanceList'
        '400':
          description: Идентификатор юрлица не распознан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Юрлицо не подключено к ГИС МТ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '409':
          $ref: '#/components/responses/MarkingSignInRequired'
        '422':
          $ref: '#/components/responses/MarkingDeclined'
        '429':
          $ref: '#/components/responses/MarkingRateLimited'
        '503':
          $ref: '#/components/responses/MarkingUnavailable'
  /api/v1/marking/connections/{company_id}/mods:
    get:
      tags:
      - Marking connections
      operationId: markingListMods
      summary: Получить места осуществления деятельности юрлица
      description: 'Места осуществления деятельности (МОД) юрлица из ГИС МТ: КПП, идентификатор ФИАС, адрес и товарные группы. КПП и ФИАС нужны части документов вывода из оборота.'
      x-akeda-module: marking
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: marking:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - $ref: '#/components/parameters/MarkingCompanyID'
      responses:
        '200':
          description: Места деятельности
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingModList'
        '400':
          description: Идентификатор юрлица не распознан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Юрлицо не подключено к ГИС МТ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkingError'
        '409':
          $ref: '#/components/responses/MarkingSignInRequired'
        '422':
          $ref: '#/components/responses/MarkingDeclined'
        '429':
          $ref: '#/components/responses/MarkingRateLimited'
        '503':
          $ref: '#/components/responses/MarkingUnavailable'
components:
  schemas:
    MarkingModList:
      type: object
      additionalProperties: false
      required:
      - mods
      properties:
        mods:
          type:
          - array
          - 'null'
          items:
            type: object
            additionalProperties: false
            required:
            - kpp
            - fias_id
            - address
            properties:
              kpp:
                type: string
              fias_id:
                type: string
              address:
                type: string
              inn:
                type: string
              product_groups:
                type: array
                items:
                  type: string
    MarkingCertificate:
      type: object
      additionalProperties: false
      properties:
        thumbprint:
          type: string
        owner:
          type: string
        inn:
          type: string
        valid_to:
          type: string
          format: date-time
    MarkingBalanceList:
      type: object
      additionalProperties: false
      required:
      - balances
      properties:
        balances:
          type:
          - array
          - 'null'
          items:
            type: object
            additionalProperties: false
            required:
            - product_group_id
            - product_group
            - balance
            - contract_id
            properties:
              product_group_id:
                type: integer
              product_group:
                type: string
              balance:
                type:
                - string
                - 'null'
                description: Рубли строкой с двумя знаками; null — счёта по группе нет
              contract_id:
                type: string
    MarkingError:
      type: object
      additionalProperties: false
      description: 'Отказ модуля маркировки. Поля сверх `code` и `detail` приходят только у отказов, где экран подсвечивает место: параметр документа ГИС МТ, номер кода в запросе или код со строкой складского документа.'
      required:
      - detail
      properties:
        code:
          type: string
          description: Машинный код отказа (`marking.…` или код причины разбора скана)
        detail:
          type: string
          description: Одно предложение на языке запроса
        request_id:
          type: string
          format: uuid
          description: Идентификатор случая у ответов 5xx
        field:
          type: string
          description: Параметр документа ГИС МТ с ошибкой
        problem:
          type: string
          enum:
          - required
          - format
          - value
          - not_allowed
          - unavailable
          - unsupported
          - date_range
          - unknown
          description: Что не так с параметром
        index:
          type: integer
          description: Номер нераспознанного кода в запросе с единицы
        value:
          type: string
          description: Нераспознанный код как пришёл
        identity:
          type: string
          description: Код без криптохвоста, по которому отказ
        box:
          type: string
          description: SSCC короба, где уже лежит код (или паллеты, где лежит короб)
        line:
          type: string
          format: uuid
          description: Строка складского документа отказа
    MarkingConnectionList:
      type: object
      additionalProperties: false
      required:
      - connections
      properties:
        connections:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/MarkingConnection'
    MarkingCheckStatus:
      type: string
      enum:
      - ''
      - ok
      - unauthorized
      - rate_limited
      - declined
      - unavailable
    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.
    MarkingConnection:
      type: object
      additionalProperties: false
      description: Подключение юрлица. Токенов True API и СУЗ здесь нет и не будет.
      required:
      - company_id
      - company_name
      - company_inn
      - connected
      - has_token
      - oms_id
      - oms_connection
      - oms_has_token
      - oms_token_expires_at
      - oms_token_issued_at
      - oms_last_ping_at
      - oms_last_ping_status
      - oms_last_ping_message
      properties:
        company_id:
          $ref: '#/components/schemas/UUID'
        company_name:
          type: string
        company_inn:
          type: string
        connected:
          type: boolean
        contour:
          type: string
          enum:
          - sandbox
          - production
        inn:
          type: string
          description: ИНН входа
        has_token:
          type: boolean
          description: Есть живой вход в ГИС МТ
        token_kind:
          type: string
          enum:
          - jwt
          - uuid
        token_expires_at:
          type: string
          format: date-time
        token_issued_at:
          type: string
          format: date-time
        token_issued_by:
          type: integer
          format: int64
        certificate:
          $ref: '#/components/schemas/MarkingCertificate'
        participant:
          type: object
          additionalProperties: true
          description: Несекретные сведения об участнике из входа
        last_check_at:
          type: string
          format: date-time
        last_check_status:
          $ref: '#/components/schemas/MarkingCheckStatus'
        last_check_message:
          type: string
        oms_id:
          type: string
        oms_connection:
          type: string
        oms_has_token:
          type: boolean
          description: Есть живой вход в СУЗ
        oms_token_expires_at:
          type:
          - string
          - 'null'
          format: date-time
        oms_token_issued_at:
          type:
          - string
          - 'null'
          format: date-time
        oms_last_ping_at:
          type:
          - string
          - 'null'
          format: date-time
        oms_last_ping_status:
          $ref: '#/components/schemas/MarkingCheckStatus'
        oms_last_ping_message:
          type: string
    MarkingConnectionEnvelope:
      type: object
      additionalProperties: false
      required:
      - connection
      properties:
        connection:
          $ref: '#/components/schemas/MarkingConnection'
    UUID:
      type: string
      format: uuid
  responses:
    Unauthorized:
      description: Сессия, ключ или кабинет не подтверждены
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MarkingUnavailable:
      description: ГИС МТ или СУЗ не отвечают (`marking.gismt.unavailable`, `marking.oms.unavailable`) либо на сервере не задан ключ шифрования входа (`marking.connection.encryption_key_required`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarkingError'
    MarkingRateLimited:
      description: ГИС МТ или СУЗ просят подождать (`marking.gismt.rate_limited`, `marking.oms.rate_limited`). Повторите через минуту.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarkingError'
    Forbidden:
      description: Текущая роль не имеет требуемого права
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MarkingSignInRequired:
      description: Вход юрлица в ГИС МТ или СУЗ истёк или не выполнен (`marking.gismt.unauthorized`, `marking.oms.unauthorized`), не заданы OMS ID и соединение (`marking.oms.not_configured`) или сохранённый вход не читается. Войти может только человек по УКЭП в браузере.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarkingError'
    MarkingDeclined:
      description: ГИС МТ или СУЗ отказали по существу (`marking.gismt.declined`, `marking.oms.declined`); `detail` передаёт отказ словами оператора.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarkingError'
  parameters:
    MarkingCompanyID:
      name: company_id
      in: path
      required: true
      description: Юрлицо кабинета
      schema:
        $ref: '#/components/schemas/UUID'
    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
- 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