{
  "openapi": "3.1.0",
  "info": {"title": "个人财务只读查询", "version": "1.0.0", "description": "只查询授权的已采集账本；不读取短信，不修改交易，不推断银行卡余额。配置时将服务器替换为实际 HTTPS 域名。"},
  "servers": [{"url": "https://replace-with-your-domain.invalid"}],
  "security": [{"financeReadKey": []}],
  "components": {
    "securitySchemes": {"financeReadKey": {"type": "http", "scheme": "bearer", "description": "在网站生成的独立 read 密钥，仅放在秘密设置"}},
    "parameters": {
      "start": {"name": "startDate", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "起始日期，默认本月首日；一次最多366天"},
      "end": {"name": "endDate", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "结束日期，默认今天，北京时间"}
    },
    "schemas": {
      "Summary": {"type": "object", "properties": {"currency": {"type": "string"}, "incomeCents": {"type": "integer"}, "expenseCents": {"type": "integer"}, "refundCents": {"type": "integer"}, "transferCents": {"type": "integer"}, "netExpenseCents": {"type": "integer"}, "cashFlowCents": {"type": "integer"}, "confirmedCount": {"type": "integer"}, "pendingCount": {"type": "integer"}, "categories": {"type": "object", "additionalProperties": {"type": "integer"}}, "notice": {"type": "string"}}},
      "Transaction": {"type": "object", "properties": {"id": {"type": "string"}, "transactionTime": {"type": "string", "format": "date-time"}, "amountCents": {"type": "integer"}, "direction": {"type": "string"}, "merchant": {"type": "string"}, "category": {"type": "string"}, "accountAlias": {"type": "string"}, "source": {"type": "string"}, "status": {"type": "string"}, "excluded": {"type": "boolean"}, "reviewReason": {"type": "string"}}},
      "Page": {"type": "object", "properties": {"transactions": {"type": "array", "items": {"$ref": "#/components/schemas/Transaction"}}, "total": {"type": "integer"}, "offset": {"type": "integer"}, "nextOffset": {"type": ["integer", "null"]}}}
    }
  },
  "paths": {
    "/api/finance-external/summary": {"get": {"operationId": "financeSummary", "summary": "按日期统计已确认消费、收入、退款、转账和分类", "parameters": [{"$ref": "#/components/parameters/start"}, {"$ref": "#/components/parameters/end"}], "responses": {"200": {"description": "金额单位为整数分，排除待核对记录，不代表银行余额", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Summary"}}}}, "401": {"description": "查询密钥无效"}}}},
    "/api/finance-external/transactions": {"get": {"operationId": "financeTransactions", "summary": "分页读取个人交易", "parameters": [{"$ref": "#/components/parameters/start"}, {"$ref": "#/components/parameters/end"}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["all", "confirmed", "provisional", "excluded"], "default": "all"}}, {"name": "direction", "in": "query", "schema": {"type": "string", "enum": ["income", "expense", "transfer", "refund"]}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 100000, "default": 0}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}], "responses": {"200": {"description": "只返回当前密钥所属账户数据", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "401": {"description": "查询密钥无效"}}}}
  }
}