Actual Budget API

Actual Budget 的官方 Node.js API。支持无头运行——适用于从服务器同步的本地预算数据。

安装

bash
npm install @actual-app/api

环境变量

变量	必填	说明
ACTUALSERVERURL	是	服务器 URL（例如 https://actual.example.com）
ACTUAL_PASSWORD

是 | 服务器密码 | | ACTUALSYNCID | 是 | 预算同步 ID（设置 → 高级 → 同步 ID） | | ACTUALDATADIR | 否 | 预算数据的本地缓存目录（默认为当前工作目录） | | ACTUALENCRYPTIONPASSWORD | 否 | 端到端加密密码（如已启用） | | NODEEXTRACA_CERTS | 否 | 自签名证书的 CA 证书文件路径 |

自签名证书

如果您的 Actual Budget 服务器使用自签名证书：

1. 1. 推荐： 将您的 CA 添加到系统信任存储中，或
2. 替代方案： 设置 NODEEXTRACA_CERTS=/path/to/your-ca.pem 以信任您的特定 CA

请避免完全禁用 TLS 验证——这会使您暴露于中间人攻击。

快速开始

javascript
const api = require(@actual-app/api);

await api.init({
dataDir: process.env.ACTUALDATADIR || /tmp/actual-cache,
serverURL: process.env.ACTUALSERVERURL,
password: process.env.ACTUAL_PASSWORD,
});

await api.downloadBudget(
process.env.ACTUALSYNCID,
process.env.ACTUALENCRYPTIONPASSWORD ? { password: process.env.ACTUALENCRYPTIONPASSWORD } : undefined
);

// ... 执行操作 ...

await api.shutdown();

核心概念

• - 金额 以分为单位的整数：$50.00 = 5000，-1200 = 支出 $12.00
• 日期 使用 YYYY-MM-DD，月份使用 YYYY-MM
• ID 为 UUID——使用 getIDByName(type, name) 按名称查找
• 使用 api.utils.amountToInteger(123.45) 转换 → 12345

常用操作

获取预算概览

javascript const months = await api.getBudgetMonths(); // [2026-01, 2026-02, ...] const jan = await api.getBudgetMonth(2026-01); // { categoryGroups, incomeAvailable, ... }

账户

javascript const accounts = await api.getAccounts(); const balance = await api.getAccountBalance(accountId); const newId = await api.createAccount({ name: Checking, type: checking }, 50000); // 初始 $500 await api.closeAccount(id, transferToAccountId); // 转移剩余余额

交易

javascript // 获取日期范围内的交易 const txns = await api.getTransactions(accountId, 2026-01-01, 2026-01-31);

// 带去重和规则的导入（银行导入推荐）
const { added, updated } = await api.importTransactions(accountId, [
{ date: 2026-01-15, amount: -2500, payee_name: Grocery Store, notes: Weekly run },
{ date: 2026-01-16, amount: -1200, payeename: Coffee Shop, importedid: bank-123 },
]);

// 更新交易
await api.updateTransaction(txnId, { category: categoryId, cleared: true });

类别与收款方

javascript const categories = await api.getCategories(); const groups = await api.getCategoryGroups(); const payees = await api.getPayees();

// 创建
const catId = await api.createCategory({ name: Subscriptions, group_id: groupId });
const payeeId = await api.createPayee({ name: Netflix, category: catId });

预算金额

javascript await api.setBudgetAmount(2026-01, categoryId, 30000); // 预算 $300 await api.setBudgetCarryover(2026-01, categoryId, true);

规则

javascript const rules = await api.getRules(); await api.createRule({ stage: pre, conditionsOp: and, conditions: [{ field: payee, op: is, value: payeeId }], actions: [{ op: set, field: category, value: categoryId }], });

计划

javascript const schedules = await api.getSchedules(); await api.createSchedule({ payee: payeeId, account: accountId, amount: -1500, date: { frequency: monthly, start: 2026-01-01, interval: 1, endMode: never }, });

银行同步

javascript await api.runBankSync({ accountId }); // GoCardless/SimpleFIN

同步与关闭

javascript await api.sync(); // 推送/拉取更改到服务器 await api.shutdown(); // 完成后始终调用

ActualQL 查询

对于复杂查询，使用 ActualQL：

javascript
const { q, runQuery } = require(@actual-app/api);

// 本月按类别汇总支出
const { data } = await runQuery(
q(transactions)
.filter({
date: [{ $gte: 2026-01-01 }, { $lte: 2026-01-31 }],
amount: { $lt: 0 },
})
.groupBy(category.name)
.select([category.name, { total: { $sum: $amount } }])
);

// 搜索交易
const { data } = await runQuery(
q(transactions)
.filter({ payee.name: { $like: %grocery% } })
.select([date, amount, payee.name, category.name])
.orderBy({ date: desc })
.limit(20)
);

运算符： $eq、$lt、$lte、$gt、$gte、$ne、$oneof、$regex、$like、$notlike
拆分： .options({ splits: inline | grouped | all })

辅助函数

javascript
// 按名称查找 ID
const acctId = await api.getIDByName(accounts, Checking);
const catId = await api.getIDByName(categories, Food);
const payeeId = await api.getIDByName(payees, Amazon);

// 列出预算
const budgets = await api.getBudgets(); // 本地 + 远程文件

转账

转账使用特殊的收款方。通过 transfer_acct 字段查找转账收款方：
javascript
const payees = await api.getPayees();
const transferPayee = payees.find(p => p.transfer_acct === targetAccountId);
await api.importTransactions(fromAccountId, [
{ date: 2026-01-15, amount: -10000, payee: transferPayee.id }
]);

拆分交易

javascript
await api.importTransactions(accountId, [{
date: 2026-01-15,
amount: -5000,
payee_name: Costco,
subtransactions: [
{ amount: -3000, category: groceryCatId },
{ amount: -2000, category: householdCatId },
]
}]);

批量导入（新预算）

用于从其他应用迁移：
javascript
await api.runImport(My-New-Budget, async () => {
for (const acct of myData.accounts) {
const id = await api.createAccount(acct);
await api.addTransactions(id, myData.transactions.filter(t => t.acctId === id));
}
});

参考

完整 API：https://actualbudget.org/docs/api/reference
ActualQL：https://actualbudget.org/docs/api/actual-ql