获取密钥
- 在 Money Tracker 应用中打开“个人资料”,选择“API 密钥”。
- 点按“创建密钥”,起个名字,并勾选它可以执行的操作。
- 复制 API_KEY 和 API_SECRET。Secret 只显示一次。
每个账户只能有一个有效密钥。要更换它,请在同一界面撤销后再创建新的。撤销后的密钥会立即失效。
身份验证
每次请求都把这两个值作为请求头发送。不要把 Secret 放进 URL、网页或其他人能打开的应用里。
- X-Api-Key
- 你的 API_KEY,以 mtu_ 开头。
- X-Api-Secret
- 你的 API_SECRET,由 40 个字母和数字组成。
curl "https://moneytracker.arizu.id/api/v1/transactions?month=2026-11&type=income" \
-H "X-Api-Key: mtu_YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"权限
密钥只获得你勾选的权限。写入权限包含读取权限。
- transactions:read
- 读取交易
- transactions:write
- 记录、修改和删除交易
- categories:read
- 读取类别
- categories:write
- 添加和删除类别
- money_sources:read
- 读取资金来源及其余额
- money_sources:write
- 添加、修改和删除资金来源
- profile:read
- 读取账户名称、邮箱、货币、语言和方案
接口
路径相对于基础 URL。金额使用账户货币。
账户
-
GET
/api/v1/auth/meprofile:read账户资料。
交易
-
GET
/api/v1/transactionstransactions:read交易列表,最新的在前。筛选参数:month(2026-11)、type(income 或 expense)、source_id、page、per_page(最多 100)。
-
GET
/api/v1/transactions/{id}transactions:read单笔交易。
-
POST
/api/v1/transactionstransactions:write记录一笔交易。必填:type、amount、occurred_on(2026-11-02)。可选:category_id、payment_source_id、note(最多 255 个字符)、client_ref。
-
PUT
/api/v1/transactions/{id}transactions:write修改一笔交易。发送与记录时相同的字段,不含 client_ref。
-
DELETE
/api/v1/transactions/{id}transactions:write删除一笔交易。
类别
-
GET
/api/v1/categoriescategories:read收入和支出类别。
-
POST
/api/v1/categoriescategories:write添加类别。必填:type、name。可选:icon、color(#RRGGBB)、client_ref。
-
DELETE
/api/v1/categories/{id}categories:write删除类别。
资金来源
-
GET
/api/v1/payment-sourcesmoney_sources:read资金来源及其余额。
-
POST
/api/v1/payment-sourcesmoney_sources:write添加资金来源。必填:type(bank、card、ewallet 或 cash)、holder_name。可选:bank_name、provider_name、card_type、card_last4、opening_balance、client_ref。
-
PUT
/api/v1/payment-sources/{id}money_sources:write修改资金来源。
-
DELETE
/api/v1/payment-sources/{id}money_sources:write删除资金来源。
其他所有路径对 API 密钥都会返回 403,即使应用本身在使用这些路径。
示例:记录一笔销售
收银系统可以把每笔销售记录为收入。为每笔销售设置单独的 client_ref,这样网络出错后重试也不会重复记录。
curl -X POST "https://moneytracker.arizu.id/api/v1/transactions" \
-H "X-Api-Key: mtu_YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"type": "income",
"amount": 125000,
"occurred_on": "2026-11-02",
"note": "Sale 1042",
"client_ref": "pos-sale-1042"
}'响应状态为 201,新交易的 id 在 data.id 中。
{
"data": {
"id": 58213,
"amount": "125000.00",
"currency": "IDR",
"original_amount": null,
"original_currency": null,
"fx_rate": null,
"fx_date": null
}
}client_ref 由 8 到 64 个字母、数字或连字符组成。如果账户中已有相同 client_ref 的交易,API 会返回该交易,而不会新建记录。
响应与错误
成功的响应把结果放在 data 中。失败的响应在 error 中给出账户语言的消息,通常还带有在所有语言中都相同的 code。
{
"error": "This API key does not have the permission for this request",
"code": "api_key_scope_missing",
"scope": "transactions:write"
}- 401
- 缺少密钥或 Secret,或者填写错误,或者密钥已被撤销或已过期。
- 403
- 密钥没有执行此请求的权限,该路径不对 API 密钥开放,或者账户已被封禁。
- 404
- 此账户中不存在该项目。
- 422
- 缺少某个字段或字段无效。如果有 fields,会列出需要修正的内容。
- 429
- 请求过多。请等待 Retry-After 响应头中给出的秒数。
限制
每个密钥每分钟最多可发送 60 个请求。方案限制同样适用,与应用内一致。在 Free 方案下,每天最多可新增 30 笔交易。
保护好你的密钥
- 只把 Secret 保存在一个地方(例如收银系统的设置中),不要通过聊天或邮件分享。
- 只勾选该系统需要的权限。
- 如果 Secret 泄露,请在应用中撤销该密钥并创建新的密钥。
- 应用会显示你的密钥最近一次使用的时间。如果与你自己的系统不符,请撤销该密钥。
关于 API 的问题,请写信至 ariefzufar@arizu.id / arizu.team@gmail.com。