freee Developer API ガイド

概要

freee株式会社が提供するクラウドバックオフィスサービスのPublic APIプラットフォーム。5つのAPIで会計・人事労務・請求書・工数管理・販売を操作できる。

API別ベースURL・レート制限

重要: 各APIのベースURLが異なる。会計は直接 /api/1/、その他は /hr、/iv、/pm、/sm がプレフィックスとして付く。

核心ルール

1. company_idが大半の事業所スコープAPIで必須 — 最初に GET /api/1/companies で事業所一覧を取得しcompany_idを保持する。例外: /companies, /users/me, OAuth系は不要
2. マスタ同期 → トランザクション操作の順序 — 取引先・勘定科目・税区分・部門・品目のマスタIDを先に同期してから、取引(deals)作成等を行う
3. アクセストークン有効期限: 6時間（21,600秒） — 期限切れは expired_access_token エラーコードで通知
4. リフレッシュトークン有効期限: 90日、1回使い切り — リフレッシュ時に新しいトークンペアが発行される。古いリフレッシュトークンは即座に無効化されるため、新しいものを必ず保存すること
5. 公式SDKは定期メンテナンス終了（2023-2024年） — C#/Java/PHP/JavaScriptの公式SDKはメンテナンス終了・一部アーカイブ済み。OpenAPI Generatorでクライアントコードを自動生成するか、freee MCPサーバーを使用する
6. レート制限は事業所単位 — 一般: 300 req/min、HR: 10,000 req/hour。超過時は429または403応答
7. プラン別機能制限あり — フリープランでは仕訳帳API等が利用不可。freee_plan_limit エラーで通知
8. 後方互換ポリシー: 新フィールド・新エンドポイントは予告なし追加 — レスポンスの未知プロパティを無視する設計にすること
9. stateパラメータ必須（CSRF対策） — OAuth認可リクエストに必ずランダム文字列を含め、コールバック時に検証する
10. HTTPS必須 — HTTPアクセスは不可。APIベースURL https://api.freee.co.jp/ のみ

認証（OAuth 2.0）

フロー概要

1. ユーザーを認可URLにリダイレクト（prompt=select_company推奨）
2. ユーザーがfreeeにログイン → 事業所選択 → 権限承認
3. コールバックURLに認可コード（code）が返却
4. 認可コードをアクセストークン + リフレッシュトークンに交換
5. アクセストークンでAPI呼び出し
6. 期限切れ時はリフレッシュトークンで更新（新しいペアを必ず保存）

エンドポイント

認可URLパラメータ

スコープ

read, write, default_read — アプリ作成時に設定。変更時は全トークン破棄→再認可が必要。

トークン有効期限

ローカルテスト

コールバックURLに urn:ietf:wg:oauth:2.0:oob を指定すると、認可コードがブラウザに表示される。

curl例: トークン取得

curl -X POST "https://accounts.secure.freee.co.jp/public_api/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "code=${AUTH_CODE}" \
  -d "redirect_uri=${REDIRECT_URI}"

curl例: トークンリフレッシュ

curl -X POST "https://accounts.secure.freee.co.jp/public_api/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "refresh_token=${REFRESH_TOKEN}"

→ 詳細実装パターン（Next.js API Route、TypeScript）: references/oauth-flow.md

5 API エンドポイント概要

会計API（Accounting）

パスプレフィックス: /api/1/

→ 全エンドポイント詳細・パラメータ・連携パターン: references/accounting-api.md

人事労務API（HR）

パスプレフィックス: /hr/api/v1/、APIバージョン: 2022-02-01

認可レベル: company_admin（他従業員データ）、self_only（本人のみ）

→ 全エンドポイント詳細: references/hr-api.md

請求書API（Invoice）

工数管理API（Project Management）

販売API（Sales Management）

→ 請求書・工数・販売API詳細: references/invoice-pm-sales-api.md

レート制限

API別の詳細なレート制限は「API別ベースURL・レート制限」テーブルを参照。

レート制限は事業所単位で適用される。同一事業所に対する複数アプリからのリクエストが合算される点に注意。

HR APIレート制限ヘッダー

X-RateLimit-Limit: 10000       # 最大リクエスト数
X-RateLimit-Remaining: 9500    # 残りリクエスト数
X-RateLimit-Reset: 1700000000  # リセット時刻（Unix timestamp）

超過時の対応

• 会計API: HTTP 400（レート制限超過メッセージ）
• HR API: HTTP 429 → リトライ、過度のアクセスで HTTP 403 + 10分間クールダウン
• リトライ: 指数バックオフ推奨（1s → 2s → 4s）
• 並列実行時はスレッド数を制限（逐次実行では通常超過しない）

エラーハンドリング

HTTPステータスコード

401エラーサブコード

エラーレスポンス形式

{
  "status_code": 401,
  "errors": [
    {
      "type": "status",
      "messages": ["Permission denied"],
      "codes": ["user_do_not_have_permission"]
    }
  ]
}

注意: エラーメッセージは変更される可能性がある。codes フィールドで判定すること。新しいエラーコードも予告なく追加されるため、未知コードの汎用ハンドリングも実装すること。

TypeScript: トークン自動リフレッシュパターン

interface FreeeTokenSet {
  access_token: string;
  refresh_token: string;
  expires_at: number; // Unix timestamp
  company_id: string;
}

// ユーザー単位の排他制御（同一ユーザーの並行リフレッシュ防止）
const refreshLocks = new Map<string, Promise<FreeeTokenSet>>();

async function getValidToken(userId: string): Promise<FreeeTokenSet> {
  const token = await loadTokenFromDb(userId);
  if (Date.now() / 1000 <= token.expires_at - 300) return token;

  let lock = refreshLocks.get(userId);
  if (!lock) {
    lock = refreshFreeeToken(userId, token).finally(() => {
      refreshLocks.delete(userId);
    });
    refreshLocks.set(userId, lock);
  }
  return await lock;
}

async function freeeApiFetch<T>(
  url: string, userId: string, init: RequestInit = {}
): Promise<T | undefined> {
  const token = await getValidToken(userId);
  const headers = new Headers(init.headers);
  headers.set('Authorization', `Bearer ${token.access_token}`);
  headers.set('Accept', 'application/json');
  if (init.body && !headers.has('Content-Type')) {
    headers.set('Content-Type', 'application/json');
  }
  const res = await fetch(url, { ...init, headers });
  if (res.status === 204) return undefined;     // DELETE成功等
  if (res.status === 401) {
    const body = await res.json();
    if (body.errors?.[0]?.codes?.includes('expired_access_token')) {
      // 排他制御付きリフレッシュ後にリトライ
      const newToken = await getValidToken(userId);
      headers.set('Authorization', `Bearer ${newToken.access_token}`);
      const retry = await fetch(url, { ...init, headers });
      if (retry.status === 204) return undefined;
      if (!retry.ok) throw await retry.json();
      return (await retry.json()) as T;
    }
    throw new Error(`freee API error: ${JSON.stringify(body)}`);
  }
  if (!res.ok) throw await res.json();
  return (await res.json()) as T;
}

Webhook（Beta）

会計API Webhook

HR API Webhook

検証

リクエストヘッダー x-freee-token の値を、アプリのWebhook設定で表示される検証トークンと照合する。

制限事項（Beta）

• エラーログ未提供
• API経由のCRUD操作は通知対象外（Web画面操作のみ）
• HR: 一括インポート、退職処理は通知対象外
• ドメインホワイトリスト: egw.freee.co.jp の許可が必要

→ Webhook実装詳細・検証コード: references/webhook-setup.md

Developer Portal セットアップ

freeeアプリ作成・環境変数設定・コールバックURL登録・トラブルシューティングの完全ガイド。

→ 初回セットアップ・トラブルシューティング: references/developer-portal-setup.md

開発ツール

freee MCP Server（推奨）

Claude Desktop/Codeからfreee APIを直接操作できるMCPサーバー。5つのAPI全対応、72のリファレンスファイル。

# セットアップ
npx freee-mcp configure

# Claude Codeプラグイン
claude plugin install freee/freee-mcp

• OAuth 2.0 + PKCE認証（自動トークンリフレッシュ）
• GitHub: https://github.com/freee/freee-mcp
• Discord: https://discord.gg/9ddTPGyxPw

OpenAPI Generator（クライアントコード自動生成）

公式SDKは全てARCHIVED。OpenAPI Generatorで任意言語のクライアントコードを生成する。

# TypeScriptクライアント生成例
docker run --rm -v "${PWD}:/local" \
  openapitools/openapi-generator-cli:v5.4.0 generate \
  -i https://raw.githubusercontent.com/freee/freee-api-schema/master/v2020_06_15/open-api-3/api-schema.json \
  -g typescript-fetch \
  -o /local/freee-client

OpenAPIスキーマURL

ベースURL: https://raw.githubusercontent.com/freee/freee-api-schema/master/

アプリ種別

アプリ審査

• 所要時間: 約1-2週間
• アプリ名に "for freee" / "by freee" 使用禁止
• 事業所選択機能の実装必須（prompt=select_company）
• 最小権限の原則
• 権限追加時: 全アクセストークンが破棄される → ユーザーの再認可が必要

クイックスタート

1. 事業所一覧取得（company_id確認）

curl -s "https://api.freee.co.jp/api/1/companies" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

2. 取引先一覧取得

curl -s "https://api.freee.co.jp/api/1/partners?company_id=${COMPANY_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

3. HR: 従業員一覧取得

curl -s "https://api.freee.co.jp/hr/api/v1/companies/${COMPANY_ID}/employees" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

4. 取引（支出）作成

curl -X POST "https://api.freee.co.jp/api/1/deals" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": '"${COMPANY_ID}"',
    "issue_date": "2026-03-26",
    "type": "expense",
    "details": [{
      "account_item_id": 101,
      "tax_code": 2,
      "amount": 10000,
      "description": "テスト取引"
    }]
  }'

チェックリスト

API呼び出し前

• company_idを取得・保持しているか
• マスタデータ（取引先・勘定科目・税区分）を同期済みか
• アクセストークンの有効期限を確認しているか
• HTTPSでリクエストしているか
• Content-Type: application/json を設定しているか

レスポンス処理

• 未知のJSONプロパティを無視する設計か（後方互換）
• 401エラー時にサブコード（codes）で分岐しているか
• レート制限超過時のリトライ（指数バックオフ）を実装しているか
• ページネーションを考慮しているか（offset, limit）

トークン管理

• リフレッシュ時に新しいリフレッシュトークンを保存しているか
• stateパラメータでCSRF対策しているか
• トークンをログや画面に露出させていないか
• リフレッシュトークン期限（90日）の管理・再認可フローがあるか

トラブルシューティング

Q: 401 expired_access_token が頻発する

A: アクセストークンは6時間で期限切れ。リフレッシュトークンでプロアクティブに更新する（期限の5分前など）。

Q: 401 invalid_grant でリフレッシュが失敗する

A: リフレッシュトークンは1回使い切り。同一トークンを複数回使用すると失敗する。並行リクエスト時はトークンリフレッシュの排他制御が必要。

Q: 401 re_authorization_required が返る

A: アプリの権限（スコープ）を変更した場合、全トークンが無効化される。ユーザーに再認可フローを案内する。

Q: 429/403でレート制限に引っかかる

A: HR APIは403 + 10分間クールダウンの場合がある。X-RateLimit-Remaining ヘッダーを監視し、残り少なくなったら待機する。

Q: freee_plan_limit エラーが返る

A: フリープランでは仕訳帳API等が利用不可。ユーザーのプランを確認し、利用可能なエンドポイントのみ呼び出す。

Q: レスポンスに新しいフィールドが突然現れた

A: 正常動作。freeeは後方互換として新フィールドを予告なく追加する。未知プロパティを無視する設計にすること。

詳細リファレンス

• references/oauth-flow.md — OAuth 2.0認証フロー完全実装（Next.js API Route、トークンローテーション、事業所選択、OOBフロー）
• references/accounting-api.md — 会計API全31+エンドポイント詳細（パラメータ、マスタ同期、経費精算ワークフロー、インボイス制度）
• references/hr-api.md — 人事労務API全エンドポイント詳細（従業員CRUD、勤怠、打刻、認可レベル）
• references/invoice-pm-sales-api.md — 請求書・工数管理・販売API詳細（請求書移行注意、プロジェクト収支、販売マスタ）
• references/webhook-setup.md — Webhook設定・検証実装（イベント一覧、ペイロード形式、TypeScript検証コード）

動的読み込みルール: references/ 配下のファイルは起動時に一括読み込みしない。必要に応じて該当ファイルのみ読み込むこと。

関連スキル

関連リソース

最近の変更（2025-2026）

改訂履歴