跳转到主要内容

​
订阅 CRUD

订阅 API 使用 camelCase 字段。服务端管理字段会在响应中返回，但不能出现在写请求里。

​
操作语义

操作适用场景风险AI 是否需要确认
GET /api/v1/subscriptions查询、搜索、汇总、分析或识别订阅低不需要
GET /api/v1/subscriptions/{id}已知 UUID，读取单条订阅低不需要
POST /api/v1/subscriptions记录一个新的订阅中需要
PATCH /api/v1/subscriptions/{id}修改可写字段，包括 status（取消/暂停/恢复）中–高需要
DELETE /api/v1/subscriptions/{id}永久删除本地追踪记录（如需保留历史请改用取消）高需要
AI 集成在更新或删除前，应该先查询并确认目标订阅；除非用户已经提供了准确的订阅 UUID。写操作需要带 write 权限的 API Key；只读 Key 会收到 403 insufficient_scope。

​
分页

GET /api/v1/subscriptions 按创建时间倒序返回，支持两个可选查询参数：
参数默认值规则
limit50每页数量，范围 1 到 100
offset0从开头跳过的记录数
响应中包含 pagination 对象。当 hasMore 为 true 时，用 offset + limit 获取下一页。 
{
  "data": [ /* ... */ ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false },
  "requestId": "request-..."
}

curl -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  "https://your-site.example/api/v1/subscriptions?limit=50&offset=50"
超出范围的取值会返回 400 invalid_pagination。

​
过滤与排序

GET /api/v1/subscriptions 在分页之外，还支持以下可选过滤器和排序：
参数规则
statusactive、paused、cancelled 之一
category分类精确匹配，如 Streaming
periodmonthly、yearly、custom 之一
q对订阅名称不区分大小写搜索
expiringBeforeYYYY-MM-DD；返回 nextPaymentDate 在该日期当天或之前的记录
sortcreatedAt、-createdAt、nextPaymentDate、-nextPaymentDate、amount、-amount、name、-name 之一（默认 -createdAt，前缀 - 表示降序）
将 status=active 与 expiringBefore 组合即可回答「哪些即将续费」。非法取值返回 400 invalid_query，并带 field 与 suggestedFix。 
curl -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  "https://your-site.example/api/v1/subscriptions?status=active&expiringBefore=2026-07-01&sort=nextPaymentDate"
响应会回显实际生效的查询，便于 Agent 确认结果来源： 
{
  "data": [ /* ... */ ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false },
  "query": { "sort": "nextPaymentDate", "filters": { "status": "active", "expiringBefore": "2026-07-01" } },
  "requestId": "request-..."
}

​
订阅对象

{
  "id": "33333333-3333-4333-8333-333333333333",
  "name": "Netflix",
  "category": "Streaming",
  "amount": 15.99,
  "currency": "USD",
  "period": "monthly",
  "lastPaymentDate": "2026-06-01",
  "nextPaymentDate": "2026-07-01",
  "notificationEnabled": true,
  "status": "active",
  "createdAt": "2026-06-16T00:00:00.000Z",
  "updatedAt": "2026-06-16T00:00:00.000Z"
}

​
可写字段

{
  "name": "Netflix",
  "category": "Streaming",
  "amount": 15.99,
  "currency": "USD",
  "period": "monthly",
  "lastPaymentDate": "2026-06-01",
  "customDate": null,
  "notificationEnabled": true,
  "status": "active"
}
服务端管理这些字段：
  • id
  • nextPaymentDate
  • createdAt
  • updatedAt
不要在 POST 或 PATCH 请求里发送服务端管理字段。

​
字段规则

字段规则
name必填，1-120 个字符
category必填，1-80 个字符
amount必填数字，范围 0 到 999999.99，最多 2 位小数
currency必填，可选 CNY、USD、EUR、JPY、GBP、AUD、CAD、CHF、HKD、SGD
period必填，可选 monthly、yearly、custom
lastPaymentDate必填，格式为 YYYY-MM-DD
customDate仅当 period 为 custom 时必填；表示间隔天数，需为正整数字符串
notificationEnabled可选布尔值，默认 true
status可选，active、paused、cancelled 之一，默认 active
nextPaymentDate 由服务端根据 lastPaymentDate、period 和 customDate 计算。PATCH 时，只有这三个字段之一发生变化才会重新计算；修改其它字段不会改动已存的 nextPaymentDate。PATCH 只校验你实际传入的字段，因此更新某个字段不会因为其它历史数据不合规而失败。

​
生命周期：取消、暂停、恢复 vs 删除

订阅有一个 status：active（计费中）、paused（暂停）、cancelled（已取消、停止计费但保留历史）。修改状态是软操作——记录及其审计历史都会保留，可随时恢复为 active。而 DELETE 是永久删除，会一并移除该记录的审计历史。 当用户表示不再使用某服务但将来可能回来时，优先改状态而不是删除： 
# 取消（保留历史）
curl -X PATCH \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"cancelled"}' \
  https://your-site.example/api/v1/subscriptions/33333333-3333-4333-8333-333333333333

# 暂停，之后再恢复
curl -X PATCH ... -d '{"status":"paused"}' .../{id}
curl -X PATCH ... -d '{"status":"active"}'  .../{id}
在分析端点中，只有 active 订阅计入活跃支出。只有当用户希望永久删除记录时才用 DELETE。

​
自然语言示例

​
新增订阅

用户意图： 
帮我记录 ChatGPT Plus，每月 20 美元，上次付款是 2026-06-17。
API 调用： 
curl -X POST \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ChatGPT Plus","category":"AI","amount":20,"currency":"USD","period":"monthly","lastPaymentDate":"2026-06-17","notificationEnabled":true}' \
  https://your-site.example/api/v1/subscriptions

​
修改计费周期

用户意图： 
把 Netflix 改成年付。
Agent 流程：
  1. 调用 GET /api/v1/subscriptions 找到 Netflix 记录。
  2. 向用户确认具体记录和修改内容。
  3. 调用 PATCH /api/v1/subscriptions/{id}。
curl -X PATCH \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"yearly"}' \
  https://your-site.example/api/v1/subscriptions/33333333-3333-4333-8333-333333333333

​
删除重复记录

用户意图： 
删除重复的 Netflix 订阅。
Agent 流程：
  1. 调用 GET /api/v1/subscriptions 找到重复候选。
  2. 向用户确认订阅名称和 id。
  3. 调用 DELETE /api/v1/subscriptions/{id}。
curl -X DELETE \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  https://your-site.example/api/v1/subscriptions/33333333-3333-4333-8333-333333333333

​
自定义计费周期

如果不是月付或年付，把 period 设为 custom，并把 customDate 设为表示天数的正整数字符串。 
{
  "name": "Domain renewal",
  "category": "Infrastructure",
  "amount": 12,
  "currency": "USD",
  "period": "custom",
  "lastPaymentDate": "2026-06-01",
  "customDate": "45"
}
从 custom 改回 monthly 或 yearly 时，省略 customDate。服务端会清理旧的自定义计费数据。

​
AI tool schema

使用 ai-tools.json 获取 tool/function 定义、风险等级和确认提示。