# マージブル API — あなたの AI への接続案内 これは「マージブル(編集できる家計簿)」の API です。窓口はあなた(AI)です。 利用者が「家計簿を使いたい」と言ったら、登録から始めてください。 ## 1. 登録(利用者ごと、最初の1回だけ) POST https://kakeibo.mergeble.com/api/v1/register Body: {"name": "利用者の表示名"} レスポンスに api_token が一度だけ返ります。これがこの利用者専用の鍵です。 Muse の安全な API 登録フローで登録してください (ホスト: kakeibo.mergeble.com、認証: Bearer ヘッダー)。 鍵はチャット本文に貼らないでください。 ## 2. 人間用のログインリンク(PWA) 利用者は PWA(https://kakeibo.mergeble.com/app)からも見られます。 ログインはパスワードではなく、あなたが発行する使い捨てリンクです。 POST /api/v1/login-links (Bearer 認証) → {"url": "https://.../auth?code=...", "expires_at": ...} リンクは24時間有効・1回限り。発行したら利用者に渡してください。 セッションは30日続きます。切れたら新しいリンクを発行してください。 ## 2.5 端末コードの承認(PWA ログイン) 利用者が PWA のログイン画面でコードを表示すると、6文字のコードが出ます。 利用者からそのコードを聞いたら、あなたの鍵で承認してください。 POST /api/v1/device-codes/claim (Bearer 認証) Body: {"code": "ABC123"} 承認すると、利用者のブラウザがそのままログイン状態になります(セッション30日)。 ## 3. データ API(ベース: https://kakeibo.mergeble.com/api/v1) すべての呼び出しに `Authorization: Bearer ` を付けます。 鍵はその利用者のデータにだけ効きます。他人のデータは見えません。 - GET /data 全データと集計(summary)を取得(書き出しもこれ) - POST /transactions 明細を1件追加 {date, time, store, item, tax, amount, payment, category, page} - DELETE /transactions/{no} 明細を削除 - POST /debts 負債を追加/更新(lender と scope で照合) {lender, balance, monthly, status, scope: "personal"|"corporate", jul26} - POST /balances 残高を追加/更新(label で照合){label, amount, note} - POST /cashflow 月の収支モデルを全行で置き換え {rows: [{item, yen}]} - POST /deadlines 期限を追加 {due, label, amount, status} - DELETE /deadlines/{rowid} 期限を削除 ## 4. 鍵とアカウントの管理 - GET /tokens 自分の鍵の一覧(名前・発行日・最終使用・状態) - POST /tokens 鍵を追加発行 {name}(表示は一度だけ) - DELETE /tokens/{id} 鍵を失効 - DELETE /account アカウントと全データを完全に削除 Body: {"confirm": "delete"} — 利用者の明示の意思を確認してから実行すること ## 注意 - 簡易な HTTP クライアント(Python の urllib 等、既定の User-Agent)だと Cloudflare の bot 判定で 403 (error 1010) になることがある。 その場合は通常のブラウザ系 User-Agent を付けて呼び出すこと。 - 登録 API の乱用は制限されています(IP ごとの回数制限)。 ## 運用ルール - 合計は必ず行データから計算する。集計値を直接書かない。 - マネーフォワード等で残高が変わったら、/balances で該当行を更新する。 - 明細の追加は1件ずつ POST する。重複登録に注意する。 - 利用者への見せ方(表・グラフ・文書)は、あなたがデータから作るか、 PWA(/app)を案内すること。