名称： paperless-ngx
描述： 通过 REST API 与 Paperless-ngx 文档管理系统交互。当用户需要在其 Paperless-ngx 实例中搜索、上传、下载、整理文档，或管理标签、通信者、文档类型时使用。

Paperless-ngx 技能

通过 HTTP 请求调用 Paperless-ngx 的 REST API 来管理文档。

配置

需要设置以下环境变量：
- PAPERLESS_URL: 基础 URL (例如：https://paperless.example.com)
- PAPERLESS_TOKEN: 来自 Paperless-ngx 设置的 API 令牌

认证

在所有请求中包含令牌：

Authorization: Token $PAPERLESS_TOKEN

核心操作

搜索文档

curl -s "$PAPERLESS_URL/api/documents/?query=invoice" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

可用筛选选项：correspondent__id, document_type__id, tags__id__in, created__date__gte, created__date__lte, added__date__gte。

获取文档详情

curl -s "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

下载文档

# 原始文件
curl -s "$PAPERLESS_URL/api/documents/{id}/download/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf

# 归档（已OCR）版本
curl -s "$PAPERLESS_URL/api/documents/{id}/download/?original=false" \
  -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf

上传文档

curl -s "$PAPERLESS_URL/api/documents/post_document/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -F "document=@/path/to/file.pdf" \
  -F "title=Document Title" \
  -F "correspondent=1" \
  -F "document_type=2" \
  -F "tags=3" \
  -F "tags=4"

可选字段：title, created, correspondent, document_type, storage_path, tags (可重复), archive_serial_number, custom_fields。

更新文档元数据

curl -s -X PATCH "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "correspondent": 1, "tags": [1, 2]}'

删除文档

curl -s -X DELETE "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

组织管理端点

标签

# 列出标签
curl -s "$PAPERLESS_URL/api/tags/" -H "Authorization: Token $PAPERLESS_TOKEN"

# 创建标签
curl -s -X POST "$PAPERLESS_URL/api/tags/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Important", "color": "#ff0000"}'

通信者

# 列出通信者
curl -s "$PAPERLESS_URL/api/correspondents/" -H "Authorization: Token $PAPERLESS_TOKEN"

# 创建通信者
curl -s -X POST "$PAPERLESS_URL/api/correspondents/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ACME Corp"}'

文档类型

# 列出文档类型
curl -s "$PAPERLESS_URL/api/document_types/" -H "Authorization: Token $PAPERLESS_TOKEN"

# 创建文档类型
curl -s -X POST "$PAPERLESS_URL/api/document_types/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Invoice"}'

批量操作

curl -s -X POST "$PAPERLESS_URL/api/documents/bulk_edit/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [1, 2, 3],
    "method": "add_tag",
    "parameters": {"tag": 5}
  }'

可用方法：set_correspondent, set_document_type, add_tag, remove_tag, delete, reprocess。

任务状态

上传后，可检查任务状态：

curl -s "$PAPERLESS_URL/api/tasks/?task_id={uuid}" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

响应处理

• 列表端点返回 {"count": N, "results": [...]} 格式，支持分页
• 单个对象直接返回该对象
• 使用 ?page=2 进行分页
• 添加 ?ordering=-created 进行排序（前缀 - 表示降序）