REST API 概要

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

ベース URL

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

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

Authorization: Bearer ik_xxxxxxx

API キーはサーバーの 設定 > API キー管理 から発行できます。キーは ik_ プレフィックスで始まります。

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

スコープ	説明	使えるエンドポイント
`journals:create`	仕訳起票	`POST /journals`
`journals:read`	仕訳閲覧	`GET /journals`, `GET /journals/:id`
`journals:delete`	仕訳削除	`DELETE /journals/:id`
`ai:analyze`	AI 証憑仕訳	`POST /ai/analyze`, `GET/DELETE /ai/drafts`

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

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

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

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

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

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

リクエストパラメータ:

パラメータ	デフォルト	上限	説明
`page`	1	—	ページ番号
`per_page`	20 or 50	100	1ページあたりの件数

レスポンス:

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

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

エンドポイント	制限
`POST /api/v1/ai/analyze`	30 リクエスト / 時間
その他	制限なし

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