Маршруты документов¶
Группа маршрутов /api/documents отвечает за работу с извлечёнными документами --- результатами обработки загруженных файлов. Каждый документ представляет собой один распознанный документ (акт, договор, счёт и т. д.), найденный внутри многостраничного PDF-файла.
Исходный файл: backend/app/api/routes/documents.py.
Получение списка документов¶
GET /api/documents/¶
Возвращает список документов с постраничным выводом. Сортировка --- по номеру начальной страницы.
Параметры запроса:
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
job_id |
строка | --- | Показать только документы из указанного задания |
doc_type |
строка | --- | Фильтр по типу документа (например, «Акт», «Договор») |
group_id |
строка | --- | Показать только документы из указанной группы |
ungrouped |
логическое | --- | Если true --- только документы, не входящие ни в одну группу |
has_error |
логическое | --- | Фильтр по наличию отметки об ошибке |
skip |
число | 0 | Сколько записей пропустить |
limit |
число | 50 | Максимальное количество записей |
Каждый документ в ответе содержит: идентификатор, идентификатор задания, заголовок, тип и подтип документа, диапазон страниц, источник, ориентацию и поворот страницы, уверенность распознавания, данные, извлечённые из содержимого (from_content) и из имени файла (from_filename), приведённые данные (normalized), принадлежность к группе, признак основного документа группы, отметку ошибки с комментарием, пути к файлу и изображению предпросмотра, дату создания.
Поиск документов¶
GET /api/documents/search¶
Полнотекстовый поиск по всем полям документов. Минимальная длина запроса --- 2 символа. Поиск не зависит от регистра.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
q |
строка | Поисковый запрос (обязательный, минимум 2 символа) |
doc_type |
строка | Дополнительный фильтр по типу документа |
has_error |
логическое | Фильтр по наличию отметки об ошибке |
skip |
число | Сколько записей пропустить |
limit |
число | Максимальное количество записей |
Поиск ведётся по следующим полям:
- заголовок документа;
- тип документа;
- номер, дата, стороны, контрагент, договор, системные номера, месторождение, название проекта, наименования позиций (из содержимого);
- контрагент, договор, бухгалтерский номер, элемент СПП (из имени файла);
- комментарий к ошибке.
Результат отсортирован по дате создания --- от новых к старым.
GET /api/documents/search/count¶
Возвращает количество документов, найденных по поисковому запросу. Принимает те же параметры q и doc_type, что и адрес поиска. Используется для отображения числа результатов без загрузки самих документов.
Получение одного документа¶
GET /api/documents/{document_id}¶
Возвращает полные сведения о документе по его идентификатору.
Просмотр и скачивание файлов¶
GET /api/documents/{document_id}/view¶
Возвращает PDF-файл документа для просмотра в браузере. Файл передаётся напрямую через серверную часть. Заголовки ответа разрешают встраивание в iframe.
GET /api/documents/{document_id}/download¶
Возвращает PDF-файл документа для скачивания. Браузер предложит сохранить файл на диск.
GET /api/documents/{document_id}/preview¶
Возвращает изображение предпросмотра документа (JPEG или PNG). Результат кэшируется браузером на 24 часа.
GET /api/documents/{document_id}/download-url¶
Возвращает временную ссылку на скачивание файла напрямую из хранилища MinIO. Ссылка действительна 24 часа.
GET /api/documents/{document_id}/preview-url¶
Возвращает временную ссылку на изображение предпросмотра напрямую из хранилища MinIO. Ссылка действительна 24 часа.
Статистика по типам¶
GET /api/documents/stats/by-type¶
Возвращает распределение документов по типам и подтипам. Для каждой комбинации типа и подтипа подсчитываются количество документов и средняя уверенность распознавания.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
job_id |
строка | Ограничить статистику конкретным заданием |
Результат отсортирован по убыванию количества.
Отметка ошибок¶
PATCH /api/documents/{document_id}/error¶
Позволяет поставить или снять отметку об ошибке в документе.
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
has_error |
логическое | true --- поставить отметку, false --- снять |
comment |
строка | Комментарий к ошибке (необязательный, сохраняется только при has_error = true) |
При установке отметки сохраняются комментарий и дата. При снятии --- комментарий и дата очищаются.
Ручная правка полей¶
PATCH /api/documents/{document_id}/fields¶
Обновляет поля документа вручную. Можно изменить поля из раздела from_content (извлечённые из содержимого) и from_filename (извлечённые из имени файла).
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
from_content |
объект | Словарь «имя поля --- новое значение» для данных из содержимого |
from_filename |
объект | Словарь «имя поля --- новое значение» для данных из имени файла |
При первом редактировании каждого поля исходное значение сохраняется в разделе manual_edits, чтобы его можно было восстановить. При повторном редактировании обновляется только дата последнего изменения.
Ответ возвращает обновлённый документ целиком.
POST /api/documents/{document_id}/fields/revert¶
Откатывает поле к исходному значению, которое было до ручной правки.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
field_path |
строка | Путь к полю, например from_content.number |
Если поле не было отредактировано вручную --- возвращается ошибка. После отката запись о правке удаляется из manual_edits.
Связанные реестры¶
GET /api/documents/{document_id}/registries¶
Возвращает список реестров, в которых найден данный документ. Для каждого реестра показываются строки, в которых документ указан как совпадение, с баллами и признаком подтверждения.
Ответ содержит:
- сведения о реестре (идентификатор, имя файла, лист, состояние, статистика);
- список строк реестра, в которых найден документ (номер строки, привязанные данные, состояние, балл совпадения, признак подтверждения);
- общее число строк с этим документом;
- количество подтверждённых совпадений.