1. 项目概述一个为金融数据自由而生的命令行工具如果你曾经尝试过从德国的银行获取自己的交易数据或者想自动化处理一些财务对账任务那你大概率听说过或体验过“FinTS”协议。这是一个在德语区德国、奥地利、瑞士银行业广泛使用的标准全称是“金融交易服务”可以把它理解为德国版的“Open Banking”接口。然而与一些现代API不同FinTS协议本身相当古老且复杂充满了各种银行特有的“方言”和加密要求直接与之对话的体验堪比用命令行操作一台老式传真机。这就是h4gen/fints-agent-cli这个项目诞生的背景。它不是一个庞大的金融科技平台而是一个精巧、专注的命令行工具。它的核心使命非常明确扮演一个“翻译官”和“信使”的角色将复杂的FinTS协议封装成简单、可脚本化的命令行操作。你可以通过它用几条简单的命令查询账户余额、获取交易流水、甚至发起转账如果银行支持而无需关心底层HTTPS连接、PIN/TAN验证流程、以及令人头疼的数据格式解析。我最初接触这个工具是因为需要定期将多个银行账户的数据同步到自己的财务数据库中。手动导出CSV再导入太繁琐而各大银行提供的官方应用接口要么不存在要么限制重重。fints-agent-cli的出现让我能够用cron任务在服务器上定时运行全自动地抓取数据整个过程清晰、透明且完全受自己控制。它解决的不是一个“有没有”的问题而是一个“好不好用”、“自不自由”的问题。对于开发者、财务自动化爱好者、以及任何希望将个人财务数据掌握在自己手中的人来说这个工具提供了一个极其优雅的解决方案。它不改变银行的后端而是在你和银行之间铺设了一条由代码构成的、可靠的数据管道。2. 核心架构与工作原理拆解要理解fints-agent-cli的价值我们必须先深入看看它要对付的“怪兽”——FinTS协议本身以及这个工具是如何将其驯服的。2.1 FinTS协议古老标准与现代需求的碰撞FinTS前身是著名的“HBCI”是一个基于ISO 8583和XML的银行业务通信标准。它的设计初衷是安全可靠因此具备以下特点这些特点也构成了主要的接入门槛基于PIN/TAN的双因素认证这是核心安全机制。首先用PIN口令登录然后对于任何敏感操作如查询余额、获取交易列表、转账银行服务器会返回一个TAN交易认证码挑战用户必须从另一个渠道短信、TAN生成器、照片TAN获取这个TAN并提交操作才能完成。fints-agent-cli需要完整支持这个交互流程。银行特定的参数Banking Profile每家银行甚至每个银行代码BLZ对应的服务器地址、端口、支持的TAN方式、SSL证书要求都可能不同。工具必须维护一个可靠的数据源来获取这些信息。复杂的报文格式通信报文是结构化的、包含多个“段”的文本每个段有特定的含义和格式。手动构造和解析这些报文是噩梦。状态性会话一次查询或交易往往需要多个步骤的报文往返工具需要维护会话状态。fints-agent-cli并没有重新发明轮子去解析这些报文。它明智地选择站在巨人的肩膀上——即底层的fints库。这个库用Python实现了FinTS协议的核心。CLI工具的角色是提供一个友好、统一的前端将命令行参数转化为对fints库的调用并处理诸如配置文件管理、TAN交互、输出格式化等“脏活累活”。2.2 工具的核心组件与数据流整个工具的工作流可以清晰地分为几个阶段下图展示了从用户输入命令到获取结果的全过程flowchart TD A[用户执行CLI命令] -- B[解析参数与加载配置] B -- C[初始化FinTS客户端] C -- D[发起连接与PIN登录] D -- E{是否需要TAN?} E -- 是 -- F[触发TAN回调br控制台/脚本] F -- G[用户提交TAN] G -- H[完成请求] E -- 否 -- H H -- I[解析银行返回的原始数据] I -- J[格式化为JSON/CSV等] J -- K[输出结果]配置层这是使用的起点。用户需要在一个配置文件如~/.config/fints-agent-cli/config.yaml中预先定义好一个或多个“账户”。每个账户配置包含了银行代码、登录名、PIN、服务器URL等核心信息。工具启动时首先读取并验证这些配置。客户端初始化层根据配置工具调用fints库创建客户端实例。这一步会处理SSL上下文可能涉及加载自定义证书、设置用户代理、并与指定的银行服务器建立连接。认证与交互层这是最动态的部分。工具发送初始登录请求。如果银行返回一个TAN挑战fints-agent-cli会触发一个预设的“回调机制”。默认情况下它会在控制台打印提示等待用户手动输入TAN。但更强大的用法是你可以配置一个外部脚本作为回调。例如我配置了一个脚本当需要短信TAN时自动从我的电脑通知栏读取最新短信并提取TAN实现半自动化。对于照片TAN甚至可以结合OCR技术。这个设计极大地扩展了工具的自动化潜力。业务逻辑与格式化层一旦认证通过工具便执行用户请求的具体操作如get-accounts获取账户列表、get-transactions获取交易。fints库返回的是Python对象。fints-agent-cli再将这些对象序列化成更通用的格式默认是JSON也支持CSV方便被其他程序如Python pandas, jq, 或你的记账软件直接消费。输出层最终格式化后的数据被打印到标准输出。你可以用管道|将其重定向到文件或直接作为另一个命令的输入。关键设计心得fints-agent-cli的架构体现了优秀的Unix哲学——“做一件事并做好”。它不试图成为一个全功能的GUI财务软件而是坚定地做一个“过滤器”从FinTS协议输入向标准输出吐出结构化数据。这使得它能完美地嵌入任何自动化工作流中价值倍增。3. 从零开始配置与核心命令实战理论说得再多不如动手操作一遍。下面我将带你完成一次完整的配置和使用流程其中会穿插我踩过坑后才总结出的关键技巧。3.1 环境准备与安装首先你需要一个Python环境3.7以上。推荐使用虚拟环境来管理依赖避免污染系统Python。# 1. 创建并进入虚拟环境 python3 -m venv ~/.venv/fints source ~/.venv/fints/bin/activate # Linux/macOS # 对于Windows: ~\.venv\fints\Scripts\activate # 2. 安装 fints-agent-cli pip install fints-agent-cli安装过程很简单。但这里有一个至关重要的注意事项FinTS协议严重依赖密码学操作和XML处理在Windows上有时会遇到编译依赖库如cryptography的问题。如果安装失败请先尝试升级你的pip和setuptools或者寻找预编译的wheel包。在Linux/macOS上通常很顺利。3.2 编写你的第一个配置文件配置是核心。工具默认会在~/.config/fints-agent-cli/config.yaml寻找配置文件。我们创建一个# ~/.config/fints-agent-cli/config.yaml accounts: my_checking_account: # 这是一个账户配置的标识符你可以自定义 blz: 12345678 # 你的银行代码Bankleitzahl login: your_login_id # 你的网上银行登录名 pin: your_pin # 你的PIN码。⚠️安全警告考虑用环境变量或密文 url: https://fints.your-bank.de/fints # 以上是最低配置。url如果不知道工具可以尝试根据blz自动发现。 # 但自动发现可能失败手动指定最可靠。 my_savings_account: blz: 87654321 login: your_other_login pin: !ENV ${FINTS_PIN_SAVINGS} # 高级技巧从环境变量读取PIN更安全 # 工具支持 !ENV 标签来引用环境变量 url: https://fints.another-bank.de/fints安全警告与最佳实践 明文存储PIN码是高风险行为。fints-agent-cli支持从环境变量读取配置值。我强烈建议你这样操作将PIN码存入环境变量export FINTS_PIN_MAINyour_pin在配置文件中使用pin: !ENV ${FINTS_PIN_MAIN}对于生产环境或服务器考虑使用专门的密钥管理服务或加密的配置文件。3.3 探索与测试核心命令详解配置好后我们就可以开始探索了。所有命令都遵循fints 账户标识符 操作的基本格式。3.3.1 获取账户列表握手测试这是你首先应该运行的命令用于测试配置是否正确并与银行建立首次连接。fints my_checking_account get-accounts执行过程与解读工具读取my_checking_account的配置。尝试连接指定的URL或根据BLZ查找。发起初始的“对话初始化”请求。这里银行可能会返回支持的TAN方法和账户列表。关键点第一次为某个账户运行命令时银行很可能要求进行TAN验证即使只是获取账户列表。这是正常的因为银行需要确认你的身份有权访问信息。按照控制台提示完成TAN输入。成功后你会看到类似JSON的输出里面列出了该登录名下所有可访问的账户包括账号、IBAN、BIC、账户类型Girokonto, Sparkonto等和可用余额。这个命令的输出是你后续操作的基础因为很多银行需要你使用内部账户ID而不是IBAN来查询交易。3.3.2 获取交易记录核心功能这是最常用的功能。假设我们从账户列表里拿到了目标账户的内部ID是DE12345678901234567890。# 获取最近30天的交易 fints my_checking_account get-transactions --iban DE12345678901234567890 --days 30 # 获取指定日期范围的交易 fints my_checking_account get-transactions --iban DE12345678901234567890 --from 2024-01-01 --to 2024-01-31 # 以CSV格式输出便于导入电子表格 fints my_checking_account get-transactions --iban DE12345678901234567890 --days 7 --format csv参数解析与技巧--iban这里其实填IBAN或之前获取的内部账户ID都可以。但有些银行对IBAN支持更好有些则必须用内部ID。如果一种方式失败换另一种试试。--days/--from/--to控制时间范围。注意银行对可查询的历史数据有保留期限通常是一到三个月。更早的数据可能无法通过接口获取。--format json/csv选择输出格式。JSON包含最完整的信息如交易对手的姓名、银行代码、用途等CSV则更轻量适合直接分析。3.3.3 自动化之魂TAN回调脚本手动输入TAN是自动化的最大障碍。fints-agent-cli允许你通过--tan-callback参数指定一个外部脚本来处理TAN挑战。假设我们创建一个简单的脚本/path/to/my_tan_handler.sh#!/bin/bash # 这个脚本会从标准输入读取银行发来的TAN挑战信息JSON格式 # 然后需要向标准输出写入一个JSON包含获取到的TAN # 读取银行发来的挑战信息 challenge_input$(cat) # 你可以在这里解析 challenge_input提取挑战文本等信息。 # 例如挑战文本可能会显示在手机银行APP上。 echo 银行请求TAN请查看你的手机银行。 2 echo $challenge_input | jq . 2 # 用jq美化输出到标准错误方便查看 # 模拟这里我们假设通过某种方式如读取短信数据库获取了TAN # 实际应用中这里可能是调用一个AppleScript弹窗或读取一个文件。 retrieved_tan123456 # 输出所需的JSON echo {\tan\: \$retrieved_tan\}然后这样使用fints my_checking_account get-accounts --tan-callback /path/to/my_tan_handler.sh当银行需要TAN时工具会调用你的脚本将挑战信息通过标准输入传递给它并等待脚本从标准输出返回TAN。这意味着你可以集成任何你能想到的获取TAN的方式图形化弹窗、读取特定通知、甚至在安全环境下从加密的文件中读取静态TAN仅用于某些测试场景。实操心得实现全自动TAN处理是FinTS自动化的“圣杯”但也伴随着安全风险。务必确保你的回调脚本在安全的环境中运行并且不会泄露TAN。对于生产环境我建议采用“半自动”方式脚本收到挑战后通过系统通知如notify-send或osascript提醒用户然后暂停并等待用户在终端输入这比完全手动操作效率高又比全自动更安全。4. 高级应用场景与集成方案当你能够稳定地获取数据后fints-agent-cli的真正威力才开始显现。它不再是一个孤立的工具而是你个人财务数据基础设施的“采集器”。4.1 构建个人财务数据管道我的核心使用场景是构建一个自动化的数据管道架构如下定时触发使用 Linux 的cron或 macOS 的launchd每周日凌晨2点执行数据抓取脚本。数据采集脚本中依次调用fints-agent-cli获取所有配置账户的交易数据例如过去7天输出为JSON。数据清洗与转换使用jq或 Python 脚本如pandas解析JSON将数据转换成标准格式。例如统一日期格式、货币符号将德语描述翻译或分类如“GIROPAY”归类为“线上支付”。数据存储将清洗后的数据追加到数据库如SQLite、PostgreSQL或数据文件如Parquet中。这里我推荐使用SQLite它简单、零配置非常适合个人项目。分析与可视化数据入库后你可以用任何喜欢的工具进行分析。我用 Metabase 连接这个SQLite数据库制作了个人仪表盘实时查看月度支出分类、净资产趋势、预算执行情况等。一个简化的cron脚本示例#!/bin/bash # ~/scripts/fetch_finance.sh source ~/.venv/fints/bin/activate # 获取支票账户数据 fints my_checking_account get-transactions --days 7 --format json /tmp/transactions_checking_$(date %Y%m%d).json # 获取储蓄账户余额 fints my_savings_account get-balance --format json /tmp/balance_savings_$(date %Y%m%d).json # 然后调用一个Python脚本进行后续处理 python ~/scripts/process_and_store.py4.2 与现有记账软件集成很多人使用现成的记账软件如 GnuCash、MoneyMoneymacOS或在线应用。fints-agent-cli可以作为这些软件的“数据供给器”。GnuCashGnuCash支持通过CSV导入交易。你可以定期运行fints-agent-cli生成CSV然后在GnuCash中使用“导入交易”功能并配置一个固定的“导入规则”来自动分类。虽然不能完全一键导入但比手动录入快得多。MoneyMoneyMoneyMoney本身支持很多欧洲银行的直接同步。但对于它不支持的银行你可以编写一个简单的“插件”本质是一个能输出特定格式JSON的脚本在脚本内部调用fints-agent-cli。这样就能将任意支持FinTS的银行添加到MoneyMoney中。自研应用对于开发者这是最灵活的方案。你可以写一个简单的Flask或FastAPI服务提供一个/api/transactions端点内部调用fints-agent-cli。然后你的手机App或网页前端就可以调用这个API来展示数据完全掌控界面和逻辑。4.3 安全与维护考量自动化带来了便利也带来了责任。凭证管理永远不要将PIN码硬编码在脚本或配置文件中并上传到GitHub等公开仓库。务必使用环境变量并确保你的服务器或本地环境安全。考虑使用passUnix密码管理器或操作系统提供的密钥链来管理这些秘密。错误处理你的自动化脚本必须有健壮的错误处理。网络可能中断银行服务器可能维护TAN可能失效。脚本应该能捕获fints-agent-cli返回的非零退出码记录详细的错误日志并在必要时发送警报如邮件、Telegram消息而不是静默失败。数据去重定时抓取时要小心处理交易重叠区间。如果每次抓取过去7天的数据那么周末运行的任务会抓到大量重复交易。你的处理脚本需要根据交易ID、日期、金额、对手方等信息进行去重再存入数据库。遵守银行条款频繁地、自动化地查询账户可能违反某些银行的服务条款。请合理设置查询频率如每天一次或每周一次避免对银行服务器造成不必要的负载。5. 疑难杂症与调试指南即使按照指南操作你也可能会遇到问题。下面是我在实践中总结的常见问题及其解决方法。5.1 连接与初始化问题问题ConnectionError或SSLError。原因银行使用了自定义的SSL证书或过时的TLS协议Python的默认SSL上下文无法验证。排查首先尝试用curl -v https://your-bank-fints-url测试是否能连通。如果curl也报证书错误说明是银行证书问题。对于自签名证书你可以通过--custom-cert参数如果工具支持或设置REQUESTS_CA_BUNDLE环境变量来指定证书包。更常见的是某些老式服务器需要降级TLS版本。这需要修改底层fints库的代码或urllib3的配置比较棘手。一个变通方法是使用一个反向代理如本地运行的Nginx来与银行通信由代理处理SSL协商而fints-agent-cli连接代理的HTTP端口。问题Bank not found或无法自动发现URL。原因工具内置的银行数据库可能没有你银行的条目或者信息已过时。解决放弃自动发现手动指定url参数。银行的FinTS URL通常可以在其官网的帮助页面或搜索“FinTS URL”加上银行名称找到。这是最可靠的方-法。5.2 认证与TAN问题问题登录失败提示“PIN错误”或“用户被锁定”。原因PIN码确实错误或连续失败次数过多导致账户被临时锁定。解决先用网上银行网页或App确认PIN码是否正确。如果账户被锁通常等待一段时间如15分钟到几小时会自动解锁或需要联系银行解锁。重要有些银行的“PIN”可能不是你的网银登录密码而是一个专门为FinTS/HBCI接口设置的“接口密码”需要在网银设置中单独申请和激活。请仔细核对。问题TAN方式不被支持或回调脚本不工作。原因银行可能只支持特定的TAN方式如短信TAN、手机TAN、照片TAN。fints-agent-cli需要知道使用哪种方式。排查运行fints account get-accounts -v增加verbose输出查看初始握手时银行返回了哪些支持的TAN方式。在配置文件中你可以尝试指定tan_mechanism参数如tan_mechanism: 901对于照片TAN或tan_mechanism: 920对于短信TAN。具体的代码需要查阅银行的文档或从verbose输出中获取。对于回调脚本确保它有执行权限chmod x并且输入输出格式符合要求。在脚本开头加入set -x或大量使用echo 2来调试看它是否被正确调用以及收到了什么数据。5.3 数据与业务逻辑问题问题获取到的交易数据不全或日期范围不对。原因FinTS协议本身和银行实现都可能有限制。有些银行一次最多返回100条交易有些则对查询的起止日期有严格限制如不能超过90天。解决分页查询如果数据量大你需要实现分页逻辑。fints-agent-cli可能不直接支持你需要手动控制--from和--to参数进行多次查询后合并结果。调整范围尝试缩短查询的天数比如从--days 90改为--days 30。使用“获取新交易”功能有些银行支持基于“点指针”获取上次查询之后的交易这比按日期查询更可靠。查看fints-agent-cli是否支持类似--since-last的参数。问题JSON输出字段名难以理解或为空。原因FinTS协议返回的原始字段名是德语的且不同银行填充数据的完整度不同。解决这是常态。你需要编写一个映射层。例如工具输出的purpose字段可能包含混乱的拼接文本。你需要用正则表达式或字符串匹配来提取有用的信息如订单号、收款人备注。这是一个需要针对每家银行进行微调的过程。5.4 调试与日志当一切都不奏效时打开详细日志是最后的法宝。# 使用 -v 或 --verbose 标志 fints my_checking_account get-accounts -v # 更详细的调试可以设置环境变量 DEBUG1 fints my_checking_account get-accountsverbose 输出会显示发送和接收的原始FinTS报文脱敏后这对于理解通信流程、定位在哪一步出错至关重要。你可以看到银行返回的具体错误代码和消息根据这些信息去搜索往往能找到解决方案。最后记住开源社区是你的后盾。h4gen/fints-agent-cli项目本身的GitHub Issues页面以及底层fints库的讨论区是寻找答案和分享经验的宝贵资源。很多奇怪的问题可能已经有先驱者遇到了并提供了解决方案。
FinTS协议自动化实战：用fints-agent-cli构建个人财务数据管道
1. 项目概述一个为金融数据自由而生的命令行工具如果你曾经尝试过从德国的银行获取自己的交易数据或者想自动化处理一些财务对账任务那你大概率听说过或体验过“FinTS”协议。这是一个在德语区德国、奥地利、瑞士银行业广泛使用的标准全称是“金融交易服务”可以把它理解为德国版的“Open Banking”接口。然而与一些现代API不同FinTS协议本身相当古老且复杂充满了各种银行特有的“方言”和加密要求直接与之对话的体验堪比用命令行操作一台老式传真机。这就是h4gen/fints-agent-cli这个项目诞生的背景。它不是一个庞大的金融科技平台而是一个精巧、专注的命令行工具。它的核心使命非常明确扮演一个“翻译官”和“信使”的角色将复杂的FinTS协议封装成简单、可脚本化的命令行操作。你可以通过它用几条简单的命令查询账户余额、获取交易流水、甚至发起转账如果银行支持而无需关心底层HTTPS连接、PIN/TAN验证流程、以及令人头疼的数据格式解析。我最初接触这个工具是因为需要定期将多个银行账户的数据同步到自己的财务数据库中。手动导出CSV再导入太繁琐而各大银行提供的官方应用接口要么不存在要么限制重重。fints-agent-cli的出现让我能够用cron任务在服务器上定时运行全自动地抓取数据整个过程清晰、透明且完全受自己控制。它解决的不是一个“有没有”的问题而是一个“好不好用”、“自不自由”的问题。对于开发者、财务自动化爱好者、以及任何希望将个人财务数据掌握在自己手中的人来说这个工具提供了一个极其优雅的解决方案。它不改变银行的后端而是在你和银行之间铺设了一条由代码构成的、可靠的数据管道。2. 核心架构与工作原理拆解要理解fints-agent-cli的价值我们必须先深入看看它要对付的“怪兽”——FinTS协议本身以及这个工具是如何将其驯服的。2.1 FinTS协议古老标准与现代需求的碰撞FinTS前身是著名的“HBCI”是一个基于ISO 8583和XML的银行业务通信标准。它的设计初衷是安全可靠因此具备以下特点这些特点也构成了主要的接入门槛基于PIN/TAN的双因素认证这是核心安全机制。首先用PIN口令登录然后对于任何敏感操作如查询余额、获取交易列表、转账银行服务器会返回一个TAN交易认证码挑战用户必须从另一个渠道短信、TAN生成器、照片TAN获取这个TAN并提交操作才能完成。fints-agent-cli需要完整支持这个交互流程。银行特定的参数Banking Profile每家银行甚至每个银行代码BLZ对应的服务器地址、端口、支持的TAN方式、SSL证书要求都可能不同。工具必须维护一个可靠的数据源来获取这些信息。复杂的报文格式通信报文是结构化的、包含多个“段”的文本每个段有特定的含义和格式。手动构造和解析这些报文是噩梦。状态性会话一次查询或交易往往需要多个步骤的报文往返工具需要维护会话状态。fints-agent-cli并没有重新发明轮子去解析这些报文。它明智地选择站在巨人的肩膀上——即底层的fints库。这个库用Python实现了FinTS协议的核心。CLI工具的角色是提供一个友好、统一的前端将命令行参数转化为对fints库的调用并处理诸如配置文件管理、TAN交互、输出格式化等“脏活累活”。2.2 工具的核心组件与数据流整个工具的工作流可以清晰地分为几个阶段下图展示了从用户输入命令到获取结果的全过程flowchart TD A[用户执行CLI命令] -- B[解析参数与加载配置] B -- C[初始化FinTS客户端] C -- D[发起连接与PIN登录] D -- E{是否需要TAN?} E -- 是 -- F[触发TAN回调br控制台/脚本] F -- G[用户提交TAN] G -- H[完成请求] E -- 否 -- H H -- I[解析银行返回的原始数据] I -- J[格式化为JSON/CSV等] J -- K[输出结果]配置层这是使用的起点。用户需要在一个配置文件如~/.config/fints-agent-cli/config.yaml中预先定义好一个或多个“账户”。每个账户配置包含了银行代码、登录名、PIN、服务器URL等核心信息。工具启动时首先读取并验证这些配置。客户端初始化层根据配置工具调用fints库创建客户端实例。这一步会处理SSL上下文可能涉及加载自定义证书、设置用户代理、并与指定的银行服务器建立连接。认证与交互层这是最动态的部分。工具发送初始登录请求。如果银行返回一个TAN挑战fints-agent-cli会触发一个预设的“回调机制”。默认情况下它会在控制台打印提示等待用户手动输入TAN。但更强大的用法是你可以配置一个外部脚本作为回调。例如我配置了一个脚本当需要短信TAN时自动从我的电脑通知栏读取最新短信并提取TAN实现半自动化。对于照片TAN甚至可以结合OCR技术。这个设计极大地扩展了工具的自动化潜力。业务逻辑与格式化层一旦认证通过工具便执行用户请求的具体操作如get-accounts获取账户列表、get-transactions获取交易。fints库返回的是Python对象。fints-agent-cli再将这些对象序列化成更通用的格式默认是JSON也支持CSV方便被其他程序如Python pandas, jq, 或你的记账软件直接消费。输出层最终格式化后的数据被打印到标准输出。你可以用管道|将其重定向到文件或直接作为另一个命令的输入。关键设计心得fints-agent-cli的架构体现了优秀的Unix哲学——“做一件事并做好”。它不试图成为一个全功能的GUI财务软件而是坚定地做一个“过滤器”从FinTS协议输入向标准输出吐出结构化数据。这使得它能完美地嵌入任何自动化工作流中价值倍增。3. 从零开始配置与核心命令实战理论说得再多不如动手操作一遍。下面我将带你完成一次完整的配置和使用流程其中会穿插我踩过坑后才总结出的关键技巧。3.1 环境准备与安装首先你需要一个Python环境3.7以上。推荐使用虚拟环境来管理依赖避免污染系统Python。# 1. 创建并进入虚拟环境 python3 -m venv ~/.venv/fints source ~/.venv/fints/bin/activate # Linux/macOS # 对于Windows: ~\.venv\fints\Scripts\activate # 2. 安装 fints-agent-cli pip install fints-agent-cli安装过程很简单。但这里有一个至关重要的注意事项FinTS协议严重依赖密码学操作和XML处理在Windows上有时会遇到编译依赖库如cryptography的问题。如果安装失败请先尝试升级你的pip和setuptools或者寻找预编译的wheel包。在Linux/macOS上通常很顺利。3.2 编写你的第一个配置文件配置是核心。工具默认会在~/.config/fints-agent-cli/config.yaml寻找配置文件。我们创建一个# ~/.config/fints-agent-cli/config.yaml accounts: my_checking_account: # 这是一个账户配置的标识符你可以自定义 blz: 12345678 # 你的银行代码Bankleitzahl login: your_login_id # 你的网上银行登录名 pin: your_pin # 你的PIN码。⚠️安全警告考虑用环境变量或密文 url: https://fints.your-bank.de/fints # 以上是最低配置。url如果不知道工具可以尝试根据blz自动发现。 # 但自动发现可能失败手动指定最可靠。 my_savings_account: blz: 87654321 login: your_other_login pin: !ENV ${FINTS_PIN_SAVINGS} # 高级技巧从环境变量读取PIN更安全 # 工具支持 !ENV 标签来引用环境变量 url: https://fints.another-bank.de/fints安全警告与最佳实践 明文存储PIN码是高风险行为。fints-agent-cli支持从环境变量读取配置值。我强烈建议你这样操作将PIN码存入环境变量export FINTS_PIN_MAINyour_pin在配置文件中使用pin: !ENV ${FINTS_PIN_MAIN}对于生产环境或服务器考虑使用专门的密钥管理服务或加密的配置文件。3.3 探索与测试核心命令详解配置好后我们就可以开始探索了。所有命令都遵循fints 账户标识符 操作的基本格式。3.3.1 获取账户列表握手测试这是你首先应该运行的命令用于测试配置是否正确并与银行建立首次连接。fints my_checking_account get-accounts执行过程与解读工具读取my_checking_account的配置。尝试连接指定的URL或根据BLZ查找。发起初始的“对话初始化”请求。这里银行可能会返回支持的TAN方法和账户列表。关键点第一次为某个账户运行命令时银行很可能要求进行TAN验证即使只是获取账户列表。这是正常的因为银行需要确认你的身份有权访问信息。按照控制台提示完成TAN输入。成功后你会看到类似JSON的输出里面列出了该登录名下所有可访问的账户包括账号、IBAN、BIC、账户类型Girokonto, Sparkonto等和可用余额。这个命令的输出是你后续操作的基础因为很多银行需要你使用内部账户ID而不是IBAN来查询交易。3.3.2 获取交易记录核心功能这是最常用的功能。假设我们从账户列表里拿到了目标账户的内部ID是DE12345678901234567890。# 获取最近30天的交易 fints my_checking_account get-transactions --iban DE12345678901234567890 --days 30 # 获取指定日期范围的交易 fints my_checking_account get-transactions --iban DE12345678901234567890 --from 2024-01-01 --to 2024-01-31 # 以CSV格式输出便于导入电子表格 fints my_checking_account get-transactions --iban DE12345678901234567890 --days 7 --format csv参数解析与技巧--iban这里其实填IBAN或之前获取的内部账户ID都可以。但有些银行对IBAN支持更好有些则必须用内部ID。如果一种方式失败换另一种试试。--days/--from/--to控制时间范围。注意银行对可查询的历史数据有保留期限通常是一到三个月。更早的数据可能无法通过接口获取。--format json/csv选择输出格式。JSON包含最完整的信息如交易对手的姓名、银行代码、用途等CSV则更轻量适合直接分析。3.3.3 自动化之魂TAN回调脚本手动输入TAN是自动化的最大障碍。fints-agent-cli允许你通过--tan-callback参数指定一个外部脚本来处理TAN挑战。假设我们创建一个简单的脚本/path/to/my_tan_handler.sh#!/bin/bash # 这个脚本会从标准输入读取银行发来的TAN挑战信息JSON格式 # 然后需要向标准输出写入一个JSON包含获取到的TAN # 读取银行发来的挑战信息 challenge_input$(cat) # 你可以在这里解析 challenge_input提取挑战文本等信息。 # 例如挑战文本可能会显示在手机银行APP上。 echo 银行请求TAN请查看你的手机银行。 2 echo $challenge_input | jq . 2 # 用jq美化输出到标准错误方便查看 # 模拟这里我们假设通过某种方式如读取短信数据库获取了TAN # 实际应用中这里可能是调用一个AppleScript弹窗或读取一个文件。 retrieved_tan123456 # 输出所需的JSON echo {\tan\: \$retrieved_tan\}然后这样使用fints my_checking_account get-accounts --tan-callback /path/to/my_tan_handler.sh当银行需要TAN时工具会调用你的脚本将挑战信息通过标准输入传递给它并等待脚本从标准输出返回TAN。这意味着你可以集成任何你能想到的获取TAN的方式图形化弹窗、读取特定通知、甚至在安全环境下从加密的文件中读取静态TAN仅用于某些测试场景。实操心得实现全自动TAN处理是FinTS自动化的“圣杯”但也伴随着安全风险。务必确保你的回调脚本在安全的环境中运行并且不会泄露TAN。对于生产环境我建议采用“半自动”方式脚本收到挑战后通过系统通知如notify-send或osascript提醒用户然后暂停并等待用户在终端输入这比完全手动操作效率高又比全自动更安全。4. 高级应用场景与集成方案当你能够稳定地获取数据后fints-agent-cli的真正威力才开始显现。它不再是一个孤立的工具而是你个人财务数据基础设施的“采集器”。4.1 构建个人财务数据管道我的核心使用场景是构建一个自动化的数据管道架构如下定时触发使用 Linux 的cron或 macOS 的launchd每周日凌晨2点执行数据抓取脚本。数据采集脚本中依次调用fints-agent-cli获取所有配置账户的交易数据例如过去7天输出为JSON。数据清洗与转换使用jq或 Python 脚本如pandas解析JSON将数据转换成标准格式。例如统一日期格式、货币符号将德语描述翻译或分类如“GIROPAY”归类为“线上支付”。数据存储将清洗后的数据追加到数据库如SQLite、PostgreSQL或数据文件如Parquet中。这里我推荐使用SQLite它简单、零配置非常适合个人项目。分析与可视化数据入库后你可以用任何喜欢的工具进行分析。我用 Metabase 连接这个SQLite数据库制作了个人仪表盘实时查看月度支出分类、净资产趋势、预算执行情况等。一个简化的cron脚本示例#!/bin/bash # ~/scripts/fetch_finance.sh source ~/.venv/fints/bin/activate # 获取支票账户数据 fints my_checking_account get-transactions --days 7 --format json /tmp/transactions_checking_$(date %Y%m%d).json # 获取储蓄账户余额 fints my_savings_account get-balance --format json /tmp/balance_savings_$(date %Y%m%d).json # 然后调用一个Python脚本进行后续处理 python ~/scripts/process_and_store.py4.2 与现有记账软件集成很多人使用现成的记账软件如 GnuCash、MoneyMoneymacOS或在线应用。fints-agent-cli可以作为这些软件的“数据供给器”。GnuCashGnuCash支持通过CSV导入交易。你可以定期运行fints-agent-cli生成CSV然后在GnuCash中使用“导入交易”功能并配置一个固定的“导入规则”来自动分类。虽然不能完全一键导入但比手动录入快得多。MoneyMoneyMoneyMoney本身支持很多欧洲银行的直接同步。但对于它不支持的银行你可以编写一个简单的“插件”本质是一个能输出特定格式JSON的脚本在脚本内部调用fints-agent-cli。这样就能将任意支持FinTS的银行添加到MoneyMoney中。自研应用对于开发者这是最灵活的方案。你可以写一个简单的Flask或FastAPI服务提供一个/api/transactions端点内部调用fints-agent-cli。然后你的手机App或网页前端就可以调用这个API来展示数据完全掌控界面和逻辑。4.3 安全与维护考量自动化带来了便利也带来了责任。凭证管理永远不要将PIN码硬编码在脚本或配置文件中并上传到GitHub等公开仓库。务必使用环境变量并确保你的服务器或本地环境安全。考虑使用passUnix密码管理器或操作系统提供的密钥链来管理这些秘密。错误处理你的自动化脚本必须有健壮的错误处理。网络可能中断银行服务器可能维护TAN可能失效。脚本应该能捕获fints-agent-cli返回的非零退出码记录详细的错误日志并在必要时发送警报如邮件、Telegram消息而不是静默失败。数据去重定时抓取时要小心处理交易重叠区间。如果每次抓取过去7天的数据那么周末运行的任务会抓到大量重复交易。你的处理脚本需要根据交易ID、日期、金额、对手方等信息进行去重再存入数据库。遵守银行条款频繁地、自动化地查询账户可能违反某些银行的服务条款。请合理设置查询频率如每天一次或每周一次避免对银行服务器造成不必要的负载。5. 疑难杂症与调试指南即使按照指南操作你也可能会遇到问题。下面是我在实践中总结的常见问题及其解决方法。5.1 连接与初始化问题问题ConnectionError或SSLError。原因银行使用了自定义的SSL证书或过时的TLS协议Python的默认SSL上下文无法验证。排查首先尝试用curl -v https://your-bank-fints-url测试是否能连通。如果curl也报证书错误说明是银行证书问题。对于自签名证书你可以通过--custom-cert参数如果工具支持或设置REQUESTS_CA_BUNDLE环境变量来指定证书包。更常见的是某些老式服务器需要降级TLS版本。这需要修改底层fints库的代码或urllib3的配置比较棘手。一个变通方法是使用一个反向代理如本地运行的Nginx来与银行通信由代理处理SSL协商而fints-agent-cli连接代理的HTTP端口。问题Bank not found或无法自动发现URL。原因工具内置的银行数据库可能没有你银行的条目或者信息已过时。解决放弃自动发现手动指定url参数。银行的FinTS URL通常可以在其官网的帮助页面或搜索“FinTS URL”加上银行名称找到。这是最可靠的方-法。5.2 认证与TAN问题问题登录失败提示“PIN错误”或“用户被锁定”。原因PIN码确实错误或连续失败次数过多导致账户被临时锁定。解决先用网上银行网页或App确认PIN码是否正确。如果账户被锁通常等待一段时间如15分钟到几小时会自动解锁或需要联系银行解锁。重要有些银行的“PIN”可能不是你的网银登录密码而是一个专门为FinTS/HBCI接口设置的“接口密码”需要在网银设置中单独申请和激活。请仔细核对。问题TAN方式不被支持或回调脚本不工作。原因银行可能只支持特定的TAN方式如短信TAN、手机TAN、照片TAN。fints-agent-cli需要知道使用哪种方式。排查运行fints account get-accounts -v增加verbose输出查看初始握手时银行返回了哪些支持的TAN方式。在配置文件中你可以尝试指定tan_mechanism参数如tan_mechanism: 901对于照片TAN或tan_mechanism: 920对于短信TAN。具体的代码需要查阅银行的文档或从verbose输出中获取。对于回调脚本确保它有执行权限chmod x并且输入输出格式符合要求。在脚本开头加入set -x或大量使用echo 2来调试看它是否被正确调用以及收到了什么数据。5.3 数据与业务逻辑问题问题获取到的交易数据不全或日期范围不对。原因FinTS协议本身和银行实现都可能有限制。有些银行一次最多返回100条交易有些则对查询的起止日期有严格限制如不能超过90天。解决分页查询如果数据量大你需要实现分页逻辑。fints-agent-cli可能不直接支持你需要手动控制--from和--to参数进行多次查询后合并结果。调整范围尝试缩短查询的天数比如从--days 90改为--days 30。使用“获取新交易”功能有些银行支持基于“点指针”获取上次查询之后的交易这比按日期查询更可靠。查看fints-agent-cli是否支持类似--since-last的参数。问题JSON输出字段名难以理解或为空。原因FinTS协议返回的原始字段名是德语的且不同银行填充数据的完整度不同。解决这是常态。你需要编写一个映射层。例如工具输出的purpose字段可能包含混乱的拼接文本。你需要用正则表达式或字符串匹配来提取有用的信息如订单号、收款人备注。这是一个需要针对每家银行进行微调的过程。5.4 调试与日志当一切都不奏效时打开详细日志是最后的法宝。# 使用 -v 或 --verbose 标志 fints my_checking_account get-accounts -v # 更详细的调试可以设置环境变量 DEBUG1 fints my_checking_account get-accountsverbose 输出会显示发送和接收的原始FinTS报文脱敏后这对于理解通信流程、定位在哪一步出错至关重要。你可以看到银行返回的具体错误代码和消息根据这些信息去搜索往往能找到解决方案。最后记住开源社区是你的后盾。h4gen/fints-agent-cli项目本身的GitHub Issues页面以及底层fints库的讨论区是寻找答案和分享经验的宝贵资源。很多奇怪的问题可能已经有先驱者遇到了并提供了解决方案。
