介绍
# Paperless-ngx Skill
通过 HTTP 请求使用 Paperless-ngx 的 REST API 管理文档。
## 配置
需要环境变量： - `PAPERLESS_URL`：基础 URL（例如 `https://paperless.example.com`） - `PAPERLESS_TOKEN`：来自 Paperless-ngx 设置的 API 令牌
## 身份验证
在所有请求中包含令牌： ``` Authorization: Token $PAPERLESS_TOKEN ```
## 核心操作
### 搜索文档
```bash 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`。
### 获取文档详情
```bash curl -s "$PAPERLESS_URL/api/documents/{id}/" \ -H "Authorization: Token $PAPERLESS_TOKEN" ```
### 下载文档
```bash # Original file curl -s "$PAPERLESS_URL/api/documents/{id}/download/" \ -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf
# Archived (OCR'd) version curl -s "$PAPERLESS_URL/api/documents/{id}/download/?original=false" \ -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf ```
### 上传文档
```bash 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`。
### 更新文档元数据
```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 # List tags curl -s "$PAPERLESS_URL/api/tags/" -H "Authorization: Token $PAPERLESS_TOKEN"
# Create tag curl -s -X POST "$PAPERLESS_URL/api/tags/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Important", "color": "#ff0000"}' ```
### 通信对象
```bash # List correspondents curl -s "$PAPERLESS_URL/api/correspondents/" -H "Authorization: Token $PAPERLESS_TOKEN"
# Create correspondent curl -s -X POST "$PAPERLESS_URL/api/correspondents/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "ACME Corp"}' ```
### 文档类型
```bash # List document types curl -s "$PAPERLESS_URL/api/document_types/" -H "Authorization: Token $PAPERLESS_TOKEN"
# Create document type curl -s -X POST "$PAPERLESS_URL/api/document_types/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Invoice"}' ```
## 批量操作
```bash 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`。
## 任务状态
上传后，检查任务状态： ```bash curl -s "$PAPERLESS_URL/api/tasks/?task_id={uuid}" \ -H "Authorization: Token $PAPERLESS_TOKEN" ```
## 响应处理
- 列表端点返回包含分页信息的 `{"count": N, "results": [...]}` - 单个对象直接返回对象本身 - 使用 `?page=2` 进行分页 - 添加 `?ordering=-created` 进行排序（前缀 `-` 表示降序）