Akeda Docflow tax API

openapi: 3.2.0
info:
  title: Akeda ERP Client Docflow tax 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 tax
  description: 'Модуль docflow (документы) — раздел «Налоговая»: требования, письма и рассылки госорганов и статусы сданной отчётности из ленты отчётности оператора. Только чтение и одна локальная отметка «ответ дан»: квитанцию, ответ и отчётность подписывают у оператора. В регистры раздел не пишет ничего'
paths:
  /api/v1/docflow/gov/summary:
    get:
      tags:
      - Docflow tax
      operationId: docflowGovSummary
      x-akeda-audience: external
      summary: Сводка раздела «Налоговая»
      description: 'Счётчики частей раздела (требования, письма и рассылки, отчёты), сколько требований ещё ждут квитанции или ответа и сколько из них просрочены или близки к блокировке счёта, и доступ каждого подключения к ленте отчётности оператора. access=denied — оператор отказал приложению в разделе «Отчётность»: note несёт его слова, чинится это в правах приложения у оператора.'
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-permission: docflow.edo:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      responses:
        '200':
          description: Сводка раздела
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowGovSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/docflow/gov/documents:
    get:
      tags:
      - Docflow tax
      operationId: docflowGovDocuments
      x-akeda-audience: external
      summary: Документы госорганов
      description: 'Список части раздела: claims — требования со сроками «Квитанция до» и «Ответ до» (рабочие дни пн–пт, производственного календаря нет), letters — входящие письма и рассылки, наши письма, заявления и ответы, reports — сданные отчёты и квитанции по ним. Состояние требования приходит кодом оператора (0/3/4/6/7/9/41/10) и его словами; urgency считает сервер на сегодняшний день.'
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-permission: docflow.edo:read
      parameters:
      - $ref: '#/components/parameters/TenantHeader'
      - name: part
        in: query
        description: Часть раздела
        schema:
          type: string
          enum:
          - claims
          - letters
          - reports
          default: claims
      - name: open
        in: query
        description: 1 — только требования, которые ждут квитанции или ответа
        schema:
          type: string
          enum:
          - '1'
      - name: company
        in: query
        description: Юрлицо подключения
        schema:
          $ref: '#/components/schemas/UUID'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Документы части раздела
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocflowGovList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/docflow/gov/documents/{id}:
    get:
      tags:
      - Docflow tax
      operationId: docflowGovDocument
      x-akeda-audience: external
      summary: Карточка документа госоргана
      description: 'Документ госоргана с файлами и событиями пакета. operator_link — карточка у оператора («СсылкаДляНашаОрганизация»): там отвечают и подписывают. Пакет не госоргана отвечает 404.'
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-permission: docflow.edo:read
      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/DocflowGovDocument'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/docflow/gov/documents/{id}/answered:
    post:
      tags:
      - Docflow tax
      operationId: docflowMarkGovAnswered
      x-akeda-audience: external
      summary: Отметить «ответ дан»
      description: 'Локальная отметка у требования: ответ ушёл мимо ленты оператора (бумагой, лично, через другого оператора). Оператору ничего не уходит; требование уходит из «Ждут меня». Не требование — 400 docflow.gov.invalid.'
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-permission: docflow.edo:write
      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/DocflowGovDocument'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags:
      - Docflow tax
      operationId: docflowUnmarkGovAnswered
      x-akeda-audience: external
      summary: Снять отметку «ответ дан»
      description: Снимает ручную отметку. Ответ, увиденный в ленте оператора, снять нельзя — 409 docflow.gov.answer_from_operator.
      security:
      - erpUserToken: []
      - mcpOAuth:
        - akeda:delegate
      x-akeda-module: docflow
      x-akeda-release-stage: preview
      x-akeda-permission: docflow.edo:write
      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/DocflowGovDocument'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    DocflowAttachment:
      type: object
      additionalProperties: false
      description: 'Файл внутри пакета. Внутреннего пути в хранилище здесь нет: снаружи файл получают отдельной операцией, а путь не часть контракта и не подсказка для перебора.'
      required:
      - id
      - message
      - external_id
      - name
      - kind
      - content_type
      - size_bytes
      - sha256
      - stored
      - created_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        message:
          $ref: '#/components/schemas/UUID'
        external_id:
          type: string
          description: Идентификатор вложения у оператора
        name:
          type: string
          description: Имя файла словами оператора
        kind:
          type: string
          enum:
          - ''
          - document
          - title
          - notice
          description: 'Наш словарь, а не оператора: документ, ответный титул, служебное извещение. Пусто означает, что вид неизвестен, и это законно'
        content_type:
          type: string
        size_bytes:
          type: integer
          format: int64
        sha256:
          type: string
        stored:
          type: boolean
          description: 'Байты скачаны и лежат у НАС. Ссылка оператора хранилищем не считается: она живёт около месяца, а накладную спрашивают через три года'
        downloaded_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    DocflowGovConnectionState:
      type: object
      additionalProperties: false
      required:
      - connection
      - company
      - company_name
      - access
      - checked_at
      - note
      properties:
        connection:
          $ref: '#/components/schemas/UUID'
        company:
          type:
          - string
          - 'null'
          format: uuid
        company_name:
          type: string
        access:
          type: string
          enum:
          - ''
          - ok
          - denied
          - failed
          description: Пусто — ленту отчётности ещё не читали
        checked_at:
          type:
          - string
          - 'null'
          format: date-time
        note:
          type: string
          description: Слова оператора при отказе
    DocflowEvent:
      type: object
      additionalProperties: false
      description: Событие ленты пакета. Лента — то, по чему человек восстанавливает ход спора с контрагентом, поэтому название и комментарий хранятся словами оператора и не переводятся.
      required:
      - id
      - message
      - external_id
      - name
      - comment
      - created_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        message:
          $ref: '#/components/schemas/UUID'
        external_id:
          type: string
        name:
          type: string
        comment:
          type: string
        occurred_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    DocflowGovSummary:
      type: object
      additionalProperties: false
      required:
      - claims
      - claims_open
      - claims_urgent
      - letters
      - reports
      - connections
      properties:
        claims:
          type: integer
        claims_open:
          type: integer
        claims_urgent:
          type: integer
        letters:
          type: integer
        reports:
          type: integer
        connections:
          type: array
          items:
            $ref: '#/components/schemas/DocflowGovConnectionState'
    DocflowGovList:
      type: object
      additionalProperties: false
      required:
      - count
      - results
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/DocflowGovDocument'
    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.
    DocflowGovDocument:
      type: object
      additionalProperties: false
      description: Документ госоргана в зеркале оператора. doc_type, doc_subtype, state_code и state_name — слова оператора; kind, claim_kind и authority — наш вид по одному правилу сервера. Сроки — календарные даты ГГГГ-ММ-ДД; пустая строка — срока нет (не требование или дата отправки неизвестна).
      required:
      - id
      - connection
      - company
      - company_name
      - kind
      - claim_kind
      - authority
      - authority_name
      - authority_code
      - external_id
      - doc_type
      - doc_subtype
      - number
      - date
      - note
      - kit_id
      - state_code
      - state_name
      - state_description
      - sent_on
      - receipt_due
      - answer_due
      - block_after
      - receipt_sent_at
      - answered_at
      - answered_by
      - answered_by_name
      - answer_message
      - receipt_pending
      - answer_pending
      - receipt_late
      - answer_late
      - open
      - urgency
      - operator_link
      - received_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        connection:
          $ref: '#/components/schemas/UUID'
        company:
          type:
          - string
          - 'null'
          format: uuid
        company_name:
          type: string
        kind:
          type: string
          enum:
          - claim
          - letter
          - outgoing
          - answer
          - receipt
          - report
        claim_kind:
          type: string
          enum:
          - ''
          - explanations
          - documents
          - general
        authority:
          type: string
          description: fns, sfr, rosstat, fsrar, rpn или пусто
        authority_name:
          type: string
        authority_code:
          type: string
        external_id:
          type: string
        doc_type:
          type: string
        doc_subtype:
          type: string
        number:
          type: string
        date:
          type: string
        note:
          type: string
        kit_id:
          type: string
        state_code:
          type: string
        state_name:
          type: string
        state_description:
          type: string
        sent_on:
          type: string
        receipt_due:
          type: string
        answer_due:
          type: string
        block_after:
          type: string
          description: С этого дня без квитанции инспекция вправе приостановить операции по счетам
        receipt_sent_at:
          type:
          - string
          - 'null'
          format: date-time
        answered_at:
          type:
          - string
          - 'null'
          format: date-time
        answered_by:
          type:
          - integer
          - 'null'
          format: int64
          description: Сотрудник, отметивший ответ вручную; null — ответ виден в ленте или его нет
        answered_by_name:
          type: string
        answer_message:
          type:
          - string
          - 'null'
          format: uuid
        receipt_pending:
          type: boolean
        answer_pending:
          type: boolean
        receipt_late:
          type: boolean
          description: Срок квитанции прошёл или до блокировки счёта не больше двух рабочих дней, а квитанции нет
        answer_late:
          type: boolean
          description: Срок ответа прошёл, а ответа нет
        open:
          type: boolean
        urgency:
          type: string
          enum:
          - ''
          - soon
          - overdue
          - blocking
        operator_link:
          type: string
        received_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type: string
          format: date-time
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/DocflowAttachment'
        events:
          type: array
          items:
            $ref: '#/components/schemas/DocflowEvent'
    UUID:
      type: string
      format: uuid
  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'
    Conflict:
      description: Конфликт версии, идемпотентности или бизнес-состояния
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: Внешний банк, справочник или контур подключений временно недоступен
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Запись не найдена или не видима текущему пользователю
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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