API 实战

查询基础资料

先读取账本，再读取对应分类、账户和记账成员，使用返回的真实ID，不能直接复制示例数字。

curl "$ILITEBOOK_URL/api/v1/ledgers/1/categories" -H "Authorization: Bearer $ILITEBOOK_TOKEN"
curl "$ILITEBOOK_URL/api/v1/ledgers/1/accounts" -H "Authorization: Bearer $ILITEBOOK_TOKEN"
curl "$ILITEBOOK_URL/api/v1/ledgers/1/members" -H "Authorization: Bearer $ILITEBOOK_TOKEN"

创建支出

curl "$ILITEBOOK_URL/api/v1/ledgers/1/transactions" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN" -H "Content-Type: application/json" \
 -H "Idempotency-Key: expense-20261104-001" \
 -d '{"kind":"expense","amount":"12.34","date":"2026-11-04","category_id":"1","account_id":"1","member_id":"1","description":"午餐"}'

转账

curl "$ILITEBOOK_URL/api/v1/ledgers/1/transfers" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN" -H "Content-Type: application/json" \
 -H "Idempotency-Key: transfer-20261104-001" \
 -d '{"amount":"100.00","date":"2026-11-04","from_account_id":"1","to_account_id":"2","member_id":"1"}'

附件上传与下载

每个文件一个请求。上传返回附件ID，在创建流水时填写attachment_ids数组关联。下载需要同样的Bearer认证。

curl "$ILITEBOOK_URL/api/v1/ledgers/1/attachments" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN" -F "file=@receipt.pdf"
# 返回 {"data":{"id":"42","name":"receipt.pdf","size":1234}}
# 创建流水时增加 "attachment_ids":["42"]
curl "$ILITEBOOK_URL/api/v1/attachments/42/download" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN" -o receipt.pdf

查询流水和报表

curl "$ILITEBOOK_URL/api/v1/ledgers/1/transactions?kind=expense&month=2026-11&page=1" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN"
curl "$ILITEBOOK_URL/api/v1/ledgers/1/reports?year=2026&month=11" \
 -H "Authorization: Bearer $ILITEBOOK_TOKEN"

Python调用

示例只使用Python标准库，令牌从环境变量读取。HTTP错误应按状态处理，不要无限重复写入。

import json, os, urllib.request, urllib.error
base = os.environ["ILITEBOOK_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["ILITEBOOK_TOKEN"]}
request = urllib.request.Request(base + "/api/v1/ledgers", headers=headers)
try:
    with urllib.request.urlopen(request, timeout=15) as response:
        print(json.load(response))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode())

典型错误处理

401重新生成或检查令牌；403检查软件版本、令牌范围及账本授权；409先读取当前version，人工确认后再重试；写入遇到网络中断时复用同一Idempotency-Key。