远程记账 API

以 admin 身份登录 Billbook，打开设置 → 🔑 远程记账 API，点击「生成 token」。

明文 token 仅显示一次，请立即复制保存。数据库只保留 SHA-256 哈希，token 一旦遗失只能重新生成（会作废旧的）。

Token 格式：bb_<userId>_<secret>。所有 API 请求都用 Authorization: Bearer <token> 传入。

请求 body 是一个 JSON 对象，字段如下：

• title (string, 必填) — 交易名称
• amount (number, 必填) — 金额，必须为正数
• type (string, 可选，默认 expense) — expense / income / prepaid_expense / pending_income
• category (string, 可选) — 分类名称
• note (string, 可选) — 备注
• created_at (string, 可选) — ISO 8601 时间，省略则为当前

curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

返回 admin 账号设置的分类名称列表，顺序与仪表板下拉菜单一致。响应只有名称字符串，不含 id 或交易数据。

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

返回最近更新的标签前缀（#XXX 那种），默认 20 个,可用 ?limit= 调整（上限 100）。

若 tag_prefixes 表尚未建立，返回空数组而不是错误。

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

所有错误都是 JSON：{ "error": "消息" }。

• 401 — 缺少授权、token 格式错误、token 已撤销或不匹配
• 402 — 订阅已到期，需续订才能写入
• 405 — Method 不支持（例如对 /api/ingest 发 GET）
• 501 — 服务器未设置 SUPABASE_SERVICE_ROLE_KEY
• 500 — 其他内部错误

设计上只能写入调用者自己组织的交易，无法跨 org 或读取已有数据：

• user_id 永远是 token 所有者本人，无法伪造
• org_id 永远是所有者的 org，无法跨组织写入
• token 仅发给 admin 角色（manager / staff 返回 403）
• 响应不泄露其他数据行，只返回 { id, created_at }
• 撤销后立即失效，可在设置中随时轮换

创建一个「获取 URL 内容」动作，URL 设为 https://billbook.me/api/ingest，方法 POST，标头加 Authorization: Bearer bb_... 与 Content-Type: application/json，请求内容用 JSON：{"title":"咖啡","amount":120,"type":"expense"}。把 title 与 amount 替换为从快捷指令输入或询问的变量即可。