ウチかけ API

アプリの外から家計簿を読み書きするための API です。スクリプトや、AIアシスタントから使えます。

1. トークンを発行する

アプリの 設定 → API → APIトークン から発行します。名前を付けて「発行」を押すと、uch_ で始まる文字列が表示されます。

発行したトークンは、そのユーザーが所属するグループの家計簿に紐づきます。使わなくなったらアプリの一覧から左スワイプで失効できます。一覧には最終利用日時が出るので、使っていないものを見つけて消せます。

2. リクエストの共通ルール

• ベース URL: https://kakeibo-api.starhoshi.workers.dev/v1
• 認証: Authorization: Bearer <トークン>
• ボディ・レスポンスとも JSON (Content-Type: application/json)
• 日付は YYYY-MM-DD、月は YYYY-MM
• 金額は円単位の整数

できること

トークンでできるのは次のことだけです。これ以外のパスは 403 を返します。家計簿の削除やグループの操作はできません。

取得できる期間

無料プランでそれ以外の月を指定すると 403 premium_required になります。アプリからはどのプランでも全期間を見られます。制限があるのは API 経由のときだけです。

3. エンドポイント

GET /v1/categories, /v1/payers, /v1/income-sources

明細を登録する前に、ここで ID を引きます。3つとも同じ形です。

curl https://kakeibo-api.starhoshi.workers.dev/v1/categories \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN"

{
  "categories": [
    { "id": "…", "name": "食費", "sortOrder": 0, "isActive": true, "color": "0" }
  ]
}

{ "payers": [{ "id": "…", "name": "妻 メイン口座", "sortOrder": 0, "isActive": true }] }
{ "incomeSources": [{ "id": "…", "name": "夫給与", "sortOrder": 0, "isActive": true }] }

• isActive が false のものは無効化済みです。新しい明細には使わないでください。
• 並びはアプリでの表示順です (sortOrder)。
• color はカテゴリのみ。色そのものではなくインデックスで、実際の色はアプリが計算します。

POST /v1/entries

明細を1件登録します。すべての項目が任意で、1つも指定しなくても登録できます。あとからアプリで埋められます。

curl -X POST https://kakeibo-api.starhoshi.workers.dev/v1/entries \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-08-12",
    "amount": 842,
    "memo": "コンビニ",
    "categoryId": "…",
    "payerId": "…"
  }'

{ "id": "5f1c…" }

同じ明細を二重に登録しないために

id を自分で決めて送ると、同じ id では 2 件目が作られません。応答が返ってこなかったときに、そのまま同じリクエストを送り直せます。

スクリプトが途中で落ちたり、通信が切れて成否が分からなくなったりしたときは、迷わず同じ id で送り直してください。1 件目が入っていればそのまま、入っていなければ今回入ります。

# 何回叩いても 1 件しか入らない
curl -X POST https://kakeibo-api.starhoshi.workers.dev/v1/entries \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "date": "2026-08-12",
    "amount": 842
  }'

2 回目の中身が違っていても、1 件目は書き換わりません (更新は PATCH の仕事です)。

締めた月より前の日付を登録したいとき

「先月のレシートが出てきたが、先月はもう締めた」という場合は、date を実際の日にしたまま postedMonth を今月にします。日付はレシートどおり、集計は今月に載ります。

{ "date": "2026-07-29", "postedMonth": "2026-08", "amount": 5480 }

PATCH /v1/entries/{id}

登録済みの明細を書き換えます。送った項目だけが変わります。触れていない項目はそのままです。

項目は POST /v1/entries と同じです。null を明示的に送ると、その項目を空にできます (たとえば {"categoryId": null} でカテゴリ未設定に戻ります)。省略した場合との違いに注意してください。

curl -X PATCH https://kakeibo-api.starhoshi.workers.dev/v1/entries/5f1c… \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 900, "memo": "コンビニ (訂正)" }'

{ "ok": true }

明細の id は POST /v1/entries の返り値か、 GET /v1/months/{year}/{month} の entries[].id から取れます。

月テンプレート (毎月の支払いの予約) から自動で入った明細も、入ってしまえば普通の明細です。 金額が変わった家賃やサブスクは、この API でその月のぶんだけ直せます。

DELETE /v1/entries/{id}

明細を削除します。集計からも一覧からも消えます。

curl -X DELETE https://kakeibo-api.starhoshi.workers.dev/v1/entries/5f1c… \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN"

{ "ok": true }

存在しない id や、自分の家計簿にない id を指定すると 404 が返ります。 すでに削除済みの明細をもう一度消した場合も 404 です。

GET /v1/months/{year}/{month}

その月の明細と集計です。GET /v1/months/2026/8 のように指定します。

curl https://kakeibo-api.starhoshi.workers.dev/v1/months/2026/8 \
  -H "Authorization: Bearer $UCHIKAKE_TOKEN"

{
  "year": 2026,
  "month": 8,
  "closed": null,
  "created": true,
  "entries": [
    {
      "id": "…",
      "type": "expense",
      "date": "2026-08-12",
      "postedMonth": "2026-08",
      "categoryId": "…",
      "incomeSourceId": null,
      "payerId": "…",
      "memo": "コンビニ",
      "amount": 842,
      "createdBy": "…"
    }
  ],
  "summary": {
    "incomeTotal": 620000,
    "expenseTotal": 174765,
    "categoryTotals": [{ "categoryId": "…", "total": 5160 }],
    "payerTotals": [{ "payerId": "…", "total": 2122 }],
    "payerBalanceTotals": [{ "payerId": "…", "total": 388878 }],
    "incomeSourceTotals": [{ "incomeSourceId": "…", "total": 391000 }]
  }
}

• 明細は追加した順で返ります。並べ替えは呼び出し側で行ってください。
• amount が null の明細は「金額未入力」です。0 円とは別物です。
• 内訳の categoryId / payerId / incomeSourceId が null の行は「未設定」ぶんの合計です。内訳の合計は総額と一致します。
• closed が入っている月は締め済みですが、書き込みは拒否されません (目印として記録されているだけです)。
• 無料プランで当月・前月・前々月より前を指定すると 403 premium_required になります。

4. エラー

本文は { "error": "invalid_amount", "message": "金額は整数で指定してください。" } の形です。

5. AI クライアントから使う

Claude Code のようなツールには、トークンと、このページの内容を渡せばそのまま使えます。たとえば次のように頼めます。

ウチかけ API (https://uchikake.web.app/api.html) を使って、
今月の食費の合計を教えて。トークンは環境変数 UCHIKAKE_TOKEN にある。