Firefly III

Firefly III 是一款自托管的个人财务管理工具。本技能提供用于管理财务的 API 接口。

配置

所需环境变量：

• - FIREFLYURL：基础 URL（例如 https://budget.example.com）
• FIREFLYTOKEN：个人访问令牌（存储在 ~/.firefly_token）

获取令牌：个人资料 → OAuth → 个人访问令牌 → 创建新令牌

API 基础

bash
TOKEN=$(cat ~/.firefly_token)
BASE=$FIREFLY_URL/api/v1
curl -s $BASE/endpoint \
-H Authorization: Bearer $TOKEN \
-H Accept: application/json \
-H Content-Type: application/json

核心端点

账户

bash

列出账户

curl $BASE/accounts?type=asset # asset|expense|revenue|liability

创建账户

curl -X POST $BASE/accounts -d { name: 银行账户, type: asset, account_role: defaultAsset, currency_code: EUR }

账户类型：asset（资产）、expense（支出）、revenue（收入）、liability（负债）
资产角色：defaultAsset（默认资产）、savingAsset（储蓄资产）、sharedAsset（共享资产）、ccAsset（信用卡资产）

交易

bash

列出交易

curl $BASE/transactions?type=withdrawal&start=2026-01-01&end=2026-01-31

创建支出交易

curl -X POST $BASE/transactions -d { transactions: [{ type: withdrawal, date: 2026-01-15, amount: 50.00, description: 食品杂货, source_name: 银行账户, destination_name: 超市, category_name: 食品杂货 }] }

创建存款交易（收入）

curl -X POST $BASE/transactions -d { transactions: [{ type: deposit, date: 2026-01-01, amount: 3000.00, description: 工资, source_name: 雇主, destination_name: 银行账户, category_name: 工资 }] }

创建转账交易

curl -X POST $BASE/transactions -d { transactions: [{ type: transfer, date: 2026-01-05, amount: 500.00, description: 储蓄, source_name: 银行账户, destination_name: 储蓄账户 }] }

交易类型：withdrawal（支出）、deposit（存款）、transfer（转账）

类别

bash

列出类别

curl $BASE/categories

创建类别

curl -X POST $BASE/categories -d {name: 食品杂货}

预算

bash

列出预算

curl $BASE/budgets

创建预算

curl -X POST $BASE/budgets -d {name: 餐饮, active: true}

设置预算周期限额

curl -X POST $BASE/budgets/{id}/limits -d { start: 2026-01-01, end: 2026-01-31, amount: 500.00 }

存钱罐（储蓄目标）

bash

列出存钱罐

curl $BASE/piggy-banks

创建存钱罐

curl -X POST $BASE/piggy-banks -d { name: 度假基金, target_amount: 2000.00, accounts: [{account_id: 1}], start_date: 2026-01-01, target_date: 2026-12-31, transactioncurrencycode: EUR }

向存钱罐存钱

curl -X POST $BASE/piggy-banks/{id}/events -d {amount: 100.00}

订阅（账单）

bash

列出订阅

curl $BASE/subscriptions

创建订阅

curl -X POST $BASE/subscriptions -d { name: Netflix, amount_min: 12.99, amount_max: 12.99, date: 2026-01-15, repeat_freq: monthly, currency_code: EUR }

重复频率：weekly（每周）、monthly（每月）、quarterly（每季度）、half-year（每半年）、yearly（每年）

周期性交易

bash

列出周期性交易

curl $BASE/recurrences

创建周期性交易

curl -X POST $BASE/recurrences -d { type: withdrawal, title: 房租, first_date: 2026-01-01, repeat_until: 2026-12-31, repetitions: [{ type: monthly, moment: 1 }], transactions: [{ amount: 1000.00, description: 月租金, source_id: 1, destination_name: 房东, category_name: 房租 }] }

规则（自动分类）

bash

列出规则

curl $BASE/rules

创建规则

curl -X POST $BASE/rules -d { title: 分类食品杂货, trigger: store-journal, active: true, strict: false, triggers: [ {type: description_contains, value: ALDI} ], actions: [ {type: set_category, value: 食品杂货} ] }

触发类型：descriptioncontains（描述包含）、descriptionstarts（描述开头）、descriptionends（描述结尾）、amountless（金额小于）、amountmore（金额大于）、sourceaccount_is（来源账户为）等。
操作类型：setcategory（设置类别）、setbudget（设置预算）、addtag（添加标签）、setdescription（设置描述）等。

标签

bash

列出标签

curl $BASE/tags

创建标签

curl -X POST $BASE/tags -d {tag: 度假}

报表与摘要

bash

账户余额随时间变化

curl $BASE/accounts/{id}/transactions?start=2026-01-01&end=2026-01-31

获取当前余额

curl $BASE/accounts | jq .data[] | {name: .attributes.name, balance: .attributes.current_balance}

常见任务

按类别查看支出

bash curl $BASE/categories | jq .data[] | {name: .attributes.name, spent: .attributes.spent}

查看预算进度

bash curl $BASE/budgets | jq .data[] | {name: .attributes.name, spent: .attributes.spent}

搜索交易

bash curl $BASE/search/transactions?query=食品杂货&limit=25

错误处理

• - 422 Unprocessable Entity：检查错误响应中的必填字段
• 401 Unauthorized：令牌已过期或无效
• 404 Not Found：资源不存在

提示

• - 使用 sourcename/destinationname 可自动创建支出/收入账户
• 类别与预算不同（类别用于分类，预算用于限额）
• 存钱罐需要关联到资产账户
• 使用规则可在创建交易时自动分类