API v1リファレンス

概要

Manilo APIは、iOSアプリで使っているのと同じ台帳 — 口座、カテゴリ、予算、共有グループ、トランザクション — をプログラムから操作するためのJSON REST APIです。インポーターやエクスポーター、同期ブリッジ、ダッシュボードの構築や、独自の自動化の実装に利用できます。

• ベースURL: https://api.manilo.app（以前のベースURL api.ledgy.app も引き続き利用できます）
• バージョンプレフィックス: このドキュメントのすべてのエンドポイントは /api/v1/ の下に配置されています。
• 通信: HTTPSのみ。HTTPでのリクエストは受け付けません。
• エンコーディング: リクエストとレスポンスのボディはJSON、文字コードはUTF-8。プロパティ名は camelCase です。
• 認証: Authorization: Bearer … をすべてのリクエストに付与します。
• Cloudサブスクリプション: すべてのv1エンドポイントで必要です。詳しくはサブスクリプション必須を参照してください。

クイックスタート

最初の認証済みリクエストまで、3ステップです。

1. パーソナルアクセストークンを発行する

1. ご自身のManiloダッシュボードにサインインし、設定 → API Access を開きます。
2. 「+ New token」をクリックします。
3. トークンにわかりやすい名前を付け（例:「Zapier — 週次エクスポート」）、必要なスコープを選びます（スコープを参照）。有効期限は任意で設定できます。
4. トークンをコピーします。表示されるのは一度きりです。トークンは接頭辞 lgpat_ と、それに続く16進数64文字で構成されます。

同じページには、有効なトークンが最終使用日時と権限の数とともに一覧表示されます。期限が近づくと「30日以内に期限切れ」の警告が出て、ゴミ箱アイコンからいつでも即座に失効させられます。1つのアカウントで同時に保持できる有効なトークンは、最大25個です。

2. リクエストを送る

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. レスポンスを確認する

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

認証

エンドポイント /api/v1/ へのすべてのリクエストには、Authorization ヘッダーが必要です。使用できるトークンは2種類です:

• パーソナルアクセストークン（PAT） — ダッシュボードの設定 → API Access ページで作成する、長期間有効なベアラートークンです。形式は lgpat_ + 16進数64文字。スコープを指定でき、いつでも失効させられ、有効期限も任意で設定できます。サードパーティ連携にはこちらを推奨します。
• セッションJWT — ファーストパーティのアプリ（iOS、ダッシュボード）に発行される短命のトークンです。スコープの制限はありません。サインイン済みのセッションから取り出せれば単発のテストに使えますが、正式にサポートされる方法はPATです。

ヘッダーの形式

Authorization: Bearer lgpat_a1b2c3d4e5f6…

トークンの上限

• 1つのManiloアカウントにつき、有効なPATは最大25個です。
• 作成時に有効期限を任意で設定できます。期限切れのトークンは 401 Unauthorized を返します。
• 失効させたトークンは、ただちに使えなくなります。Maniloが保存するのはトークンのSHA-256ハッシュだけで、値そのものは保存しません。そのため漏洩したトークンを復元することはできず、失効させて作り直すことになります。

よくある認証エラー

401

トークンがない、形式が不正、期限切れ、または失効しています。

403

トークンは有効ですが、リクエストしたエンドポイントに必要なスコープをPATが持っていないか、Cloudサブスクリプションが有効ではありません。

スコープ

PATはデフォルトで拒否のモデルに従います。トークンが呼び出せるのは、必要なスコープを保持しているエンドポイントだけで、それ以外はすべて 403 Forbidden を返します。連携に本当に必要な、最小限のスコープだけを付与してください。

利用できるスコープ:

以下の各エンドポイントには、必要なスコープが小さな紫色のチップで表示されます。スコープ :write は :read を含みません。両方必要な場合は、両方をリクエストしてください。

サブスクリプション必須

読み取り専用のものも含め、すべてのv1エンドポイントは、呼び出すユーザーに有効なManilo Cloudサブスクリプションがあることを前提とします。サブスクリプションが停止・期限切れになっている場合や、一度も開始されていない場合、APIは次のように応答します:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

レスポンスの X-Subscription-Required ヘッダーによって、サブスクリプションによるブロックと、一般的な権限エラーをクライアント側で区別できます。アクセスを回復するには、iOSアプリまたは dashboard.manilo.app/upgrade でCloudを再度有効にしてください。

エラー

エラーには標準のHTTPステータスコードを使用します。レスポンスボディは、フィールドが1つだけのJSONオブジェクトです:

{ "error": "Human-readable message" }

処理すべきステータスコード:

200

OK — リソース、または一覧を返しました。

201

Created — 新しいリソースを作成しました。レスポンスの Location ヘッダーが正規のURLを指します。

204

No Content — 削除に成功しました。ボディはありません。

400

検証に失敗しました — 必須フィールドの欠落、値が範囲外、JSONの形式が不正、など。

401

認証に失敗しました — 詳しくは認証を参照してください。

403

権限がありません — スコープが不足しているか、サブスクリプションが有効ではありません。

404

リソースが見つからないか、権限により参照できません。

409

競合が発生しました — 一意制約違反など。

5xx

サーバー側の障害です。冪等な読み取りであれば、指数バックオフを挟んで再試行して問題ありません。

ページネーションとフィルター

一覧系のエンドポイントは、既定では条件に一致するすべての項目を返します。件数が大きくなり得る唯一のリソースであるトランザクションは、カーソルベースのページネーションに対応しています。

トランザクションのカーソル

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

レスポンスには nextCursor が含まれます。これをクエリパラメータ cursor として渡すと、次のページを取得できます。レスポンスの nextCursor が null になったら、最後まで到達したことを意味します。

• limit — ページサイズ。範囲は 1..200 に丸められます。既定値は 50 です。
• cursor — 不透明なトークンです。中身は解釈せず、そのまま扱ってください。
• type, dateFrom, dateTo, categoryId, accountId, groupId — 任意のフィルターです。詳しくはトランザクションの一覧取得エンドポイントを参照してください。

型とフォーマット

• ID — 不透明な文字列です。解析せず、大文字と小文字を区別するUTF-8の識別子として扱ってください。
• タイムスタンプ — UTCのISO-8601形式で、末尾に Z が付きます。例: "2026-05-13T10:30:00Z"。
• 日付（トランザクションの date など） — 同じISO-8601の形式ですが、意味を持つのは日付の部分だけです。
• 金額 — JSONの数値で、単位は主単位、小数点以下は最大4桁です（例: 12.50）。補助単位は使いません。必ず currencyCode と組み合わせて扱われます。
• 通貨コード — ISO-4217に従い、大文字のアルファベットちょうど3文字です（例: "EUR", "USD", "GBP"）。
• 削除 — 削除の操作はすべて論理削除です。削除した項目は一覧や取得のレスポンスに現れなくなりますが、共有相手や過去のレシートはそのまま保持されます。
• 副作用 — 口座・カテゴリ・グループを削除しても、それに紐づくトランザクションは残り、参照だけが外れます。口座の削除エンドポイントでは、その動作を明示的に指定できます。

口座

口座は、残高を持つ入れ物です — 銀行口座、クレジットカード、現金の財布、証券口座など。すべてのトランザクションは、いずれか1つの口座（振替の場合は2つ）に紐づきます。

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

カテゴリ

カテゴリは、そのトランザクションが何のためのものか（食料品、家賃、フリーランス収入など）を表します。システムカテゴリは読み取り専用で全ユーザー共通、ユーザーカテゴリは自由に管理できます。カテゴリグループは、関連するカテゴリをまとめる単位です。

ユーザーカテゴリ

カテゴリグループ

予算

予算は、繰り返される期間ごとに、カテゴリ単位の支出（categoryId がnullの場合は台帳全体の支出）に上限を設けます。グループと共有するには groupId を設定します。

グループ

グループは共有の台帳です — 世帯、旅行、シェアハウスなど。メンバー全員が同じトランザクションを見られますが、所有権は各自のままです。メンバーの管理と招待はiOSアプリで行い、ここでのAPIが扱うのはリソースそのものです。

トランザクション

トランザクションは、台帳における動詞です。種類は4つ: income, expense, transfer（口座間の振替）、そして adjustment（残高の単発調整）です。基本のエンドポイントは収入と支出を作成し、振替には専用のエンドポイントがあります。大量のデータを扱うインポーター向けには、一括処理版も用意しています。

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

一括操作

インポーター向けの機能です。1バッチあたりの上限は100件で、動作はベストエフォートです。1行が不正でも、ほかの行までロールバックされることはありません。成功した項目と行ごとのエラーは分けて返されるため、失敗した分だけを再試行できます。

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

トランザクションオブジェクト

アイコン

Maniloには、口座・カテゴリ・グループのすべてで使われる、厳選されたアイコンセットとカラーパレットが用意されています。カタログは一度取得してキャッシュし、リソースを作成するときに識別子を使い回してください。

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

バージョニング

• v1内で破壊的変更はありません。追加するのは、新しいエンドポイント、任意指定の新しいフィールド、新しい列挙値だけです。フィールドの型やnull許容、必須かどうかが変わることはありません。
• 新しい列挙値は破壊的変更ではありません。未知の type, source、または action の値は、クラッシュさせるのではなく「表示しない」として扱ってください。プロダクトの成長に合わせて追加していきます。
• 破壊的な変更（もし必要になった場合）は /api/v2/ の下で提供し、少なくとも6か月の並行提供期間と、v1のレスポンスへの非推奨ヘッダーを伴います。

サポート

バグを見つけた、エンドポイントを追加してほしい、ドキュメントにない挙動に出会った — そんなときはヘルプセンターを開くか、support@manilo.app までメールでご連絡ください。問題を報告される際は、リクエストid（レスポンスヘッダー X-Request-Id に返されます）を添えていただけると助かります。

セキュリティに関わるご報告（トークンの漏洩、権限のバイパス、不正な読み取りなど）は、security@manilo.app までご連絡ください。