Paperless-ngx 技能

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

配置

需要环境变量：

• - PAPERLESSURL：基础URL（例如 https://paperless.example.com）
• PAPERLESSTOKEN：来自Paperless-ngx设置的API令牌

身份验证

在所有请求中包含令牌：

Authorization: Token $PAPERLESS_TOKEN

核心操作

搜索文档

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

筛选选项：correspondentid、document_typeid、tagsidin、createddategte、createddatelte、addeddategte。

获取文档详情

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

下载文档

bash

原始文件

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

上传文档

bash
curl -s $PAPERLESSURL/api/documents/postdocument/ \
-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、documenttype、storagepath、tags（可重复）、archiveserialnumber、custom_fields。

更新文档元数据

bash
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]}

删除文档

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

组织管理端点

标签

bash

列出标签

curl -s $PAPERLESSURL/api/tags/ -H Authorization: Token $PAPERLESSTOKEN

创建标签

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

通信方

bash

列出通信方

curl -s $PAPERLESSURL/api/correspondents/ -H Authorization: Token $PAPERLESSTOKEN

创建通信方

curl -s -X POST $PAPERLESS_URL/api/correspondents/ \ -H Authorization: Token $PAPERLESS_TOKEN \ -H Content-Type: application/json \ -d {name: ACME Corp}

文档类型

bash

列出文档类型

curl -s $PAPERLESSURL/api/documenttypes/ -H Authorization: Token $PAPERLESS_TOKEN

创建文档类型

curl -s -X POST $PAPERLESSURL/api/documenttypes/ \ -H Authorization: Token $PAPERLESS_TOKEN \ -H Content-Type: application/json \ -d {name: Invoice}

批量操作

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

方法：setcorrespondent、setdocumenttype、addtag、remove_tag、delete、reprocess。

任务状态

上传后，检查任务状态：
bash
curl -s $PAPERLESSURL/api/tasks/?taskid={uuid} \
-H Authorization: Token $PAPERLESS_TOKEN

响应处理

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