Akeda Docflow Yandex KIT API

openapi: 3.2.0
info:
  title: Akeda ERP Client Docflow Yandex KIT 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: Docflow Yandex KIT
  description: 'Модуль docflow (документы: бумаги, ЭДО, согласование) — заказы сайта на Яндекс KIT: итог опроса API KIT и связь заказа сайта с заказом покупателя. Двери экрана «Настройки → Подключения → Яндекс KIT».'
paths:
  /api/v1/docflow/yandex-kit/state:
    get:
      tags:
      - Docflow Yandex KIT
      operationId: docflowYandexKitState
      summary: Итог последнего опроса Яндекс KIT
      description: Когда кабинет последний раз опрашивал API Яндекс KIT, с каким итогом (ok, token_rejected, rate_limited, unavailable, not_configured, retail_buyer_missing), сколько заказов сайта видел и изменил, до какого момента изменения KIT уже прочитаны (cursor_at) и не разошёлся ли режим подтверждения заказов с настройкой самого KIT (warning_code).
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: docflow.flow:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      responses:
        '200':
          description: Итог опроса
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowYandexKitStateEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/docflow/yandex-kit/orders:
    get:
      tags:
      - Docflow Yandex KIT
      operationId: docflowYandexKitOrders
      summary: Заказы сайта Яндекс KIT
      description: 'Заказы сайта на Яндекс KIT и заказы покупателя, которыми они стали: статус заказа и оплаты в KIT, служба доставки, трек-номер, что требует внимания человека. Персональных данных покупателя нет. Свежие сначала.'
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: docflow.flow:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: order_id
        in: query
        description: Только заказ KIT, ставший этим заказом покупателя
        schema:
          $ref: '#/components/schemas/UUID'
      - name: attention
        in: query
        description: 1 — только требующие внимания
        schema:
          type: string
          enum:
          - '1'
      - name: limit
        in: query
        description: Сколько строк вернуть, по умолчанию 100, не больше 200
        schema:
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Заказы KIT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowYandexKitOrderList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/docflow/yandex-kit/sync:
    post:
      tags:
      - Docflow Yandex KIT
      operationId: docflowYandexKitSync
      summary: Опросить Яндекс KIT сейчас
      description: 'Опрашивает API Яндекс KIT без ожидания срока и приводит заказы покупателя к сайту: новые заказы заводятся, изменённые обновляются, отменённые отменяются. Затем пишет в KIT: коды «Честного знака» собранных или отгруженных заказов, подтверждение заказа (режим подтверждения akeda — после «Собрано» и всех кодов) и, если включена передача остатков (options.stock_sync), свободный остаток склада. Отгрузки не трогает. Не подключено — 404 yandex_kit_not_connected.'
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: docflow.flow:write
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      responses:
        '200':
          description: Итог опроса
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowYandexKitStateEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/docflow/yandex-kit/handover:
    get:
      tags:
      - Docflow Yandex KIT
      operationId: docflowYandexKitHandover
      summary: Заказы Яндекс KIT к передаче курьеру
      description: 'Заказы сайта Яндекс KIT, подтверждённые и ещё не уехавшие к покупателю, группами по службе доставки, которую выбрал покупатель (YANDEX_DELIVERY, CDEK и т. п.): за каждой службой приезжает свой курьер со своим актом. У заказа — состояние на складе: picked — собран и может уехать, picking — ждёт сборки, unconfirmed — собран, но в режиме «Подтверждает Акеда» KIT его ещё не подтвердил, shipped — отгрузка проведена; waybill_at — когда заказ вошёл в акт курьеру. Обычные заказы покупателей сюда не попадают. KIT не подключён — пустой список групп.'
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      responses:
        '200':
          description: Заказы KIT по службам доставки
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowYandexKitHandover'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/docflow/yandex-kit/handover/{service}/shipped:
    post:
      tags:
      - Docflow Yandex KIT
      operationId: docflowYandexKitMarkShipped
      summary: Отгружено курьеру службы доставки Яндекс KIT
      description: 'Курьер службы доставки {service} забрал посылки заказов сайта Яндекс KIT. Проводит черновики отгрузки тех заказов этой службы, которые склад собрал («Собрано») и KIT подтвердил (в режиме «Подтверждает KIT» — все собранные), — той же дверью склада, что «Отгрузить» у собранного заказа: списание, выручка и УПД — как у обычной отгрузки. Несобранные и неподтверждённые заказы не трогает и возвращает в waiting (с waybill_at, если они уже в акте); уже отгруженные считает в already_shipped — повтор ничего не проводит второй раз. Склад отказал по заказу — он в failed, остальные проводятся. Тело необязательно: order_ids — только эти собранные заказы отданы курьеру (заказ, который после сборки отменили или не отдали, не проводится и остаётся в waiting собранным); без тела — все собранные службы. Пустая служба — 400 yandex_kit_service_required; KIT не подключён — 404 yandex_kit_not_connected.'
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-audience: external
      x-akeda-permission: stock.shipment:write
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: service
        in: path
        required: true
        description: 'Служба доставки, код KIT: YANDEX_DELIVERY, CDEK и т. п.'
        schema:
          type: string
          minLength: 1
          maxLength: 64
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                order_ids:
                  type: array
                  maxItems: 500
                  description: Заказы покупателя, которые курьер забрал; пусто — все собранные заказы службы
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Итог передачи курьеру
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowYandexKitShippedResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DocflowYandexKitHandoverGroup:
      type: object
      additionalProperties: false
      required:
      - delivery_service
      - orders
      - picked
      - picking
      - unconfirmed
      - shipped
      - in_waybill
      properties:
        delivery_service:
          type: string
          description: 'Служба доставки, код KIT: YANDEX_DELIVERY, CDEK и т. п.'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitHandoverOrder'
        picked:
          type: integer
          description: Собрано и может уехать
        picking:
          type: integer
          description: Ждут сборки
        unconfirmed:
          type: integer
          description: Собрано, но KIT ещё не подтвердил
        shipped:
          type: integer
          description: Уже отгружено
        in_waybill:
          type: integer
          description: Из неотгруженных — уже в акте курьеру
    DocflowYandexKitOrder:
      type: object
      additionalProperties: false
      required:
      - id
      - kit_order_id
      - order_number
      - kit_status
      - payment_method
      - payment_status
      - kit_created_at
      - kit_updated_at
      - order_id
      - delivery_service
      - delivery_method
      - tracking_number
      - confirmation_seen
      - delivery_chunk_ids
      - kit_confirmed_at
      - marks_state
      - marks_sent_at
      - waybill_at
      - attention_code
      - attention_detail
      - last_seen_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        kit_order_id:
          type: string
          description: Идентификатор заказа в KIT
        order_number:
          type: integer
          format: int64
          description: Номер заказа, который видит покупатель
        kit_status:
          type: string
          description: 'Статус заказа в KIT как пришёл: NEW, WAIT_FOR_DELIVERY, COMPLETED, CANCELLED и т. п.'
        payment_method:
          type: string
          description: 'Способ оплаты в KIT: CARD_ONLINE, CARD_ON_DELIVERY, CASH_ON_DELIVERY'
        payment_status:
          type: string
          description: 'Состояние оплаты в KIT: PAYMENT_PENDING_OR_UNPAID, PAYMENT_PAID, PAYMENT_REFUNDED, PAYMENT_FINALLY_PAID'
        kit_created_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        kit_updated_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        order_id:
          oneOf:
          - $ref: '#/components/schemas/UUID'
          - type: 'null'
          description: Заказ покупателя; null — ещё не заведён
        delivery_service:
          type: string
          description: 'Служба доставки, код KIT: YANDEX_DELIVERY, CDEK и т. п.'
        delivery_method:
          type: string
          description: 'Способ доставки, код KIT: PICKUP_POINT, COURIER и т. п.'
        tracking_number:
          type: string
        confirmation_seen:
          type: boolean
          description: Опрос хоть раз видел заказ в статусе WAIT_FOR_CONFIRMATION
        delivery_chunk_ids:
          type: array
          items:
            type: integer
            format: int64
          description: 'Части заказа KIT с выбранного склада KIT: по ним просят ярлык и акт'
        kit_confirmed_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Когда Akeda подтвердила заказ в KIT (режим akeda); null — не подтверждала
        marks_state:
          type: string
          enum:
          - ''
          - sent
          - none
          - incomplete
          description: 'Коды «Честного знака» в KIT: пусто — ещё не писали, sent — записаны, none — маркируемых позиций нет, incomplete — кодов меньше, чем маркируемых позиций'
        marks_sent_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Когда коды последний раз записаны в KIT
        waybill_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Когда заказ вошёл в акт приёма-передачи курьеру; null — ещё не передан
        attention_code:
          type: string
          description: 'Что требует человека: item_unknown, vat_mismatch — ставка НДС позиции в KIT не совпала со ставкой учётной политики юрлица на день заказа (kit, ours, date), below_shipped, cancelled_after_shipment, cancel_blocked, completed_not_shipped, delivery_cancelled, partial_refund, frozen, import_failed (reason, code, detail — причина отказа), marking_incomplete — кодов маркировки меньше, чем маркируемых позиций, kit_write_refused — KIT отклонил коды или подтверждение; пусто — всё сходится'
        attention_detail:
          type: object
          additionalProperties: true
          description: 'Подробности: нераспознанные позиции (items: variant_id, sku, barcode, name), причина (reason), недостача кодов (missing, required), отказ KIT (action: marks | confirm, kit_code, kit_message) или отказ ядра (code, detail; missing_dimensions — недостающие обязательные разрезы учёта, например «ЦФО»)'
        last_seen_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DocflowYandexKitStateEnvelope:
      type: object
      additionalProperties: false
      required:
      - state
      properties:
        state:
          $ref: '#/components/schemas/DocflowYandexKitSyncState'
    DocflowYandexKitShippedOrder:
      type: object
      additionalProperties: false
      required:
      - order_id
      - order_number
      - shipment_ids
      properties:
        order_id:
          $ref: '#/components/schemas/UUID'
        order_number:
          type: integer
          format: int64
          description: Номер заказа KIT
        shipment_ids:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Проведённые отгрузки склада
    DocflowYandexKitHandover:
      type: object
      additionalProperties: false
      required:
      - confirm_mode
      - groups
      properties:
        confirm_mode:
          type: string
          enum:
          - kit
          - akeda
          description: Кто подтверждает заказ в KIT
        groups:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitHandoverGroup'
    DocflowYandexKitOrderList:
      type: object
      additionalProperties: false
      required:
      - orders
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitOrder'
    DocflowYandexKitHandoverOrder:
      type: object
      additionalProperties: false
      required:
      - order_id
      - kit_order_id
      - order_number
      - kit_status
      - tracking_number
      - state
      - waybill_at
      properties:
        order_id:
          $ref: '#/components/schemas/UUID'
        kit_order_id:
          type: string
          description: Идентификатор заказа в KIT
        order_number:
          type: integer
          format: int64
          description: Номер заказа, который видит покупатель
        kit_status:
          type: string
          description: Статус заказа в KIT
        tracking_number:
          type: string
        state:
          type: string
          enum:
          - picked
          - picking
          - unconfirmed
          - shipped
          description: picked — собран и может уехать, picking — ждёт сборки, unconfirmed — собран, но KIT ещё не подтвердил (режим akeda), shipped — отгрузка проведена
        waybill_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Когда заказ вошёл в акт курьеру; null — ещё не входил
    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.
    DocflowYandexKitShippedResult:
      type: object
      additionalProperties: false
      required:
      - delivery_service
      - shipped
      - already_shipped
      - waiting
      - failed
      properties:
        delivery_service:
          type: string
        shipped:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitShippedOrder'
          description: Проведено сейчас
        already_shipped:
          type: integer
          description: Уже были отгружены раньше
        waiting:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitHandoverOrder'
          description: Не собраны или не подтверждены в KIT — не тронуты
        failed:
          type: array
          items:
            $ref: '#/components/schemas/DocflowYandexKitShippedOrder'
          description: 'Склад не провёл отгрузку: заказ проводят из карточки исполнения'
    DocflowYandexKitSyncState:
      type: object
      additionalProperties: false
      required:
      - last_run_at
      - last_success_at
      - last_code
      - orders_seen
      - orders_changed
      - cursor_at
      - warning_code
      - stock_run_at
      - stock_code
      - stock_sent
      - stock_unmatched
      - stock_variants
      properties:
        last_run_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        last_success_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        last_code:
          type: string
          description: ok, token_rejected, rate_limited, unavailable, not_configured, retail_buyer_missing; пусто — опроса не было
        orders_seen:
          type: integer
        orders_changed:
          type: integer
        cursor_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: До какого момента изменения KIT прочитаны; null — опроса не было
        warning_code:
          type: string
          description: 'Режим подтверждения в подключении (options.confirm_mode) и в KIT разошёлся: kit_auto_confirm — в KIT осталось автоподтверждение, kit_manual_confirm — заказы ждут ручного подтверждения в KIT; пусто — расхождения не видно'
        stock_run_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Когда последний раз передавались остатки в KIT (options.stock_sync); null — не передавались
        stock_code:
          type: string
          description: 'Итог передачи остатков: ok, no_kit_warehouse — не выбран склад KIT, no_warehouse — не выбран склад кабинета, launch_pending — склад готовится к запуску и не передаётся, not_configured, token_rejected, rate_limited, unavailable; пусто — передача выключена'
        stock_sent:
          type: integer
          description: Сколько вариантов KIT передано за последний проход (только изменившиеся)
        stock_unmatched:
          type: integer
          description: 'Сколько вариантов KIT без нашего товара (или отвергнутых KIT): им остаток не передаётся'
        stock_variants:
          type: integer
          description: Сколько вариантов KIT всего
    UUID:
      type: string
      format: uuid
  responses:
    Unauthorized:
      description: Сессия, ключ или кабинет не подтверждены
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Некорректный запрос или нарушение бизнес-правила
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Запись не найдена или не видима текущему пользователю
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      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
- marketplace-wildberries
- marketplace-yandex
- marketplace-product-groups
- marketplace-accounting


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