# 将 Paperless-ngx 接入 Open Flow

Source: https://openflow.run/zh-cn/integrations/paperless_ngx/

[全部集成](https://openflow.run/zh-cn/integrations/)

让 AI 查找合同、提取发票信息，或为归档文档统一标题和标签。

*   [139 个工具](https://openflow.run/zh-cn/integrations/paperless_ngx/#integration-actions)
*   API 密钥
*   文档与内容
*   效率工具

[连接 Paperless-ngx](https://console.openflow.run/connections/paperless_ngx)

每月 20,000 次免费应用调用（付费服务另计）

## 可以做什么

搜索文档正文和元数据，读取归档记录、更新分类，并取回原始文件或归档文件。连接也支持文档上传、PDF 操作和档案管理，具体取决于你的权限。

### 总结归档文档

搜索归档并读取选定文档的提取文本。

### 整理文档元数据

读取当前元数据后，应用指定标题或分类变更。

### 取得归档文件

通过临时下载链接取回归档文档。

### 导入和整理文档文件

通过文件 URL 上传文档、合并 PDF，或把选中的档案导出为 ZIP 压缩包。

## 所有工具

139 个工具

### List Documents

列出或搜索已连接用户可见的文档，默认每页 25 条。过滤条件与 Paperless-ngx 的查询参数一一对应：id、标题、归档序列号、日期、联系人、文档类型、存储路径、标签、所有者、自定义字段、MIME 类型与内容查找可以组合使用；未建模的参数放入 additional\_filters。query、text、title\_search 与 more\_like\_id 改为走搜索索引查询，结果带 \_\_search\_hit\_\_ 并按相关度排序，每次调用只能使用其中一个。只列出根文档；文件版本出现在每个文档的 versions 数组里。需要 view\_document 权限。

`paperless_ngx.list_documents`

### Get Document

获取单个文档及其元数据、标签、自定义字段、备注、文件版本与 duplicate\_documents (校验和相同的其他文档)。content 为最新版本提取出的文本，除非用 version 选择了其他版本。需要 view\_document 权限以及对该文档的查看权限。

`paperless_ngx.get_document`

### Update Document

部分更新一个文档：标题、内容、联系人、文档类型、存储路径、标签、创建日期、归档序列号、自定义字段、移除收件箱标签、所有者与对象权限。只发送提供的字段 (PATCH)；tags 与 custom\_fields 会替换整个列表。修改 owner 或 set\_permissions 需要是所有者或超级用户。响应带完整的 permissions 对象。需要 change\_document 权限以及对该文档的修改权限。

`paperless_ngx.update_document`

### Delete Document

把一个文档及其全部文件版本移入回收站。回收站中的文档在配置的回收站保留期 (默认 30 天) 到期前可以恢复，并会立即从搜索索引中移除。需要 delete\_document 权限以及对该文档的删除权限。

`paperless_ngx.delete_document`

### Get Document Root

解析任意文档 id 对应的根文档，包括文件版本的 id 与回收站中文档的 id。对根文档而言答案就是它自己的 id。需要对根文档的查看权限。

`paperless_ngx.get_document_root`

### Get Document Metadata

获取文档的文件级元数据：校验和、大小、MIME 类型、媒体文件名、是否存在归档 PDF、原始文件与归档文件的解析器元数据 (例如 PDF 信息与 XMP 字段)，以及检测到的内容语言。未给 version 时读取最新版本。需要对该文档的查看权限。

`paperless_ngx.get_document_metadata`

### Get Document Suggestions

根据匹配规则与训练好的分类器，获取文档的联系人、标签、文档类型、存储路径与日期建议。结果会缓存，直到文档或分类器发生变化。需要对该文档的修改权限 (否则 403)。

`paperless_ngx.get_document_suggestions`

### Get Document Ai Suggestions

让配置好的语言模型为文档给出标题、标签、联系人、文档类型、存储路径与日期建议。模型选中的已有对象以 id 返回，它提议的新名称单独返回。需要实例启用 AI：否则 Paperless-ngx 返回 400 AI is required for this feature，AI 配置无效时返回 400，模型超时时返回 503。调用会在模型作答期间阻塞，并需要对该文档的修改权限。

`paperless_ngx.get_document_ai_suggestions`

### Download Document

下载文档的文件，并以临时的连接器文件 URL 返回。默认在存在归档 PDF 时提供归档 PDF，否则提供原始上传文件；original=true 时始终提供原始文件。Paperless-ngx 的 preview 端点提供完全相同的字节，只是以内联方式返回，因此不作为单独的 action 暴露。对回收站中的文档与文件版本同样有效。需要对该文档的查看权限；超过 200 MiB 的文件会被拒绝。

`paperless_ngx.download_document`

### Get Document Thumbnail

下载文档 (或其某个文件版本) 的 WebP 缩略图，并以临时的连接器文件 URL 返回。需要对该文档的查看权限。

`paperless_ngx.get_document_thumbnail`

### List Document Notes

列出附加在文档上的备注，最新的在前，每条都带作者。需要 view\_note 权限以及对该文档的查看权限。

`paperless_ngx.list_document_notes`

### Add Document Note

以已连接用户的身份给文档添加一条备注，并返回完整的备注列表。同时会更新文档的 modified 时间戳并重新建立索引。需要 add\_note 权限以及对该文档的修改权限。

`paperless_ngx.add_document_note`

### Delete Document Note

删除文档上的一条备注，并返回剩余的备注。需要 delete\_note 权限以及对该文档的修改权限；备注 id 不属于该文档时返回 404。

`paperless_ngx.delete_document_note`

### List Document Share Links

列出文档尚未过期的分享链接，最新的在前。需要对该文档的修改权限 (Paperless-ngx 把读取分享链接视为分享操作)。

`paperless_ngx.list_document_share_links`

### Get Document History

获取文档的审计记录：该文档及其自定义字段值的每一条已记录的创建、更新、删除与访问条目，最新的在前，附带变更的字段与操作用户。需要实例启用审计日志 (PAPERLESS\_AUDIT\_LOG\_ENABLED，否则返回 400 Audit log is disabled)、auditlog.view\_logentry 权限，并且已连接用户必须是文档所有者或超级用户，或者文档没有所有者。

`paperless_ngx.get_document_history`

### Email Document

通过 Paperless-ngx 实例上配置的邮件服务器，把一个文档作为邮件附件发送。存在归档 PDF 时附加归档 PDF，除非 use\_archive\_version 为 false。Paperless-ngx 会经由其集合级 email 端点、以单个文档 id 处理此请求。需要 view\_document 权限、对该文档的查看权限，以及已配置的外发邮件服务器 (否则返回 500 Error emailing documents)。

`paperless_ngx.email_document`

### Email Documents

通过 Paperless-ngx 实例上配置的邮件服务器，把多个文档作为同一封邮件的附件发送。存在归档 PDF 时附加归档 PDF，除非 use\_archive\_version 为 false。需要 view\_document 权限、对每个文档的查看权限 (否则 403)，以及已配置的外发邮件服务器 (否则返回 500 Error emailing documents)。

`paperless_ngx.email_documents`

### Update Document Version

为文档上传一个新的文件版本。连接器在服务端下载 fileUrl，并以 multipart 表单字段 document 提交；Paperless-ngx 在后台把它作为根文档的新版本消费，标题、标签等元数据保持共享。返回 Celery 任务 id，用 get\_task 轮询。需要 change\_document 权限以及对根文档的修改权限；不支持的文件类型会以 400 拒绝。

`paperless_ngx.update_document_version`

### Delete Document Version

永久删除文档的一个非根文件版本。根 (原始) 版本不能用这种方式删除，请改为删除文档 (否则返回 400)。需要对根文档的删除权限。

`paperless_ngx.delete_document_version`

### Update Document Version Label

设置或清除文档某个文件版本 (包括根版本) 的标签。需要对根文档的修改权限。

`paperless_ngx.update_document_version_label`

### Get Next Asn

获取下一个可用的归档序列号：当前使用中的最大 ASN 加 1，尚未分配任何 ASN 时为 1。回收站中的文档仍会占用其 ASN。

`paperless_ngx.get_next_asn`

### Upload Document

上传一个文件，作为新文档进行消费。连接器在服务端下载 fileUrl (最多 100 MiB)，并以 multipart 表单字段 document 连同可选的标题、创建日期、联系人、文档类型、存储路径、标签、归档序列号与自定义字段值一起提交。Paperless-ngx 从字节嗅探文件类型，不支持的类型以 400 拒绝；消费过程 (OCR、匹配、工作流) 在后台运行，因此此 action 返回 Celery 任务 id，用 get\_task 轮询，成功后其 result\_data.document\_id 即为新文档。已连接用户会成为所有者。需要 add\_document 权限。

`paperless_ngx.upload_document`

### Bulk Edit Documents

对多个文档一次性应用同一项元数据修改: 设置 correspondent、document type 或 storage path, 添加或移除标签, 添加或移除自定义字段, 或替换所有者与权限。可显式列出文档, 也可用 all 加 filters 选择。元数据类方法需要全局 change\_document 权限以及对每个文档的修改权限; set\_permissions 还要求已连接用户拥有每个文档 (或文档无所有者), 超级用户除外。旧版文档编辑方法 (delete、reprocess、rotate、merge、split、delete\_pages、edit\_pdf、remove\_password) 仍被接受但已弃用, 请改用对应的专用 action。

`paperless_ngx.bulk_edit_documents`

### Delete Documents

把文档移入回收站 (软删除)。所选根文档的各个版本会一并移入回收站。回收站中的文档可通过 list\_trash 查看, 并在回收站清空前通过 restore\_trash\_documents 恢复; 回收站会在实例配置的保留期 (默认 30 天) 后自动清空。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还需要全局 delete\_document 权限, 且已连接用户须拥有每个文档 (或文档无所有者)。

`paperless_ngx.delete_documents`

### Reprocess Documents

基于原始文件重新解析文档 (文本提取、OCR 与归档 PDF 生成)。每个文档会作为单独的后台任务排队, 任务完成后其内容与归档文件会被替换; 任务入队后即返回 OK。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。

`paperless_ngx.reprocess_documents`

### Rotate Documents

把所选 PDF 文档的每一页旋转指定的度数。旋转后的文件会在后台作为每个根文档的新版本被消费, 并保留其元数据; 非 PDF 文档会被跳过并记录警告, 响应仍为 OK。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还要求已连接用户拥有每个文档 (或文档无所有者)。

`paperless_ngx.rotate_documents`

### Merge Documents

把给定文档的 PDF 按给定顺序合并成一个新文档, 新文档在后台被消费并归已连接用户所有。文件无法作为 PDF 读取的文档会被跳过。指定 metadata\_document\_id 时, 新文档会复制该文档的元数据, 并使用其标题加上 " (merged)" 后缀。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还需要全局 add\_document 权限; 若设置 delete\_originals, 则还需要全局 delete\_document 权限以及对每个文档的所有权。

`paperless_ngx.merge_documents`

### Merge Documents As Versions

把现有的顶层文档变成某个根文档的文件版本, 不创建新文件。来源文档会从文档列表中消失, 放弃其 archive serial number (根文档若没有则接收第一个), 并立即成为根文档的版本。只能选择顶层文档, 且来源文档自身不能已有版本。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还要求拥有每个文档 (或文档无所有者) 以及全局 delete\_document 权限。

`paperless_ngx.merge_documents_as_versions`

### Edit Document Pdf

根据页面操作列表重建单个文档的 PDF: 保留、重排、复制、旋转或丢弃页面, 并可选地拆分为多个输出文档。默认情况下每个输出会在后台作为归已连接用户所有的新文档被消费 (include\_metadata 为 true 时复制元数据), delete\_original 会在之后把来源文档移入回收站, 只有一个输出时还会转移其 archive serial number。update\_document 为 true 时, 单个输出会作为同一文档的新版本被消费。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还要求拥有该文档 (或文档无所有者), update\_document 不为 true 时需要全局 add\_document 权限, delete\_original 为 true 时需要全局 delete\_document 权限。

`paperless_ngx.edit_document_pdf`

### Remove Document Password

使用给定密码移除加密 PDF 文档的密码保护。未加密的文档会被跳过。默认情况下, 去除保护后的 PDF 会在后台作为归已连接用户所有的新文档被消费 (include\_metadata 为 true 时复制元数据), delete\_original 会在之后把受保护的原件移入回收站; update\_document 为 true 时, 它会成为同一文档的新版本。密码错误会使整个请求以 400 失败。需要全局 change\_document 权限以及对每个所选文档的修改权限 (否则返回 403 Insufficient permissions); 超级用户跳过这些检查。还要求拥有每个文档 (或文档无所有者), update\_document 不为 true 时需要全局 add\_document 权限, delete\_original 为 true 且未设置 update\_document 时需要全局 delete\_document 权限。

`paperless_ngx.remove_document_password`

### Bulk Download Documents

把多个文档打包成一个 zip 归档下载, 并以临时的连接器文件 URL 返回。可显式列出文档, 也可用 all 加 filters 选择; 打包的是每个根文档的最新版本。content 选择归档 PDF (文档没有归档版本时回退到原件)、原始文件或两者; follow\_formatting 会按已配置的文件名格式而不是文档标题来命名压缩包内的条目。zip 在实例上生成, 可能需要一些时间; 大小须低于连接器的 500 MiB 限制。需要对每个文档的查看权限 (否则返回 403)。

`paperless_ngx.bulk_download_documents`

### Get Selection Data

对一组文档, 统计其中有多少文档使用了每个 correspondent、标签、document type、storage path 与自定义字段。每种对象都会全部返回, 包括没有任何所给文档使用的对象, 便于调用方在批量编辑前判断某个对象是应用于全部、部分还是没有所选文档。每个文档都必须存在 (否则返回 400) 且对已连接用户可见 (否则返回 403)。

`paperless_ngx.get_selection_data`

### List Trash

列出当前在回收站中 (已软删除) 的文档, 按创建时间从新到旧排序, 字段与普通文档相同并附带 deleted\_at。超级用户可看到所有回收站文档; 其他用户只能看到自己拥有或无所有者的回收站文档, 显式共享不计入。该端点只支持分页, 不支持过滤或排序。

`paperless_ngx.list_trash`

### Restore Trash Documents

从回收站恢复文档, 使其重新出现在文档列表中并被重新加入搜索索引。每个 id 都必须是回收站中的文档 (否则返回 400), 且已连接用户需要对其中每个文档的删除权限 (否则返回 403)。

`paperless_ngx.restore_trash_documents`

### Empty Trash

永久删除回收站中的文档及其文件。省略 documents 时, 会删除已连接用户在 list\_trash 中能看到的所有回收站文档 (超级用户则是全部)。此操作不可撤销。已连接用户需要对每个受影响文档的删除权限 (否则返回 403)。

`paperless_ngx.empty_trash`

### Chat With Documents

向 Paperless-ngx AI 助手提问, 答案基于你的文档生成 (基于 LLM 索引的检索增强生成)。指定 document\_id 时, 答案只基于该文档, 该文档必须存在 (否则返回 400 Document not found) 且对已连接用户可见 (否则返回 403); 未指定时会搜索用户可见的所有文档。需要在应用配置中启用 AI (否则返回 400 AI is required for this feature)、全局 view\_document 权限以及已构建的 LLM 索引。Paperless-ngx 以流式方式返回回答; 连接器会等待流结束后返回完整文本。

`paperless_ngx.chat_with_documents`

### List Tags

列出连接用户可见的标签，包含文档数量与嵌套子标签。支持 id 与不区分大小写的名称过滤、仅取顶层标签的 is\_root 开关、排序与分页。需要 view\_tag 权限。

`paperless_ngx.list_tags`

### Get Tag

按 id 获取单个标签，包含文档数量、父标签与嵌套子标签。需要对该标签的 view\_tag 权限。

`paperless_ngx.get_tag`

### Create Tag

创建标签，可选设置颜色、匹配规则、收件箱标记与父标签。所有者默认为连接用户。需要 add\_tag 权限。

`paperless_ngx.create_tag`

### Update Tag

部分更新标签；只修改提供的字段，null 会清空 parent 这类可空字段。需要对该标签的 change\_tag 权限；修改 owner 或 set\_permissions 还要求是所有者或超级用户。

`paperless_ngx.update_tag`

### Delete Tag

删除标签。文档保留其余标签；子标签由树形模型重新挂载。需要对该标签的 delete\_tag 权限。

`paperless_ngx.delete_tag`

### List Correspondents

列出连接用户可见的联系人(correspondent)，包含文档数量。支持 id 与不区分大小写的名称过滤、排序与分页；将 last\_correspondence 设为 true 可附带每个联系人最新文档的日期。需要 view\_correspondent 权限。

`paperless_ngx.list_correspondents`

### Get Correspondent

按 id 获取单个联系人，包含文档数量与 last\_correspondence 日期。需要对该联系人的 view\_correspondent 权限。

`paperless_ngx.get_correspondent`

### Create Correspondent

创建联系人，可选设置匹配规则。所有者默认为连接用户。需要 add\_correspondent 权限。

`paperless_ngx.create_correspondent`

### Update Correspondent

部分更新联系人；只修改提供的字段。需要对该联系人的 change\_correspondent 权限；修改 owner 或 set\_permissions 还要求是所有者或超级用户。

`paperless_ngx.update_correspondent`

### Delete Correspondent

删除联系人。使用过它的文档将不再有联系人。需要对该联系人的 delete\_correspondent 权限。

`paperless_ngx.delete_correspondent`

### List Document Types

列出连接用户可见的文档类型，包含文档数量。支持 id 与不区分大小写的名称过滤、排序与分页。需要 view\_documenttype 权限。

`paperless_ngx.list_document_types`

### Get Document Type

按 id 获取单个文档类型，包含文档数量。需要对该文档类型的 view\_documenttype 权限。

`paperless_ngx.get_document_type`

### Create Document Type

创建文档类型，可选设置匹配规则。所有者默认为连接用户。需要 add\_documenttype 权限。

`paperless_ngx.create_document_type`

### Update Document Type

部分更新文档类型；只修改提供的字段。需要对该文档类型的 change\_documenttype 权限；修改 owner 或 set\_permissions 还要求是所有者或超级用户。

`paperless_ngx.update_document_type`

### Delete Document Type

删除文档类型。使用过它的文档将不再有文档类型。需要对该文档类型的 delete\_documenttype 权限。

`paperless_ngx.delete_document_type`

### List Storage Paths

列出连接用户可见的存储路径，包含文档数量。支持 id 以及不区分大小写的名称与路径过滤、排序与分页。需要 view\_storagepath 权限。

`paperless_ngx.list_storage_paths`

### Get Storage Path

按 id 获取单个存储路径，包含文档数量。需要对该存储路径的 view\_storagepath 权限。

`paperless_ngx.get_storage_path`

### Create Storage Path

根据文件名模板创建存储路径，可选设置匹配规则。建议先用 test\_storage\_path 预览模板的渲染结果。所有者默认为连接用户。需要 add\_storagepath 权限。

`paperless_ngx.create_storage_path`

### Update Storage Path

部分更新存储路径；只修改提供的字段。修改 path 会调度后台任务，重命名并移动所有使用该存储路径的文档。需要对该存储路径的 change\_storagepath 权限；修改 owner 或 set\_permissions 还要求是所有者或超级用户。

`paperless_ngx.update_storage_path`

### Delete Storage Path

删除存储路径。使用过它的文档会回退到默认文件名格式并在后台移动。需要对该存储路径的 delete\_storagepath 权限。

`paperless_ngx.delete_storage_path`

### Test Storage Path

用一个已有文档渲染存储路径模板，预览生成的文件路径(含文档的文件扩展名)，不保存任何内容。只要求该文档对连接用户可见；无效模板会返回校验错误。

`paperless_ngx.test_storage_path`

### List Custom Fields

列出自定义字段定义，以及使用每个字段的文档数量。支持 id 与不区分大小写的名称过滤、排序与分页。自定义字段没有对象级权限；需要 view\_customfield 权限。

`paperless_ngx.list_custom_fields`

### Get Custom Field

按 id 获取单个自定义字段定义，包含其下拉选项或默认货币，以及使用它的文档数量。需要 view\_customfield 权限。

`paperless_ngx.get_custom_field`

### Create Custom Field

创建自定义字段定义。select 类型字段需要在 extra\_data.select\_options 中提供至少一个带标签的选项(id 会自动生成)，monetary 类型字段可设置 extra\_data.default\_currency。需要 add\_customfield 权限。

`paperless_ngx.create_custom_field`

### Update Custom Field

部分更新自定义字段定义；只修改提供的字段。对 select 类型字段，每次更新都必须完整发送 extra\_data.select\_options，即使只是重命名字段，并保留已有选项的 id 以免文档上的取值丢失。修改已有取值字段的 data\_type 不被 Paperless-ngx 界面支持，可能导致已存值无法读取。需要 change\_customfield 权限。

`paperless_ngx.update_custom_field`

### Delete Custom Field

删除自定义字段定义，连同文档上为它存储的所有取值。需要 delete\_customfield 权限。

`paperless_ngx.delete_custom_field`

### List Saved Views

列出连接用户可见的已保存文档视图，包含过滤规则与显示设置。仅支持按 name 排序与分页，没有字段过滤。需要 view\_savedview 权限。

`paperless_ngx.list_saved_views`

### Get Saved View

按 id 获取单个已保存视图，包含过滤规则与显示设置。需要对该视图的 view\_savedview 权限。

`paperless_ngx.get_saved_view`

### Create Saved View

根据名称与过滤规则列表创建已保存文档视图，可选设置排序、每页数量、显示模式与显示字段。仪表盘与侧边栏可见性属于通过 update\_ui\_settings 保存的用户偏好，不是视图字段。所有者默认为连接用户。需要 add\_savedview 权限。

`paperless_ngx.create_saved_view`

### Update Saved View

部分更新已保存视图；只修改提供的字段，提供 filter\_rules 时会替换整个规则列表。需要对该视图的 change\_savedview 权限；修改 owner 或 set\_permissions 还要求是所有者或超级用户。

`paperless_ngx.update_saved_view`

### Delete Saved View

删除已保存视图及其过滤规则。需要对该视图的 delete\_savedview 权限。

`paperless_ngx.delete_saved_view`

### Bulk Edit Objects

批量设置多个标签、联系人、文档类型或存储路径的所有者与权限，或批量删除它们。非超级用户需要对应的 change 或 delete 模型权限，且必须拥有每个目标对象(或对象无所有者)，否则 Paperless-ngx 返回 403 Insufficient permissions。删除立即生效且不可恢复。

`paperless_ngx.bulk_edit_objects`

### List Workflows

列出工作流及其嵌套的触发器与动作, 按 order 排序。该端点只支持分页, 没有过滤或排序选项。需要 view\_workflow 权限。

`paperless_ngx.list_workflows`

### Get Workflow

按 id 读取单个工作流, 包含其触发器与动作。需要 view\_workflow 权限。

`paperless_ngx.get_workflow`

### Create Workflow

一次调用创建工作流及其触发器与动作。嵌套的触发器与动作不带 id 时新建, 带 id 时原地更新对应的已有触发器或动作。远程 OCR 动作需要消费开始触发器, 应用 AI 建议动作需要其他类型的触发器。需要 add\_workflow 权限。

`paperless_ngx.create_workflow`

### Update Workflow

部分更新工作流。只发送提供的字段。提供 triggers 或 actions 时会整体替换: 带 id 的条目原地更新, 不带 id 的条目新建, 未列出的触发器或动作会被解除挂载并删除。需要 change\_workflow 权限。

`paperless_ngx.update_workflow`

### Delete Workflow

删除工作流。它的触发器与动作会在下一次任意工作流更新时被清理。需要 delete\_workflow 权限。

`paperless_ngx.delete_workflow`

### List Workflow Triggers

列出所有工作流的触发器。该端点只支持分页, 没有过滤或排序选项。需要 view\_workflowtrigger 权限。

`paperless_ngx.list_workflow_triggers`

### Get Workflow Trigger

按 id 读取单个工作流触发器。需要 view\_workflowtrigger 权限。

`paperless_ngx.get_workflow_trigger`

### Create Workflow Trigger

创建一个独立的工作流触发器。消费开始 (type 1) 触发器需要 filter\_filename, filter\_path 或 filter\_mailrule。未挂载到任何工作流的对象会在下一次任意工作流更新时被自动删除, 请尽快通过 update\_workflow 或 create\_workflow 挂载。需要 add\_workflowtrigger 权限。

`paperless_ngx.create_workflow_trigger`

### Update Workflow Trigger

部分更新工作流触发器。只发送提供的字段。当触发器是 (或将变为) 消费开始触发器时, Paperless-ngx 要求同一请求中带上 filter\_filename, filter\_path 或 filter\_mailrule, 即使它们没有变化。需要 change\_workflowtrigger 权限。

`paperless_ngx.update_workflow_trigger`

### Delete Workflow Trigger

删除工作流触发器, 并从所有使用它的工作流中解除挂载。需要 delete\_workflowtrigger 权限。

`paperless_ngx.delete_workflow_trigger`

### List Workflow Actions

列出所有工作流的动作。该端点只支持分页, 没有过滤或排序选项。需要 view\_workflowaction 权限。

`paperless_ngx.list_workflow_actions`

### Get Workflow Action

按 id 读取单个工作流动作。需要 view\_workflowaction 权限。

`paperless_ngx.get_workflow_action`

### Create Workflow Action

创建一个独立的工作流动作。邮件 (3), webhook (4), 移除密码 (5) 与应用 AI 建议 (8) 类型分别要求提供 email, webhook, passwords 或 ai\_suggestion\_fields。未挂载到任何工作流的对象会在下一次任意工作流更新时被自动删除, 请尽快通过 update\_workflow 或 create\_workflow 挂载。需要 add\_workflowaction 权限。

`paperless_ngx.create_workflow_action`

### Update Workflow Action

部分更新工作流动作。只发送提供的字段; 嵌套的 email 与 webhook 对象会替换已存储的设置。需要 change\_workflowaction 权限。

`paperless_ngx.update_workflow_action`

### Delete Workflow Action

删除工作流动作, 并从所有使用它的工作流中解除挂载。需要 delete\_workflowaction 权限。

`paperless_ngx.delete_workflow_action`

### List Share Links

列出当前连接用户可见的分享链接 (自己的链接加上共享给自己的链接), 可按创建与过期时间过滤。每条结果都带有公开下载地址 share\_url。需要 view\_sharelink 权限。

`paperless_ngx.list_share_links`

### Get Share Link

按 id 读取单个分享链接, 包含公开的 share\_url。需要 view\_sharelink 权限并且能访问该链接。

`paperless_ngx.get_share_link`

### Create Share Link

为单个文档创建公开分享链接。链接归当前连接用户所有, 该用户必须有权查看此文档。响应包含 slug 与推导出的 share\_url; 分享链接创建后不能修改, 要更改过期时间或文件版本请删除后重建。需要 add\_sharelink 权限。

`paperless_ngx.create_share_link`

### Delete Share Link

删除分享链接, 公开 URL 随即失效。需要 delete\_sharelink 权限并且是该链接的所有者 (或超级用户)。

`paperless_ngx.delete_share_link`

### List Share Link Bundles

列出当前连接用户可见的分享链接打包, 可按状态, 包含的文档以及创建或过期时间过滤。每条结果都带有 share\_url 与构建状态。需要 view\_sharelinkbundle 权限。

`paperless_ngx.list_share_link_bundles`

### Get Share Link Bundle

按 id 读取单个分享链接打包, 包含构建状态, 大小与公开的 share\_url。在 create\_share\_link\_bundle 或 rebuild\_share\_link\_bundle 之后用它轮询打包, 直到 status 为 ready。需要 view\_sharelinkbundle 权限。

`paperless_ngx.get_share_link_bundle`

### Create Share Link Bundle

创建分享链接打包: 一个公开链接, 提供多个文档打成的 zip 压缩包。当前连接用户必须有权查看每个文档, 重复的 id 会被拒绝。zip 由后台任务构建, 因此返回的打包状态为 pending; 请轮询 get\_share\_link\_bundle 直到 ready。打包创建后不能修改。需要 add\_sharelinkbundle 权限。

`paperless_ngx.create_share_link_bundle`

### Rebuild Share Link Bundle

丢弃分享链接打包已构建的 zip 压缩包并重新排队构建, 例如在其文档发生变化之后。返回的打包状态为 pending; 若构建仍在进行中, Paperless-ngx 会以 400 拒绝请求。需要 change\_sharelinkbundle 权限。

`paperless_ngx.rebuild_share_link_bundle`

### Delete Share Link Bundle

删除分享链接打包及其 zip 压缩包, 公开 URL 随即失效。需要 delete\_sharelinkbundle 权限并且是该打包的所有者 (或超级用户)。

`paperless_ngx.delete_share_link_bundle`

### List Tasks

分页并按条件列出 Paperless-ngx 后台任务(文档消费、分类器训练、完整性检查、邮件拉取及其他作业)。非 staff 用户只能看到自己的任务与无主的系统任务；staff 用户能看到所有任务。需要 view\_paperlesstask 权限。

`paperless_ngx.list_tasks`

### Get Task

按 Celery 任务 UUID 获取一个后台任务，该 UUID 由 upload\_document、update\_document\_version、run\_task 及其他异步 action 返回。轮询直到 status 为 success、failure 或 revoked；消费任务成功时在 result\_data.document\_id 中给出新文档 id (同时也是 related\_document\_ids 的第一项)，被判定为重复时在 result\_data.duplicate\_of 中给出已有文档。

`paperless_ngx.get_task`

### Get Task By Id

按数字行 id (list\_tasks 输出中的 id 字段) 获取一个后台任务，区别于 get\_task 使用的 Celery UUID。

`paperless_ngx.get_task_by_id`

### Acknowledge Tasks

将后台任务标记为已确认(从任务列表中忽略)。通过 tasks 传入数字任务行 id，或将 all 设为 true 以确认当前可见的全部未确认任务；两者必须且只能提供一个。需要 change\_paperlesstask 权限。

`paperless_ngx.acknowledge_tasks`

### Get Task Summary

获取最近 N 天内按任务类型聚合的后台任务统计：各结果的数量、平均运行与等待时间，以及最近一次运行、成功与失败的时间戳。超级用户、staff 用户以及拥有 view\_system\_monitoring 权限的用户看到全部任务；其他用户只看到自己的任务与无主的系统任务。

`paperless_ngx.get_task_summary`

### Get Task Status Counts

获取可见后台任务的总数以及各状态分组的数量：needs\_attention (failure 或 revoked)、in\_progress (pending 或 started) 与 completed (success)。接受与 list\_tasks 相同的过滤条件，但不含 status 与 is\_complete，因为计数本身已按此细分。

`paperless_ngx.get_task_status_counts`

### List Active Tasks

列出当前处于 pending 或 started 状态的后台任务，按最新在前排列，最多 50 条且不分页。非 staff 用户只能看到自己的任务与无主的系统任务。

`paperless_ngx.list_active_tasks`

### Run Task

在后台手动启动一项维护任务：train\_classifier 重新训练自动匹配分类器，sanity\_check 检查文档文件与数据库，llm\_index 更新 AI 索引。只有这三种任务类型可以派发，且只有超级用户可以调用。返回可用 get\_task 轮询的 Celery 任务 UUID。

`paperless_ngx.run_task`

### List Users

分页并按用户名过滤列出 Paperless-ngx 用户账户，按用户名排序。内置的 consumer 与 AnonymousUser 账户永远不会列出。需要 view\_user 权限。

`paperless_ngx.list_users`

### Get User

按 id 获取一个 Paperless-ngx 用户账户，包括所属用户组、直接与继承的权限代号，以及是否启用了 MFA。需要 view\_user 权限。

`paperless_ngx.get_user`

### Create User

创建一个 Paperless-ngx 用户账户。只有 username 是必填的；未设置密码的账户在设置密码之前无法用密码登录。授予 is\_staff 或 is\_superuser 要求调用方是超级用户。需要 add\_user 权限。

`paperless_ngx.create_user`

### Update User

部分更新一个 Paperless-ngx 用户账户；只有提供的字段会更改，groups 与 user\_permissions 会替换整个列表。更改 is\_staff 或 is\_superuser，或对超级用户做任何修改，都要求调用方是超级用户。需要 change\_user 权限。

`paperless_ngx.update_user`

### Delete User

永久删除一个 Paperless-ngx 用户账户。该用户拥有的对象会变为无主。删除超级用户要求调用方是超级用户。需要 delete\_user 权限。

`paperless_ngx.delete_user`

### Deactivate User Totp

移除用户的 TOTP 多因素认证器，使其只能用密码登录。调用方可以停用自己的 TOTP；停用其他用户的 TOTP 要求调用方是超级用户。用户没有 TOTP 认证器时返回 404。

`paperless_ngx.deactivate_user_totp`

### List Groups

分页并按名称过滤列出 Paperless-ngx 用户组，按名称排序。需要 view\_group 权限。

`paperless_ngx.list_groups`

### Get Group

按 id 获取一个 Paperless-ngx 用户组及其权限代号。需要 view\_group 权限。

`paperless_ngx.get_group`

### Create Group

创建一个 Paperless-ngx 用户组。Paperless-ngx 在创建时要求提供 permissions 列表，因此省略时会以空列表发送。需要 add\_group 权限。

`paperless_ngx.create_group`

### Update Group

部分更新一个 Paperless-ngx 用户组；只有提供的字段会更改，permissions 会替换整个列表。需要 change\_group 权限。

`paperless_ngx.update_group`

### Delete Group

永久删除一个 Paperless-ngx 用户组。成员会失去从该组继承的权限。需要 delete\_group 权限。

`paperless_ngx.delete_group`

### Get Profile

获取 API 令牌所属用户的个人资料：姓名、邮箱、已关联的社交账号、是否设置了密码与 MFA，以及 API 令牌本身(日志中脱敏)。

`paperless_ngx.get_profile`

### Update Profile

更新 API 令牌所属用户的姓名、邮箱或密码。只有提供的字段会更改；全部由星号组成的密码会被忽略。返回更新后的个人资料，包含 API 令牌(日志中脱敏)。

`paperless_ngx.update_profile`

### List Mail Accounts

列出 Paperless-ngx 用于抓取文档的邮箱账号，按 id 排序。只能看到已连接用户拥有的、无拥有者的或已共享给该用户的账号。密码以星号占位符返回。该端点除分页外不支持排序或字段过滤。

`paperless_ngx.list_mail_accounts`

### Get Mail Account

按 id 获取一个邮箱账号。只能看到已连接用户拥有的、无拥有者的或已共享给该用户的账号。密码以星号占位符返回。

`paperless_ngx.get_mail_account`

### Create Mail Account

创建一个 Paperless-ngx 可以从中抓取文档的 IMAP 邮箱账号。需要 add\_mailaccount 权限。账号只有在被邮件规则引用后才会生效；建议先用 test\_mail\_account 验证凭据。

`paperless_ngx.create_mail_account`

### Update Mail Account

部分更新邮箱账号。只发送提供的字段；传 null 可清空可为空的字段。仅由星号组成的密码 (即读取时返回的占位符) 会被忽略，已存储的密码保持不变。需要对该账号的修改权限。

`paperless_ngx.update_mail_account`

### Delete Mail Account

删除邮箱账号，连同属于它的所有邮件规则和已处理邮件记录。需要对该账号的删除权限。

`paperless_ngx.delete_mail_account`

### Test Mail Account

在不保存任何内容的情况下测试 Paperless-ngx 能否用给定的 IMAP 设置登录邮箱。传入现有账号的 id 并使用星号密码占位符，可测试已存储的凭据 (包括 OAuth 令牌，过期时会自动刷新)；这需要对该账号的修改权限，而测试新设置需要 add\_mailaccount 权限。登录失败会报状态 400 的错误，消息为 Unable to connect to server。

`paperless_ngx.test_mail_account`

### Process Mail Account

立即排队抓取一个邮箱账号，而不等待定时邮件检查。Paperless-ngx 会启动 mail\_fetch 后台任务并返回 OK，但不返回任务 id；可查看任务列表 (task\_type 为 mail\_fetch) 或 list\_processed\_mail 了解结果。需要对该账号的查看权限。

`paperless_ngx.process_mail_account`

### List Mail Rules

列出邮件规则，按其 order 字段排序。只能看到已连接用户拥有的、无拥有者的或已共享给该用户的规则。该端点除分页外不支持排序或字段过滤。

`paperless_ngx.list_mail_rules`

### Get Mail Rule

按 id 获取一个邮件规则。只能看到已连接用户拥有的、无拥有者的或已共享给该用户的规则。

`paperless_ngx.get_mail_rule`

### Create Mail Rule

创建一条邮件规则，告诉 Paperless-ngx 要消费某个账号的哪些邮件以及如何归档生成的文档。需要 add\_mailrule 权限以及对所引用账号的修改权限。动作 2 (移动) 和 5 (打标签) 需要 action\_parameter。

`paperless_ngx.create_mail_rule`

### Update Mail Rule

部分更新邮件规则。只发送提供的字段；传 null 可清空可为空的字段。将 action 改为 2 (移动) 或 5 (打标签) 时，需在同一请求中发送 action\_parameter，因为 Paperless-ngx 会一起校验这两个字段。需要对该规则的修改权限。

`paperless_ngx.update_mail_rule`

### Delete Mail Rule

删除邮件规则，连同它的已处理邮件记录。需要对该规则的删除权限。

`paperless_ngx.delete_mail_rule`

### List Processed Mail

列出邮件规则已经处理过的邮件，默认按处理时间倒序，可按规则或状态过滤。只返回已连接用户拥有的、无拥有者的或已共享给该用户的记录。

`paperless_ngx.list_processed_mail`

### Get Processed Mail

按 id 获取一条已处理邮件记录。只能看到已连接用户拥有的、无拥有者的或已共享给该用户的记录。

`paperless_ngx.get_processed_mail`

### Bulk Delete Processed Mail

一次删除多条已处理邮件记录，使对应邮件在下次运行时可以重新抓取。Paperless-ngx 会先检查每条记录的删除权限，只要有任何一条无权限就以状态 403 拒绝整个请求；不存在的 id 会被静默跳过。

`paperless_ngx.bulk_delete_processed_mail`

### Get Statistics

获取当前用户可见的文档统计：文档总数、收件箱数量、按 MIME 类型的分布、字符数、各类对象数量以及当前最大归档序列号。拥有全局统计权限的用户看到的是实例级数字，其他用户只统计自己有权访问的文档。

`paperless_ngx.get_statistics`

### Get System Status

获取 Paperless-ngx 系统状态：服务器版本、安装类型、存储用量、数据库与迁移状态、Redis 与 Celery 健康度、搜索索引、分类器、完整性检查和 LLM 索引状态，以及最近 30 天的任务汇总。需要系统状态权限 (超级用户或拥有 view\_paperlesstask 权限的用户)。

`paperless_ngx.get_system_status`

### Get Remote Version

查询 GitHub 上最新发布的 Paperless-ngx 版本，并判断它是否比当前实例更新。查询由实例自身完成并缓存 15 分钟；查询失败时返回版本 0.0.0 且 update\_available 为 false。

`paperless_ngx.get_remote_version`

### Get Ui Settings

获取 API 令牌所属用户的界面设置、有效权限和基本身份 (id、用户名、staff 与超级用户标记、用户组)。settings 对象还会附带服务器信息，例如 Paperless-ngx 版本、应用标题、回收站延迟、审计日志、邮件与 AI 是否可用。

`paperless_ngx.get_ui_settings`

### Update Ui Settings

用给定的 settings 对象替换当前用户已保存的界面设置。Paperless-ngx 会整体覆盖设置文档，因此请以 get\_ui\_settings 返回的完整对象为基础修改后再发送；update\_checking.backend\_setting 永远不会被保存。

`paperless_ngx.update_ui_settings`

### Get Application Config

获取实例级应用配置 (OCR、归档文件生成、条码、远程 OCR 与 AI 设置、应用标题和 logo)。值为 null 的字段会回退到对应的环境变量。需要 view\_applicationconfiguration 权限。

`paperless_ngx.get_application_config`

### Update Application Config

部分更新实例级应用配置。只有 values 中给出的字段会被修改；传 null 可把字段重置为环境默认值。修改 AI 嵌入设置会让 Paperless-ngx 在后台重建 LLM 索引。需要 change\_applicationconfiguration 权限。

`paperless_ngx.update_application_config`

### List Logs

列出 Paperless-ngx 服务器上存在的日志文件 (paperless、mail 和 celery，仅列出存在的文件)。需要管理员 (staff) 权限。

`paperless_ngx.list_logs`

### Get Log

读取一个 Paperless-ngx 日志文件的内容，可以只取最后 N 行。需要管理员 (staff) 权限。

`paperless_ngx.get_log`

### Global Search

按名称或标题在文档、保存的视图、标签、联系人、文档类型、存储路径、用户、用户组、邮件规则、邮件账户、工作流和自定义字段中全局搜索，每种对象类型最多返回 3 条匹配。文档默认通过全文索引匹配；db\_only 为 true 时只比较标题。

`paperless_ngx.global_search`

### Autocomplete Search

根据全文索引为不完整的搜索词提供补全候选，按包含该候选词的用户文档数量排序。

`paperless_ngx.autocomplete_search`

没有符合搜索条件的工具。

## 将 Paperless-ngx 接入 Open Flow

[连接 Paperless-ngx](https://console.openflow.run/connections/paperless_ngx)

每月 20,000 次免费应用调用（付费服务另计）
