REST API 概要

いいかんじ™家計簿は、仕訳の起票・閲覧・削除、AI 証憑仕訳を操作できる REST API を提供しています。

ベース URL

https://your-server.example.com/api/v1

認証

すべての API リクエストに Authorization ヘッダーが必要です。

Authorization: Bearer <token>

トークンは 2 種類サポート:

API キー (ik_*)

サーバーの 設定 > API キー管理 から発行。スコープ単位で権限を選択。

OAuth Device Flow トークン (ikt_*)

RFC 8628 OAuth 2.0 Device Authorization Grant に対応。CLI / TUI / MCP サーバーなどブラウザを起動できないクライアントから利用可能。

1. クライアントが POST /oauth/device を呼び device_code / user_code / verification_uri_complete を取得
2. ユーザーは verification_uri_complete をブラウザで開き、ログインして 「全権限で承認」 または 「読み取り専用で承認」 を選択
3. クライアントは POST /oauth/token をポーリングしてアクセストークン (ikt_*) を取得

OAuth 2.1 (MCP クライアント)

MCP クライアント (Claude カスタムコネクタ等) 向けに、動的クライアント登録 (RFC 7591) + Authorization Code + PKCE (S256) に対応しています。 POST /oauth/register でクライアント登録 → GET /oauth/authorize で同意 (このとき付与するスコープを選択可能) → POST /oauth/token で authorization_code / refresh_token を交換、という流れです。 詳細は MCP サーバー を参照してください。

OAuth トークン (ikt_*) は付与されたスコープの範囲でのみ API を呼べます (スコープが未設定の従来トークンは全スコープ相当)。読み取り専用 で 承認したトークンは、書き込み系エンドポイント (POST /journals, DELETE /journals/:id, POST /ai/analyze, DELETE /ai/drafts/:id) を 呼ぶと 403 で拒否されます。

スコープ (API キーのみ)

API キー発行時にスコープ（権限）を選択します。

journals:delete は journals:read スコープを前提とします（削除対象を閲覧できる必要があるため）。

共通レスポンス形式

成功時

すべての成功レスポンスに "ok": true が含まれます。

{
  "ok": true,
  "id": 42,
  "entry_number": 15
}

エラー時

エラーレスポンスには "error" フィールドに日本語のメッセージが含まれます。

{
  "error": "date は必須です。"
}

エラーコード

ページネーション

一覧取得 API はページネーションに対応しています。

リクエストパラメータ:

レスポンス:

{
  "ok": true,
  "journals": [...],
  "total": 150,
  "page": 1,
  "per_page": 20
}

total は条件に合致する全件数です。

レート制限

制限を超えると 429 Too Many Requests が返ります。

エンドポイント一覧

仕訳 API

AI 証憑仕訳 API

証憑 API

レポート API