Paperless-ngx REST API 完全指南：从认证到高级搜索

Paperless-ngx REST API 完全指南：从认证到高级搜索

paperless-ngx A community-supported supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ngx

前言

Paperless-ngx 作为一款优秀的文档管理系统，其 REST API 提供了强大的程序化操作能力。本文将全面解析 Paperless-ngx 的 API 功能，帮助开发者高效集成和使用。

API 基础

Paperless-ngx 提供了完整的 RESTful API 接口，可通过 /api/schema/view/ 访问可浏览的 API 界面。API 采用标准的 REST 设计风格，支持 JSON 格式的数据交互。

认证机制

Paperless-ngx 提供四种认证方式，满足不同场景需求：

1. Basic 认证

最基础的 HTTP 认证方式，适合简单的自动化脚本：

Authorization: Basic <base64编码的用户名:密码>

2. Session 认证

浏览器登录后自动获得 API 访问权限，适合前后端一体化应用。

3. Token 认证（推荐）

通过用户界面生成或通过 /api/token/ 端点获取：

Authorization: Token <你的API令牌>

优势：无需保存密码，可随时撤销，安全性更高。

4. Remote User 认证

适用于企业级 SSO 集成，需在配置中启用。

文档搜索功能

Paperless-ngx 提供强大的全文搜索能力：

基本搜索

GET /api/documents/?query=搜索关键词

支持高级搜索语法，如布尔操作符、引号精确匹配等。

相似文档搜索

GET /api/documents/?more_like_id=1234

查找与指定ID文档内容相似的其他文档。

搜索结果解析

返回结果包含丰富的元数据：

"__search_hit__": {
    "score": 0.343,       // 匹配度评分
    "highlights": "...",  // 高亮显示的匹配片段
    "rank": 23            // 结果排名
}

自定义字段过滤

通过 custom_field_query 参数实现灵活筛选：

GET /api/documents/?custom_field_query=["字段名","操作符",值]

支持多种操作类型：

• 精确匹配："exact"
• 范围查询："range" (适用于日期、数字)
• 包含检查："contains" (适用于文档链接)
• 空值检查："isnull"

自动补全功能

GET /api/search/autocomplete/?term=部分词&limit=5

基于 TF-IDF 算法返回最相关的补全建议。

文档上传接口

POST /api/documents/post_document/

使用 multipart/form-data 格式上传，支持以下元数据：

• title：文档标题
• created：创建时间
• correspondent：联系人ID
• tags：标签ID列表
• custom_fields：自定义字段ID数组

上传后返回消费任务UUID，可通过任务接口查询处理状态。

权限管理

Paperless-ngx 提供细粒度的权限控制：

{
    "owner": 用户ID,
    "set_permissions": {
        "view": {"users": [], "groups": []},
        "change": {"users": [], "groups": []}
    }
}

可通过 full_perms=true 参数获取完整权限信息。

批量操作

文档批量编辑

POST /api/documents/bulk_edit/

支持的操作包括：

• 设置元数据（联系人、类型等）
• 标签管理（添加/删除）
• 文档合并/拆分
• 页面旋转/删除
• 权限批量设置

对象批量操作

POST /api/bulk_edit_objects/

支持标签、联系人等对象的批量权限设置或删除。

API 版本控制

Paperless-ngx 采用严格的 API 版本管理：

Accept: application/json; version=6

版本策略：

• 未指定版本时默认使用 v1
• 新版本发布后，旧版本至少维护一年
• 通过响应头 X-Api-Version 和 X-Version 获取服务器信息

最佳实践建议

1. 生产环境推荐使用 Token 认证
2. 批量操作时注意检查任务状态
3. 上传大文件时考虑分块传输
4. 定期检查 API 版本兼容性
5. 使用搜索高亮功能提升用户体验

通过合理利用 Paperless-ngx 的 API，开发者可以构建强大的文档管理自动化流程，实现与企业现有系统的无缝集成。

paperless-ngx A community-supported supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ngx