开发者 API

从收银系统或脚本等其他系统读取和记录你自己 Money Tracker 账户中的交易、类别和资金来源。每个密钥只能访问创建它的账户的数据。

基础 URL
https://moneytracker.arizu.id
身份验证
X-Api-Key
X-Api-Secret
格式
通过 HTTPS 传输的 JSON
限制
每个密钥每分钟 60 个请求

获取密钥

  1. 在 Money Tracker 应用中打开“个人资料”,选择“API 密钥”。
  2. 点按“创建密钥”,起个名字,并勾选它可以执行的操作。
  3. 复制 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 中。

响应 201
{
  "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。

响应 403
{
  "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。