启用银行技能

通过启用银行API实现PSD2开放银行集成。
用于接入银行连接、获取余额/交易记录以及会话续期的多租户架构。

快速开始

1. 接入新租户

python scripts/onboard.py --bank Sparkasse Karlsruhe --country DE --mandant-id mueller

2. 获取余额 + 交易记录

python scripts/fetch.py --mandant-id mueller

3. 续期已过期的会话

python scripts/renew.py --mandant-id mueller

架构

┌─────────────┐ POST /auth ┌──────────────────────┐
│ onboard.py │ ──────────────────→ │ 启用银行API │
│ renew.py │ ←── redirect_url ── │ api.enablebanking.com│
└──────┬──────┘ └──────────┬───────────┘
│ │
│ 轮询 pending_callbacks/ │ 用户在银行门户
│ │ 进行授权
▼ ▼
┌──────────────────┐ GET /callback ┌─────────────┐
│ callback_server │ ←───────────────── │ 银行OAuth │
│ (端口 8443 HTTPS)│ │ 重定向 │
└──────────────────┘ └─────────────┘
│
│ 保存 code → pending_callbacks/{state}.json
│
▼
┌─────────────┐ POST /sessions ┌──────────────────────┐
│ onboard.py │ ──────────────────→ │ 启用银行API │
│ renew.py │ ←── session + accs ── │ │
└──────┬──────┘ └──────────────────────┘
│
│ 保存 mandanten/{id}.json
▼
┌─────────────┐ GET /accounts/{uid}/ ┌──────────────────────┐
│ fetch.py │ ──────────────────→ │ 启用银行API │
│ │ ←── balances + txns ──│ │
└──────┬──────┘ └──────────────────────┘
│
│ 保存 data/{id}/{date}.json
▼
stdout: JSON

目录结构

enable-banking/
├── SKILL.md # 本文件
├── config.json # 应用凭证（请勿提交）
├── .keys/ # 私钥 + 回调证书（请勿提交）
├── .gitignore
├── scripts/
│ ├── lib/
│ │ ├── init.py
│ │ └── auth.py # 共享JWT + API辅助函数 + 租户I/O
│ ├── callback_server.py # HTTPS回调守护进程
│ ├── onboard.py # 新租户连接
│ ├── fetch.py # 自主数据获取
│ └── renew.py # 会话续期
├── references/
│ └── api-reference.md
├── mandanten/ # 每个租户的JSON文件（请勿提交）
├── data/ # 获取的数据（请勿提交）
└── pending_callbacks/ # 临时回调代码（请勿提交）

脚本参考

scripts/lib/auth.py — 共享模块

函数	描述
loadconfig()	加载 config.json
generatejwt(config)

用于API认证的RS256 JWT | | api_request(method, endpoint, token, kwargs) | 带重试的认证API调用（429、超时） | | loadmandant(mandantid) | 加载 mandanten/{id}.json | | savemandant(mandantid, data) | 保存租户文件（chmod 600） | | list_mandanten() | 列出所有租户ID |

scripts/callback_server.py — HTTPS回调服务器

bash
python scripts/callback_server.py # 端口 8443 (HTTPS)
python scripts/callback_server.py --port 9443 # 自定义端口
python scripts/callback_server.py --no-ssl # 仅HTTP（开发环境）

• - 首次运行时在 .keys/ 中自动生成自签名证书
• GET /callback?code=...&state=... → 保存到 pendingcallbacks/{state}.json
• GET /health → 200 OK
• 作为后台进程运行：exec background:true command:python scripts/callbackserver.py

scripts/onboard.py — 租户接入

bash

连接新租户

python scripts/onboard.py --bank Sparkasse Karlsruhe --mandant-id mueller

使用手动授权码（无需回调服务器）

python scripts/onboard.py --bank Sparkasse Karlsruhe --mandant-id mueller --code ABC123

列出可用银行

python scripts/onboard.py --list-banks --country DE

企业账户

python scripts/onboard.py --bank DKB --mandant-id firma --psu-type business

流程（不使用 --code）：

1. 1. POST /auth → 生成重定向URL
2. 将URL输出到stdout（代理通过WhatsApp/邮件发送）
3. 轮询 pendingcallbacks/{state}.json（需要callbackserver运行）
4. 使用code进行POST /sessions
5. 保存 mandanten/{id}.json

scripts/fetch.py — 自主数据获取

bash

单个租户

python scripts/fetch.py --mandant-id mandant-1

所有租户

python scripts/fetch.py --all

日期范围

python scripts/fetch.py --mandant-id mandant-1 --date-from 2026-03-01 --date-to 2026-03-10

仅获取余额或交易记录

python scripts/fetch.py --mandant-id mandant-1 --balances-only python scripts/fetch.py --mandant-id mandant-1 --transactions-only

• - 默认日期范围：最近30天
• 保存到 data/{mandant-id}/{YYYY-MM-DD}.json
• 更新租户文件中的 lastFetch
• 退出码2：会话已过期（需要续期）

scripts/renew.py — 会话续期

bash
python scripts/renew.py --mandant-id mueller
python scripts/renew.py --mandant-id mueller --code ABC123

• - 使用现有租户文件中的银行和国家信息
• 与onboard相同的认证流程
• 在租户文件中保留上一会话的备份

租户数据格式

mandanten/{id}.json：
json
{
mandantId: mueller,
bank: Sparkasse Karlsruhe,
country: DE,
psuType: personal,
sessionId: cbe3cd33-...,
accounts: [
{
uid: 2818be38-...,
iban: DE17...,
name: Max Mueller,
currency: EUR,
product: Sichteinlagen
}
],
validUntil: 2026-09-06T07:18:35Z,
createdAt: 2026-03-10T08:18:00Z,
lastFetch: null
}

获取输出格式

data/{id}/{date}.json 和 stdout：
json
{
mandantId: mueller,
fetchedAt: 2026-03-10T08:00:00Z,
accounts: [
{
uid: ...,
iban: DE17...,
name: Max Mueller,
balances: [
{type: CLBD, amount: -993.13, currency: EUR, date: 2026-03-10}
],
transactions: [
{
date: 2026-03-02,
amount: -171.00,
currency: EUR,
creditDebit: DBIT,
counterparty: ...,
description: ...,
bookingDate: 2026-03-02,
valueDate: 2026-03-02
}
]
}
]
}

依赖项

• - Python 3.10+
• PyJWT (pip install PyJWT)
• cryptography (pip install cryptography)
• requests (pip install requests)

部署

本地（开发/测试）：

• - 回调服务器使用自签名