---
title: "Завести карточки бумаг входящего письма"
method: POST
path: "/api/v1/docflow/mail-messages/{id}/papers"
tags: ["Docflow intake"]
---

# Завести карточки бумаг входящего письма

`POST /api/v1/docflow/mail-messages/{id}/papers`

## Request

- Base URL: `https://erp.akeda.ru`
- URL: `https://erp.akeda.ru/api/v1/docflow/mail-messages/{id}/papers`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://erp.akeda.ru/oauth2/authorize`, token URL `https://erp.akeda.ru/oauth2/token`, scopes: `akeda:delegate`)

«Создать в Документах» у письма (ERP-2633): по решению человека каждый файл письма получает СВОЮ входящую карточку документооборота (origin uploaded) от выбранного юрлица с выбранным контрагентом; файл вложения копируется в хранилище карточки на сервере, письмо остаётся источником карточки (mail_source). Решения по файлам — те же, что у пакета ЭДО: допсоглашение встаёт под договор связью amends, спецификация — attachment, договор называют карточкой (parent_card) или файлом-договором этого же письма (parent_attachment); счёт, акт, УПД и накладную можно сразу положить в закупку поставщика (order) связью basis; закупки нет — «Создать закупку» с заведённой бумаги. Счёт получает сумму и строки из своего PDF. Файл с видом skip карточки не получает; файл с карточкой второй раз не заводится — повтор команды безопасен. Карточка без пробелов регистрируется сразу. Проводок нет, наружу не уходит ничего. Ответ — разбор письма заново.

Отказы 400 с кодом и фразой: docflow.papers.empty, docflow.papers.attachment (вложения нет в письме или оно названо дважды), docflow.papers.kind, docflow.papers.parent, docflow.papers.order, docflow.papers.purpose — как у пакета ЭДО; docflow.mail_papers.company_required — юрлицо не выбрано и не узнано; docflow.mail_papers.too_many — вложений больше двадцати. Отказ 422 docflow.formats.invalid с проверкой docflow.edo.counterparty_required — контрагент не узнан и не назван полем contact_id. Отказы карточки — кодами docflow.flow.*.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Tenant` string, required

## Request body

- DocflowMailPapersInput: Команда «Создать в Документах»: решения по файлам письма — те же, что у пакета ЭДО, — плюс юрлицо и контрагент, если разбор их не узнал.
  - `papers` DocflowPackagePaperInput[], required: Решение по каждому принимаемому файлу письма, один файл — один раз; attachment — id вложения
    - `attachment` string, uuid, required
    - `kind` 'contract' | 'amendment' | 'specification' | 'invoice' | 'act' | 'upd' | 'goods_waybill' | 'reconciliation_act' | 'power_of_attorney' | 'other' | 'skip', required: Что человек назначает файлу пакета: договор, допсоглашение, спецификация, счёт, акт, УПД, товарная накладная, акт сверки, доверенность, прочее; skip — файл не бумага сделки (сопроводительное письмо, копия уже заведённого) и карточки не получает.
    - `parent_card` string, uuid
    - `parent_attachment` string, uuid
    - `purpose` 'terms' | 'deal': Назначение допсоглашения: terms — меняет условия договора, deal — отдельная покупка или продажа по договору. Только у вида amendment, у прочих игнорируется; не прислано — предложенное разбором
    - `order` string, uuid
    - `amount` string: Сумма счёта, акта, УПД или накладной словами человека, когда файл её не назвал (скан, Word): число больше нуля, копейки через точку. Сильнее прочитанной из файла; у прочих видов игнорируется. Неверная — 400 docflow.papers.amount
  - `company_id` string, uuid
  - `contact_id` string, uuid

## Response `200`

Письмо по бумагам после заведения: у принятых файлов заполнено card

- DocflowMailPapers: Входящее письмо, разобранное по файлам (ERP-2633): каждый файл — своя бумага со своей карточкой. Поля бумаг те же, что у пакета ЭДО.
  - `message` string, uuid, required
  - `papers` DocflowPackagePaper[], required: Файлы письма; attachment — id вложения письма
    - `attachment` string, uuid, required
    - `name` string, required: Имя файла словами оператора
    - `kind` string, required: Вид уже заведённой карточки, иначе предложенный разбором. Пустая строка — разбор не понял, вид выбирает человек. У файла с карточкой — любой вид документооборота, у остальных — из перечня DocflowPackagePaperKind.
    - `kind_source` '' | 'text' | 'name' | 'operator' | 'card', required: Откуда взят вид: text — по тексту первой страницы, name — по имени файла, operator — по слову оператора (только у пакета из одного файла), card — у файла уже есть карточка; пусто — вид не определён
    - `number` string: Номер бумаги, прочитанный из файла
    - `date` string: Дата бумаги в форме ГГГГ-ММ-ДД, прочитанная из файла
    - `amount` string: Сумма строкой, как в бумаге: через число с плавающей точкой теряются копейки
    - `currency` string: Валюта, если бумага её назвала; пусто — не сказано
    - `base_number` string: Номер договора, который бумага назвала основанием: «к договору 332/26» у ДС, «Основание: Договор № 332/26» у счёта
    - `base_date` string: Дата договора-основания, если бумага её назвала
    - `parent` DocflowPackagePaperParent: Договор, под которым стоит бумага: уже заведённая карточка (card) или файл-договор этого же пакета (attachment), которому карточку заведёт та же команда. Назван ровно один из двух.
      - `card` string, uuid
      - `attachment` string, uuid
      - `title` string: Название договора для показа человеку: заголовок карточки или имя файла
    - `card` DocflowMessageFlowLink: Карточка документооборота в пакете — обратная сторона связи edo_links карточки. Пакет доказывает отправку и подпись, а содержание живёт в карточке; здесь видно, чьё содержание он вёз и чем карточка ему приходится.
      - `id` string, uuid, required
      - `document` string, uuid, required
      - `role` 'primary' | 'attachment' | 'basis', required: Чем карточка приходится конверту: основной документ, приложение или основание
      - `version` integer, required: Текущая редакция карточки: открывать человеку следует её
      - `kind` 'contract' | 'specification' | 'amendment' | 'invoice' | 'act' | 'upd' | 'goods_waybill' | 'transport_waybill' | 'consignment_note' | 'transport_order' | 'tax_invoice' | 'correction' | 'return' | 'discrepancy_act' | 'reconciliation_act' | 'power_of_attorney' | 'letter' | 'memo' | 'decree' | 'directive' | 'minutes' | 'other', required: Вид документа внутреннего контура. Вид называет бумагу, а не учётную операцию: продажу и закупку из бумаги делают отдельные команды. Внутренние виды memo (служебная записка), decree (приказ), directive (распоряжение) и minutes (протокол) всегда имеют направление internal и живут без контрагента.
      - `status` 'draft' | 'registered' | 'archived', required
      - `title` string, required
      - `number` string, required
      - `date` string, date, required
      - `created_at` string, date-time, required
      - `external_attachment_id` string: Файл пакета, по которому заведена карточка (ERP-2063): идентификатор вложения у оператора (external_id), а без него — «id:» и id вложения. У пакета «ДС + счёт» своя карточка у каждого файла. Нет у карточки на весь пакет — так заводила приёмка до разбора по файлам
    - `order` DocflowPackagePaperOrder: Закупка, в которой лежит бумага пакета.
      - `id` string, uuid, required
      - `number` string
      - `title` string
    - `purpose` 'terms' | 'deal': Назначение допсоглашения: у заведённой карточки — её, иначе предложенное по тексту. terms — меняет условия договора, deal — отдельная покупка или продажа по договору. Только у вида amendment
    - `base_deal` string: Номер допсоглашения или спецификации, названный в основании счёта: «2» из «ДС № 2»
    - `deal` DocflowPackagePaperParent: Договор, под которым стоит бумага: уже заведённая карточка (card) или файл-договор этого же пакета (attachment), которому карточку заведёт та же команда. Назван ровно один из двух.
      - `card` string, uuid
      - `attachment` string, uuid
      - `title` string: Название договора для показа человеку: заголовок карточки или имя файла
  - `contracts` DocflowPackageContract[], required: Договоры контрагента у выбранного юрлица
    - `id` string, uuid, required
    - `title` string, required
    - `number` string
    - `date` string: Дата договора в форме ГГГГ-ММ-ДД
  - `purchases` DocflowIntakePurchase[], required: Открытые закупки этого поставщика у выбранного юрлица: в них кладут счёт, акт, УПД и накладную полем order команды
    - `order_id` string, uuid, required
    - `number` string, required: Номер закупки
    - `title` string
    - `date` string: Дата закупки ГГГГ-ММ-ДД
    - `amount` string, required: Заказано
    - `remaining` string, required: Осталось исполнить: заказано минус проведённые исполнения
    - `currency` string
    - `contract_number` string: Договор закупки
    - `contract_id` string, uuid
    - `deal_paper_id` string, uuid
    - `reason` 'linked' | 'amount' | 'open' | 'number' | 'lines', required: Почему предложена: linked — бумага уже лежит в ней; amount — остаток равен сумме бумаги; open — бумага помещается в остаток; в разнесении ВХ ещё number — номер счёта или договора из основания передачи совпал с бумагой или договором закупки, lines — её товарные строки покрывают товар ВХ
    - `pnl_item_required` boolean: Первому акту этой закупки нужна статья расходов: у закупки её нет, а операции заказа в финансах ещё нет. Приёмка без pnl_item_id ответит 409 docflow.edo.intake_pnl_item_required
    - `suggested_pnl_item` DocflowIntakePnlItem: Подсказка статьи расходов первого акта закупки (ERP-1810), по порядку: статья закупки, статья оплаты закупки или её счёта, статья последнего акта этого поставщика, правило разнесения контрагента. Только расходная статья ОПиУ в обращении.
      - `id` string, uuid, required
      - `name` string, required: Название статьи — так, как его назвал кабинет
      - `source` 'order' | 'payment' | 'last_act' | 'rule': Откуда подсказка: order — статья закупки; payment — статья её оплаты или оплаты её счёта; last_act — статья последнего акта поставщика; rule — правило разнесения контрагента
    - `goods` boolean: В закупке товар, и склад включён (ERP-1810): строки бумаги на товар закупки «Принять к учёту» заводит черновиком приёмки склада по закупке (проводит его склад), строки на услуги — актом поставщика
    - `warehouse_id` string, uuid
    - `warehouse_name` string: Название склада приёмки
  - `contact` string, uuid
  - `pending` integer, required: Сколько файлов ещё без карточки и не отмечены skip
  - `company_id` string, uuid
  - `companies` DocflowMailPaperCompany[], required: Наши юрлица, доступные человеку
    - `id` string, uuid, required
    - `name` string, required
    - `inn` string
  - `counterparty` DocflowIntakeCounterparty, required: Вторая сторона и то, с кем мы её свели. Порядок узнавания жёсткий, и каждая ступень сильнее следующей: решение человека этим же запросом, сопоставление зеркала пакета, ЗАПИСАННОЕ решение по этому участнику обмена и, наконец, поиск в справочнике по ИНН и КПП. Последняя ступень — догадка, и она называет себя догадкой (match: guess), а не выдаёт себя за чьё-то решение. Разбор у неё общий с автоматчем выгрузок: второй механизм узнавания рядом с существующим разошёлся бы с ним на первой же правке — молча и в пользу дубля. Неоднозначность не разрешается никогда: ИНН, совпавший у двух юрлиц, которых не развёл КПП, уходит человеку списком options.
    - `contact` string, uuid, required
    - `contact_name` string, required: Имя этой карточки в кабинете
    - `name` string, required: Имя стороны словами оператора либо файла продавца
    - `inn` string, required
    - `kpp` string, required
    - `match` 'manual' | 'auto' | 'guess' | 'email' | 'card' | 'none', required: Откуда взялся контрагент: manual — решение человека, auto — записанное сопоставление, guess — наша догадка по реквизитам прямо сейчас, нигде не записанная, email — по адресу отправителя письма, card — как у карточек, уже заведённых из этого письма (бумаги письма), none — не свели ни с кем
    - `options` DocflowIntakeCounterpartyOption[]: Наши контрагенты с тем же ИНН, когда выбрать между ними обязан человек. Непустой список означает «такие у нас уже есть, выбери» — и потому же означает, что заводить нового НЕ НАДО: там, где контрагент с такими реквизитами уже заведён, место кнопке «связать с существующим», а не «завести».
      - `id` string, uuid, required
      - `name` string, required
      - `kpp` string, required
  - `sender` DocflowMailPaperSender, required: Отправитель, тема и дата письма.
    - `email` string, required
    - `name` string
    - `subject` string
    - `date` string, date-time: Когда письмо получено

## Other responses

- `400`: Некорректный запрос или нарушение бизнес-правила
- `401`: Сессия, ключ или кабинет не подтверждены
- `403`: Текущая роль не имеет требуемого права
- `404`: Запись не найдена или не видима текущему пользователю
- `409`: Конфликт версии, идемпотентности или бизнес-состояния
- `422`: Запрос разобран, но бизнес-значение недопустимо

## Changes

- **2026-10-20** `765c65fadf8f`: 7 warning
  - added the new `decree` enum value to the `papers/items/card/allOf[#/components/schemas/DocflowMessageFlowLink]/kind` response property for the response status `200`
  - added the new `directive` enum value to the `papers/items/card/allOf[#/components/schemas/DocflowMessageFlowLink]/kind` response property for the response status `200`
  - added the new `letter` enum value to the `papers/items/card/allOf[#/components/schemas/DocflowMessageFlowLink]/kind` response property for the response status `200`
  - added the new `lines` enum value to the `purchases/items/reason` response property for the response status `200`
  - …3 more
- **2026-10-20** `408f7294f7a9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/akeda/apis/akeda-erp-client-api/changes/api/v1/docflow/mail-messages/:id/papers/post.md)

---

[API](https://skmtc.dev/akeda/apis/akeda-erp-client-api.md) · [All operations](https://skmtc.dev/akeda/apis/akeda-erp-client-api/llms.txt) · [OpenAPI document](https://skmtc.dev/akeda/apis/akeda-erp-client-api/revisions/7a6b75f272ee?raw)