Freee Api Skill

name: freee-api-skill version: 0.29.0 description: freee の会計・人事労務・請求書・工数管理・販売・サイン（電子契約）API と連携するスキル。API リファレンスと操作レシピを提供し、freee-mcp / freee-sign-mcp 経由で正確な API 利用をガイドする。

{ "skill_name": "freee-api-skill", "evals": [ { "id": 1, "prompt": "今月の経費申請を一覧で見せて\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "recipes/expense-application-operations.md を参照した上で、freee_get_current_company → freee_api_get (service=accounting, path=/api/1/expense_applications) の手順を説明する。", "assertions": [ "freee_get_current_company を最初に呼び出す手順を説明している", "recipes/expense-application-operations.md を実際に参照している", "freee_api_get を service=accounting、path=/api/1/expense_applications で呼び出す計画を示している", "company_id パラメータが必要であることに言及している", "MCPツール（freee_api_get 等）を実際には呼び出していない" ] }, { "id": 2, "prompt": "先月の売上を勘定科目別に教えて\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "references/ から試算表のリファレンスを検索・参照し、freee_get_current_company → freee_api_get (試算表API) の手順を説明する。", "assertions": [ "freee_get_current_company を最初に呼び出す手順を説明している", "references/ 内のリファレンスを実際に検索・参照している", "試算表関連のAPIパス（/api/1/reports/trial_pl 等）を使用する計画を示している", "未承認仕訳（approval_flow_status）についてユーザーに確認する手順を含んでいる", "期間パラメータ（start_date, end_date 等）に先月の日付を指定する計画を示している", "MCPツール（freee_api_get 等）を実際には呼び出していない" ] }, { "id": 3, "prompt": "freee に出勤を打刻して\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "recipes/hr-attendance-operations.md を参照した上で、freee_get_current_company → freee_api_post (service=hr, 打刻API) の手順を説明する。", "assertions": [ "freee_get_current_company を最初に呼び出す手順を説明している", "recipes/ または references/ 内の勤怠関連ファイルを実際に参照している", "freee_api_post を service=hr で呼び出す計画を示している", "打刻タイプとして clock_in（出勤）を指定する計画を示している", "従業員IDの取得手順（/api/v1/users/me 等）を説明している", "打刻可能種別の事前確認（available_types）に言及している", "MCPツール（freee_api_post 等）を実際には呼び出していない" ] }, { "id": 4, "prompt": "取引先「テスト株式会社」に対して、税込11,000円の支出取引を登録したい。勘定科目は消耗品費で。\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "recipes/deal-operations.md を参照し、freee_get_current_company → 取引先検索 → 勘定科目検索 → freee_api_post (path=/api/1/deals, type=expense) の手順を説明する。", "assertions": [ "freee_get_current_company を最初に呼び出す手順を説明している", "recipes/deal-operations.md を実際に参照している", "取引先を検索するAPI（/api/1/partners 等）を呼び出す手順を説明している", "勘定科目を検索するAPI（/api/1/account_items 等）を呼び出す手順を説明している", "freee_api_post を service=accounting、path=/api/1/deals で呼び出す計画を示している", "type を expense（支出）に設定する計画を示している", "MCPツール（freee_api_post 等）を実際には呼び出していない" ] }, { "id": 5, "prompt": "請求書を新しく作りたいんだけど、どうすればいい？\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "recipes/invoice-operations.md を参照し、請求書作成の手順とパラメータを説明する。必要な情報（取引先、品目、金額等）をユーザーに確認する。", "assertions": [ "recipes/invoice-operations.md を実際に参照している", "請求書作成に必要なパラメータや手順を説明している", "請求書APIのパスとして /invoices（invoice サービス）を使用する計画を示している（会計APIの /api/1/invoices ではない）", "必要な情報をユーザーに確認している（取引先、品目、金額など）", "いきなりAPIを呼ぶ計画ではなく、まず情報を整理している", "MCPツールを実際には呼び出していない" ] }, { "id": 6, "prompt": "従業員の一覧を取得して\n\n注意: これはドライランです。実際にMCPツールは呼び出さず、どのツールをどのパラメータで呼び出すべきかを手順として説明してください。レシピやリファレンスの参照は実際に行ってください。", "expected_output": "freee_get_current_company → freee_api_get (service=hr, path=/api/v1/employees) の手順を説明する。", "assertions": [ "freee_get_current_company を最初に呼び出す手順を説明している", "freee_api_get を service=hr で呼び出す計画を示している",

取引（収入・支出）の操作

freee会計APIを使った取引の登録・検索ガイド。

概要

取引APIを使って収入・支出の記録、検索、更新を行います。

利用可能なパス

取引作成の前準備

取引を作成するには、事業所固有のマスタID（勘定科目ID、税区分コード、口座ID等）が必要になる。これらのIDは事業所ごとに異なるため、推測やハードコードせず、必ず事前にAPIで取得すること。

1. 勘定科目IDを取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/account_items"
}

レスポンスの account_items から目的の勘定科目（例: 「消耗品費」「旅費交通費」）の id を使用する。

2. 税区分コードを取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/taxes"
}

3. 口座IDを取得（決済済み取引の場合）

freee_api_get {
  "service": "accounting",
  "path": "/api/1/walletables",
  "query": { "type": "wallet" }
}

使用例

取引一覧を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/deals",
  "query": {
    "limit": 10
  }
}

期間で絞り込み

freee_api_get {
  "service": "accounting",
  "path": "/api/1/deals",
  "query": {
    "start_issue_date": "2025-01-01",
    "end_issue_date": "2025-01-31",
    "type": "expense"
  }
}

支出を作成（未決済）

account_item_id、tax_code は上記の前準備で取得した実際の値を使用すること。

freee_api_post {
  "service": "accounting",
  "path": "/api/1/deals",
  "body": {
    "company_id": 123456,
    "issue_date": "2025-01-15",
    "type": "expense",
    "details": [
      {
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 10000,
        "description": "消耗品購入",
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

支出を作成（決済済み）

freee_api_post {
  "service": "accounting",
  "path": "/api/1/deals",
  "body": {
    "company_id": 123456,
    "issue_date": "2025-01-15",
    "type": "expense",
    "details": [
      {
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 10000,
        "description": "消耗品購入",
        "tag_ids": [TAG_ID]
      }
    ],
    "payments": [
      {
        "amount": 10000,
        "from_walletable_type": "wallet",
        "from_walletable_id": <取得した口座ID>,
        "date": "2025-01-15"
      }
    ]
  }
}

Tips

メモタグ「freee-mcp」の付与

取引を作成する際は、freee-mcp 経由で作成したデータであることを識別できるよう、メモタグ「freee-mcp」を必ず付与すること。手順は recipes/freee-mcp-tag.md を参照。取引では details[].tag_ids にタグIDを指定する。

作成後のWeb確認URL

取引を作成した後、以下のURLでWeb画面から確認できます:

https://secure.freee.co.jp/deals#deal_id={id}

{id} は API レスポンスで返される取引ID（deal.id）を使用します。

リファレンス

詳細なAPIパラメータ（収支区分、決済状況、口座区分等）は references/accounting-deals.md を参照。

経費申請の操作

freee会計APIを使った経費申請のガイド。

概要

経費精算APIを使って経費申請の作成・取得・承認操作を行います。

利用可能なパス

取得前の注意

経費申請の作成に必要な経費科目ID（expense_application_line_template_id）は事業所ごとに異なる。推測せず、必ず事前にAPIで取得すること。

freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_application_line_templates"
}

使用例

経費申請一覧を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_applications",
  "query": {
    "limit": 10
  }
}

経費申請を作成

freee_api_post {
  "service": "accounting",
  "path": "/api/1/expense_applications",
  "body": {
    "company_id": 123456,
    "title": "交通費",
    "issue_date": "2025-01-15",
    "tag_ids": [TAG_ID],
    "expense_application_lines": [
      {
        "transaction_date": "2025-01-15",
        "description": "新宿→渋谷",
        "amount": 400
      }
    ]
  }
}

経費科目一覧を取得

経費申請作成時に使用する経費科目IDを確認:

freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_application_line_templates"
}

Tips

メモタグ「freee-mcp」の付与

経費申請を作成する際は、freee-mcp 経由で作成したデータであることを識別できるよう、メモタグ「freee-mcp」を必ず付与すること。手順は recipes/freee-mcp-tag.md を参照。経費申請では tag_ids にタグIDを指定する。

作成後のWeb確認URL

経費申請を作成した後、以下のURLでWeb画面から確認できます:

https://secure.freee.co.jp/expense_applications/{id}

{id} は API レスポンスで返される経費申請ID（expense_application.id）を使用します。

注意点

• 申請経路に部門役職データ連携を使用している経費申請はAPI経由で作成・更新できません
• 申請の削除は下書き・差戻し状態の場合のみ可能
• 領収書添付が必要な場合はファイルボックスAPIと連携

リファレンス

詳細なAPIパラメータは references/accounting-expense-applications.md を参照。

メモタグ「freee-mcp」の付与ガイド

freee-mcp 経由で作成したデータを識別するため、メモタグ「freee-mcp」を付与する手順。

手順

1. メモタグ一覧から「freee-mcp」のIDを取得:

freee_api_get {
  "service": "accounting",
  "path": "/api/1/tags"
}

レスポンスの tags 配列から name が freee-mcp のものを探し、id を取得します。

2. 存在しない場合は作成:

freee_api_post {
  "service": "accounting",
  "path": "/api/1/tags",
  "body": {
    "company_id": 123456,
    "name": "freee-mcp"
  }
}

3. 取得したタグIDをリクエストボディの tag_ids フィールドに指定してデータを作成します。

各APIでの指定箇所

勤怠の操作

freee人事労務APIを使った勤怠管理ガイド。

利用可能なパス

使用例

勤怠記録を取得

freee_api_get {
  "service": "hr",
  "path": "/api/v1/employees/{employee_id}/work_records/2025-01-15",
  "query": { "company_id": 123456 }
}

is_editable: true であれば更新可能です。

打刻を登録

freee_api_post {
  "service": "hr",
  "path": "/api/v1/employees/{employee_id}/time_clocks",
  "body": {
    "company_id": 123456,
    "type": "clock_in",
    "datetime": "2025-01-15T09:00:00+09:00"
  }
}

出退勤時刻と休憩時間を登録・更新

work_record_segments で出退勤時刻、break_records で休憩時間を指定します。

freee_api_put {
  "service": "hr",
  "path": "/api/v1/employees/{employee_id}/work_records/2025-01-15",
  "body": {
    "company_id": 123456,
    "work_record_segments": [
      {
        "clock_in_at": "2025-01-15 10:40:00",
        "clock_out_at": "2025-01-15 20:15:00"
      }
    ],
    "break_records": [
      {
        "clock_in_at": "2025-01-15 12:00:00",
        "clock_out_at": "2025-01-15 13:00:00"
      }
    ]
  }
}

• 時刻はJST（+09:00）として扱われる（タイムゾーン省略可）
• break_records を空配列にすると休憩なしになる
• 複数回の出退勤がある場合は work_record_segments に複数要素を指定する
• 既に登録済みの勤怠も同じAPIで上書き更新できる

Tips

self_only 権限について

/api/v1/employees は管理者権限が必要ですが、/api/v1/users/me で自分の employee_id を取得すれば、自分の勤怠は操作可能です。

freee_api_get {
  "service": "hr",
  "path": "/api/v1/users/me"
}

レスポンスの companies[].employee_id が自分の従業員IDです。

リファレンス

• references/hr-attendances.md - 勤怠API詳細
• references/hr-time-clocks.md - 打刻API詳細

従業員・給与の操作

freee人事労務APIを使った従業員・勤怠管理ガイド。

概要

人事労務APIを使って従業員情報の取得、勤怠データの管理を行います。

利用可能なパス

従業員関連

給与関連

使用例

従業員一覧を取得

対象年月を指定して取得:

freee_api_get {
  "service": "hr",
  "path": "/api/v1/employees",
  "query": {
    "year": 2025,
    "month": 1
  }
}

全期間の従業員一覧を取得

退職者も含めて取得:

freee_api_get {
  "service": "hr",
  "path": "/api/v1/companies/123456/employees"
}

給与明細一覧を取得

freee_api_get {
  "service": "hr",
  "path": "/api/v1/payroll_statements",
  "query": {
    "year": 2025,
    "month": 1
  }
}

Tips

作成後のWeb確認URL

人事労務の各画面は以下のURLで確認できます:

翌月払いの従業員情報取得

締め日支払い日設定が翌月払いの場合、指定month + 1の従業員情報が返されます。

例: 2025年1月の情報を取得する場合

freee_api_get {
  "service": "hr",
  "path": "/api/v1/employees",
  "query": {
    "year": 2024,
    "month": 12
  }
}

注意点

• 管理者権限を持ったユーザーのみ実行可能なAPIが多い
• 指定年月に退職済みのユーザーは /api/v1/employees では取得できない
• 全期間取得が必要な場合は /api/v1/companies/{company_id}/employees を使用

リファレンス

詳細なAPIパラメータは以下を参照:

• references/hr-employees.md - 従業員
• references/hr-payroll-statements.md - 給与明細

請求書・見積書・納品書・領収書・発注書の操作

freee請求書APIを使った帳票操作のガイド。

概要

請求書 API は https://api.freee.co.jp/iv をベースとした独立した API です。

注意: 会計 API の /api/1/invoices は過去の API であり、現在は請求書 API (service: "invoice") を使用してください。

利用可能なパス

注意: company_id は必須

請求書APIの一覧取得（GET）では、クエリパラメータに company_id が必須です。省略すると認証エラーになります。 作成（POST）でもリクエストボディに company_id が必須です。

使用例

請求書一覧を取得:

freee_api_get {
  "service": "invoice",
  "path": "/invoices",
  "query": { "company_id": 123456 }
}

請求書を作成:

freee_api_post {
  "service": "invoice",
  "path": "/invoices",
  "body": {
    "company_id": 123456,
    "billing_date": "2025-01-15",
    "partner_id": 789,
    "partner_title": "御中",
    "tax_entry_method": "out",
    "tax_fraction": "omit",
    "withholding_tax_entry_method": "out",
    "lines": [
      {
        "description": "コンサルティング費用",
        "quantity": 1,
        "unit_price": "100000",
        "tax_rate": 10,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

領収書を作成:

freee_api_post {
  "service": "invoice",
  "path": "/receipts",
  "body": {
    "company_id": 123456,
    "receipt_date": "2025-01-15",
    "partner_id": 789,
    "partner_title": "御中",
    "tax_entry_method": "out",
    "tax_fraction": "omit",
    "withholding_tax_entry_method": "out",
    "lines": [
      {
        "description": "商品代金",
        "quantity": 1,
        "unit_price": "100000",
        "tax_rate": 10,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

領収書では receipt_date（領収日）が必須です。receipt_number（領収書番号）は採番設定が[自動採番する]以外の場合に必須です。

発注書を作成:

freee_api_post {
  "service": "invoice",
  "path": "/purchase_orders",
  "body": {
    "company_id": 123456,
    "purchase_order_date": "2025-01-15",
    "partner_id": 789,
    "partner_title": "御中",
    "tax_entry_method": "out",
    "tax_fraction": "omit",
    "withholding_tax_entry_method": "out",
    "lines": [
      {
        "description": "外注費",
        "quantity": 1,
        "unit_price": "100000",
        "tax_rate": 10,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

発注書では purchase_order_date（発注日）が必須です。purchase_order_number（発注書番号）は採番設定が[自動採番する]以外の場合に必須、collects_on（支払予定日）等の発注書固有項目も指定できます。

帳票の取消・復元

請求書・見積書・納品書・領収書・発注書は、削除ではなく取消（cancel）/復元（uncancel）が可能です。いずれも PUT メソッドで、リクエストボディに company_id が必須です。

請求書を取消:

freee_api_put {
  "service": "invoice",
  "path": "/invoices/49034614/cancel",
  "body": { "company_id": 123456 }
}

取消した請求書を復元:

freee_api_put {
  "service": "invoice",
  "path": "/invoices/49034614/uncancel",
  "body": { "company_id": 123456 }
}

取消・復元の結果はレスポンスの cancel_status（canceled: 取消済み、uncanceled: 取消されていない）で確認できます。

注意: 取消すると、取引が紐づいている帳票（請求書・納品書・領収書・発注書）では取引も削除されます。見積書は取引が紐づかないため取引削除はありません。

見積書・納品書・領収書・発注書も同様に /{帳票パス}/{id}/cancel および /{帳票パス}/{id}/uncancel で取消・復元できます。

Tips

メモタグ「freee-mcp」の付与

請求書・見積書・納品書・領収書・発注書を作成する際は、freee-mcp 経由で作成したデータであることを識別できるよう、メモタグ「freee-mcp」を必ず付与すること。手順は recipes/freee-mcp-tag.md を参照。lines[].tag_ids にタグIDを指定する。

作成後のWeb確認URL

請求書・見積書・納品書・領収書・発注書を作成・更新した後、以下のURLでWeb画面から確認できます:

レスポンスの report_url フィールドにも帳票詳細ページのURLが含まれます。

{id} は API レスポンスで返されるID（invoice.idなど）を使用します。

例: 請求書ID 49034614 の場合

https://invoice.secure.freee.co.jp/reports/invoices/49034614

作成完了時にこのURLをユーザーに提示すると、すぐにWeb画面で内容を確認できます。

リファレンス

詳細なAPIパラメータは以下を参照:

• references/invoice-invoices.md - 請求書API
• references/invoice-quotations.md - 見積書API
• references/invoice-delivery-slips.md - 納品書API
• references/invoice-receipts.md - 領収書API
• references/invoice-purchase-orders.md - 発注書API

IT管理の操作

freeeIT管理APIを使った SaaSアカウント・備品・メンバー管理ガイド。

各リソースの詳細なエンドポイント仕様は以下のリファレンスを参照。

• references/it-management-members.md - メンバー
• references/it-management-application-account.md - SaaSアカウント
• references/it-management-assets.md - 備品

リソース

オープンベータについて

IT管理 API はオープンベータ。仕様は予告なく変更される可能性がある。

認証と事業所スコープ

• 認証は OAuth2（read / write スコープ）。freee 共通の認可フローを利用する
• 他の freee API と同様、操作対象の事業所を company_id で指定する。指定値は現在の事業所（freee_get_current_company）と一致する必要があり、不一致だとエラーになる。切り替えは freee_set_current_company を使う
• メソッドにより company_id の位置が異なる:
• GET（一覧・単体取得）/ DELETE: クエリパラメータ company_id（必須）
• POST / PATCH（作成・更新）: リクエストボディ company_id（必須）

ページネーション

一覧取得（GET）はすべてカーソルベース。従来の offset / limit ではない点に注意。

• 1ページ目: company_id（必須）のみで GET
• 2ページ目以降: 直前のレスポンス next_page_token を query page_token に渡す
• next_page_token が null のときは末尾

freee_api_get {
  "service": "it_management",
  "path": "/hub/it_management/members",
  "query": { "company_id": 123456 }
}
# → response.next_page_token = "eyJ..."

freee_api_get {
  "service": "it_management",
  "path": "/hub/it_management/members",
  "query": { "company_id": 123456, "page_token": "eyJ..." }
}

page_size で1ページの件数も指定できる（共通 query パラメータ）。keyword, application_id, status_id 等のフィルタは一覧エンドポイントごとに異なるため、リファレンスを参照。

ページサイズと並び順の制約

• page_size の上限は 100。超過すると AHB-3003-0002。未指定時は 25。
• 並び順は created_at DESC 固定。updated_at / name 等のソート指定には対応していない。

キーワード検索の対象

keyword クエリは部分一致 OR 検索。対象はリソースごとに異なる。

• メンバー: family_name / given_name / yomi / code / phone_number / 部署名 / login_email / カスタム属性
• SaaS アカウント: account / external_id / data 内 attribute 値
• 備品: asset_number / serial_number / 利用者名 / 各 attribute 値

ヒット範囲が広いため、絞り込みたい場合は別途フィルタ（status_id, application_id 等）と組み合わせる。

削除の挙動

API ごとに削除の意味が違うので注意:

• メンバー削除（DELETE /hub/it_management/members/{id}）: ソフトデリート
• SaaSアカウント削除（DELETE /hub/it_management/application_accounts/{id}）: ソフトデリート
• 備品削除（DELETE /hub/it_management/assets/{id}）: ハードデリート（復元不可）

備品は誤削除すると戻せないため、削除前にユーザー確認を行うこと。

SaaSアカウント (application_accounts) の特殊仕様

Write 系はカスタムアプリ限定

POST / PATCH / DELETE /hub/it_management/application_accounts/* はカスタムアプリ（ユーザーが手動で追加した管理対象 SaaS）配下のアカウントのみ受け付ける。Slack / Microsoft 365 等の自動同期で取り込まれた標準アプリのアカウントは Write 系が拒否され、ITM-05-02-0003 が返る。

カスタムアプリかどうかを事前判定する API は提供されていないため、Write 試行時のエラーで判別する。

POST と PATCH で受け付けるフィールドの差

POST /application_accounts は attributes をリクエストボディに含められない（ゲートウェイで AHB-3003-0002 unsupported）。属性値の設定は、作成直後にレスポンスの id を使って PATCH /application_accounts/{id} を続けて呼ぶ二段階運用が必要。

attributes（カスタム属性）の操作

カスタムアプリは「アカウントID / 表示名 / 権限 / ライセンス / ステータス / …」などの動的属性を持つ。

• 属性スキーマは GET /application_accounts/{id} レスポンスの application.attributes 配列で取得できる（id / title / data_type / is_identity / is_display / is_status / entitlement_kind / order）。AI はこれを参照して有効な title を把握する。
• 更新リクエストの attributes キーは UUID（attribute.id）または title 名のどちらでも OK。同一アプリ内で title はユニーク制約があるため安全に逆引きされる。
• レスポンスの data フィールドは title キーで値が返る。

PATCH /hub/it_management/application_accounts/{id}
{
  "company_id": 123456,
  "attributes": { "表示名": "Yamada Taro", "権限": "Administrator" }
}

• 部分更新では送信していない attribute は既存値が維持される。明示的に null を送れば NULL クリア可能。
• is_display: true の属性は必須。既存値が無い状態で省略すると ITM-05-02-0001 表示名を入力してください (422)。一度値をセットすれば、以降の部分更新で省略しても既存値が保持される。
• is_status: true の属性に値をセットすると status.id が連動切替（指定文字列に対応する ApplicationAccountStatus が find_or_create_by される）。
• 未知の title キーは無音で無視される（エラーにならない）。タイポに気付けないため、AI は application.attributes メタデータの title セットに含まれていることを確認してから送ること。

ステータス・ロール

• application_account_status_id / application_account_role_id を PATCH ボディで指定可能。
• 不正な UUID は ITM-05-02-0001 + invalid_fields.application_account_status_id（or application_account_role_id）で 422。
• application_account_role_id: null で既存ロールをクリア。

よくある操作の流れ

メンバー登録 → SaaS アカウント紐付け

1. メンバーを作成（POST /hub/it_management/members） 2. レスポンスの id を application_account の member_id 系フィールドに利用してアカウント作成（POST /hub/it_management/application_accounts、カスタムアプリのみ）

メンバーの position_id / employment_type_id / department_ids 等の参照 ID には、対応する一覧取得エンドポイントが提供されていない。事前に値を持っている前提で扱う。不正な ID は ITM-05-03-0001 の 422 で返り、fields 配列で具体的なフィールド名が判別できる。

メンバーの primary email（PATCH /members/{id} の email）は API での更新に対応していない。

メンバーに紐づくアカウント・備品の棚卸し

特定メンバーの利用状況を横断的に確認したいとき（入退社時の棚卸し等）は、各一覧をメンバーで絞り込む。

1. SaaSアカウント: GET /hub/it_management/application_accounts を member_id（アカウントホルダー）で絞り込み 2. 備品: GET /hub/it_management/assets を member_id（利用者）で絞り込み 3. メンバー一覧自体は雇用形態（employment_type_id）・入社日/退職日の範囲でも絞り込める（GET /hub/it_management/members）。退職者の洗い出しは退職日の範囲指定が使える

各フィルタの型・指定方法はリファレンスを参照。employment_type_id のように対応するマスタ一覧 API がない参照 ID は、既存メンバーの一覧レスポンス（employment_type.id）から値を取得する。

備品の貸与状況を更新

1. 備品一覧を取得し対象を特定（GET /hub/it_management/assets） 2. PATCH /hub/it_management/assets/{id} で更新可能フィールドを変更（リファレンス参照）

備品 PATCH のリクエストボディに current_member_id を含めるとゲートウェイで AHB-3003-0002 unsupported で拒否される。API からメンバーへの貸与状況変更は不可で、UI 側での操作が必要。

部分更新

更新系（PATCH）は指定したフィールドのみが更新される。SaaS アカウントの attributes についても上記の通り部分更新が機能する。null クリアの挙動はフィールドごとに異なるため、必ず差分のみを送る。

エラー形式

code を見れば発生源と扱い方が分かる。

• ITM-05-01-XXXX は備品 API 由来。形式は { message, code, fields: [{ name, message, user_message }] }
• ITM-05-02-XXXX は SaaS アカウント API 由来。形式は同上
• ITM-05-03-XXXX はメンバー API 由来。形式は同上
• AHB-3003-0002 は API ゲートウェイ層のスキーマ違反（必須項目欠落 / 型不一致 / unsupported フィールド送信 / page_size 上限超過 等）。形式は { message, code, fields: [{ name, message }] }
• AHB-1002-9001 はシステムエラー（5xx）。形式は { message, code }。通常運用では発生しない

具体例:

• 存在しない ID へのアクセス → ITM-05-XX-0002 (404)
• 不正な参照 ID（status_id / role_id / position_id 等） → ITM-05-XX-0001 + fields (422)
• 一意制約違反（external_id 重複等） → ITM-05-XX-0001 + fields (400)
• カスタムアプリでない SaaS アカウントへの Write → ITM-05-02-0003 (400)

AI 利用時は ITM- プレフィックスのとき fields を経由して具体的なフィールドエラーを取得することを推奨。AHB-3003-0002 も fields を持つので同様に利用可能。

エラー対応

• 401/403: 認証エラー。freee_auth_status で確認。Remote MCP は再認証を促される。ローカルは freee_clear_auth → freee_authenticate
• 404: 指定 ID のリソースが存在しない、または既にソフトデリート済みのケース。レスポンスは ITM-05-XX-0002
• 一意制約違反（asset_number, serial_number, external_id, code 等のチーム内一意フィールド）は 400 + ITM-05-XX-0001 + fields で返る

振替伝票の操作

freee会計APIを使った振替伝票の登録・検索ガイド。

概要

振替伝票APIを使って仕訳の登録、検索、更新、削除を行います。 振替伝票は売掛・買掛レポートには反映されません。債権・債務データの登録は取引(Deals)を使用してください。

利用可能なパス

作成前の注意

振替伝票の作成に必要な勘定科目ID（account_item_id）、税区分コード（tax_code）は事業所ごとに異なる。推測せず、必ず事前にAPIで取得すること（取得方法は recipes/deal-operations.md の「取引作成の前準備」を参照）。

使用例

振替伝票一覧を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/manual_journals",
  "query": {
    "limit": 10
  }
}

期間で絞り込み

freee_api_get {
  "service": "accounting",
  "path": "/api/1/manual_journals",
  "query": {
    "start_issue_date": "2025-01-01",
    "end_issue_date": "2025-01-31"
  }
}

振替伝票を作成

貸借の合計金額が一致する必要があります。

freee_api_post {
  "service": "accounting",
  "path": "/api/1/manual_journals",
  "body": {
    "company_id": 123456,
    "issue_date": "2025-01-15",
    "details": [
      {
        "entry_side": "debit",
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 10000,
        "description": "前払費用の振替",
        "tag_ids": [TAG_ID]
      },
      {
        "entry_side": "credit",
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 10000,
        "description": "前払費用の振替",
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

振替伝票を更新

detailsに含まれない既存の貸借行は削除されます。更新後も残したい行は、貸借行IDを指定してdetailsに含めてください。

freee_api_put {
  "service": "accounting",
  "path": "/api/1/manual_journals/1",
  "body": {
    "company_id": 123456,
    "issue_date": "2025-01-15",
    "details": [
      {
        "id": 1,
        "entry_side": "debit",
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 15000,
        "tag_ids": [TAG_ID]
      },
      {
        "id": 2,
        "entry_side": "credit",
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "amount": 15000,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

振替伝票を削除

freee_api_delete {
  "service": "accounting",
  "path": "/api/1/manual_journals/1"
}

Tips

メモタグ「freee-mcp」の付与

振替伝票を作成する際は、freee-mcp 経由で作成したデータであることを識別できるよう、メモタグ「freee-mcp」を必ず付与すること。手順は recipes/freee-mcp-tag.md を参照。振替伝票では details[].tag_ids にタグIDを指定する。

リファレンス

詳細なAPIパラメータは references/accounting-manual-journals.md を参照。

支払依頼の操作

freee会計APIを使った支払依頼の登録・検索ガイド。

概要

支払依頼APIを使って支払依頼の作成・取得・承認操作を行います。

利用可能なパス

作成前の注意

支払依頼の作成に必要な勘定科目ID（account_item_id）、税区分コード（tax_code）、申請経路ID（approval_flow_route_id）は事業所ごとに異なる。推測せず、必ず事前にAPIで取得すること（勘定科目・税区分の取得方法は recipes/deal-operations.md の「取引作成の前準備」を参照）。

使用例

支払依頼一覧を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/payment_requests",
  "query": {
    "limit": 10
  }
}

ステータスで絞り込み

freee_api_get {
  "service": "accounting",
  "path": "/api/1/payment_requests",
  "query": {
    "status": "in_progress"
  }
}

支払依頼を作成（下書き）

freee_api_post {
  "service": "accounting",
  "path": "/api/1/payment_requests",
  "body": {
    "company_id": 123456,
    "title": "仕入代金支払い",
    "issue_date": "2025-01-15",
    "draft": true,
    "approval_flow_route_id": 1,
    "partner_id": 201,
    "payment_date": "2025-01-31",
    "payment_method": "domestic_bank_transfer",
    "payment_request_lines": [
      {
        "line_type": "deal_line",
        "description": "商品仕入",
        "amount": 50000,
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

支払依頼を作成（申請）

freee_api_post {
  "service": "accounting",
  "path": "/api/1/payment_requests",
  "body": {
    "company_id": 123456,
    "title": "外注費支払い",
    "issue_date": "2025-01-15",
    "draft": false,
    "approval_flow_route_id": 1,
    "partner_id": 201,
    "payment_date": "2025-01-31",
    "payment_request_lines": [
      {
        "line_type": "deal_line",
        "description": "1月分外注費",
        "amount": 100000,
        "account_item_id": <取得した勘定科目ID>,
        "tax_code": <取得した税区分コード>,
        "tag_ids": [TAG_ID]
      }
    ]
  }
}

Tips

メモタグ「freee-mcp」の付与

支払依頼を作成する際は、freee-mcp 経由で作成したデータであることを識別できるよう、メモタグ「freee-mcp」を必ず付与すること。手順は recipes/freee-mcp-tag.md を参照。支払依頼では payment_request_lines[].tag_ids にタグIDを指定する。

リファレンス

詳細なAPIパラメータは references/accounting-payment-requests.md を参照。

工数管理の操作

freee工数管理APIを使ったプロジェクト・工数の管理ガイド。

重要: company_id の指定方法

すべてのエンドポイントで company_id が必須です。

• GETリクエスト: query に company_id を含める
• POSTリクエスト: body に company_id を含める

利用可能なパス

使用例

以下はリクエスト構造の参考例です。APIを呼び出す前に必ず後述のリファレンスで実際のパラメータ名・型・必須項目・制約を確認してください。

プロジェクト一覧を取得

freee_api_get {
  "service": "pm",
  "path": "/projects",
  "query": {
    "company_id": 123456
  }
}

プロジェクトを作成

freee_api_post {
  "service": "pm",
  "path": "/projects",
  "body": {
    "company_id": 123456,
    "name": "新規プロジェクト",
    "code": "PJ-001",
    "from_date": "2025-04-01",
    "thru_date": "2025-12-31",
    "pm_budgets_cost": 5000
  }
}

工数を登録

freee_api_post {
  "service": "pm",
  "path": "/workloads",
  "body": {
    "company_id": 123456,
    "project_id": 1,
    "date": "2025-03-10",
    "minutes": 120,
    "memo": "設計作業"
  }
}

工数実績を取得

freee_api_get {
  "service": "pm",
  "path": "/workloads",
  "query": {
    "company_id": 123456,
    "year_month": "2025-03"
  }
}

工数サマリを取得

freee_api_get {
  "service": "pm",
  "path": "/workload_summaries",
  "query": {
    "company_id": 123456,
    "year_month": "2025-03"
  }
}

Tips

人事労務APIとの連携

/people レスポンスの payroll_employee_id が人事労務側の employee_id に対応します。 安全な工数登録ワークフロー（勤怠チェック・重複確認・承認フロー）については recipes/pm-workload-registration.md を参照してください。

リファレンス

詳細なAPIパラメータは以下を参照:

• references/pm-projects.md - プロジェクト
• references/pm-workloads.md - 工数実績
• references/pm-people.md - 従業員
• references/pm-teams.md - チーム
• references/pm-partners.md - 取引先
• references/pm-unit-costs.md - 従業員単価
• references/pm-users.md - ログインユーザー

工数の安全な登録（PM・HR連携ワークフロー）

freee工数管理と人事労務APIを連携した安全な工数登録ワークフロー。 勤怠チェック・重複確認・ユーザー承認を経て工数を登録します。

概要

工数登録を単独で行うと以下のリスクがあります:

• 休日に工数を登録してしまう
• 有給取得日に工数を登録してしまう
• 既に登録済みの工数と重複する
• 締め済みの日に登録を試みてエラーになる

このレシピでは、人事労務APIの勤怠情報を事前確認し、 ユーザーの承認を得てから登録することで、安全に工数登録を行います。

工数APIの基本操作は recipes/pm-operations.md、 勤怠APIの基本操作は recipes/hr-attendance-operations.md を参照してください。

ワークフロー

Step 1: ユーザーID解決

PM側の person_id と HR側の employee_id を紐付けます。

1-1. PM側のログインユーザー情報を取得

freee_api_get {
  "service": "pm",
  "path": "/users/me"
}

レスポンスの companies[].person_me.id がPM側の person_id です。 companies[].id から対象の company_id も確認できます。

1-2. HR側の employee_id を取得

方法A: PM /people の payroll_employee_id を使う

freee_api_get {
  "service": "pm",
  "path": "/people",
  "query": {
    "company_id": 123456,
    "person_ids[]": [1]
  }
}

レスポンスの people[].payroll_employee_id が HR の employee_id に対応します。

方法B: HR /api/v1/users/me から直接取得

freee_api_get {
  "service": "hr",
  "path": "/api/v1/users/me"
}

レスポンスの companies[].employee_id が HR の employee_id です。 payroll_employee_id が null の場合はこちらを使ってください。 こちらも null の場合は HR 未利用のユーザーなので、 step 2 をスキップして step 3 に進みます。

self_only 権限の詳細は recipes/hr-attendance-operations.md の「self_only 権限について」を参照してください。

Step 2: 勤怠情報の事前確認

対象日の勤怠記録を取得して、工数登録が可能かチェックします。

freee_api_get {
  "service": "hr",
  "path": "/api/v1/employees/{employee_id}/work_records/2025-03-10",
  "query": {
    "company_id": 123456
  }
}

レスポンスのフィールドを「安全チェック一覧」テーブルに基づいて確認し、すべてのチェックを通過した場合のみ次のステップに進みます。 勤怠APIの詳細は recipes/hr-attendance-operations.md を参照してください。

Step 3: 既存工数の重複チェック

PM GET /workloads で対象月の既存工数を取得し、同じ日・同じプロジェクトに登録済みでないか確認します（工数取得の例は recipes/pm-operations.md 参照）。

Step 4: ユーザー承認（Human-in-the-Loop）

以下の情報をユーザーに提示し、承認を得てから登録を実行します。

提示する情報:

• 登録対象日: YYYY-MM-DD
• 勤怠状態: 所定労働日 / 出勤済み（Step 2 の結果）
• 対象プロジェクト: プロジェクト名
• 登録時間: XX分（X時間XX分）
• 業務内容: メモ
• 既存工数: なし、または既存の一覧（Step 3 の結果）

ユーザーが承認したら Step 5 へ進みます。

Step 5: 工数登録の実行

PM POST /workloads で工数を登録します（登録例は recipes/pm-operations.md 参照）。

Step 6: 登録結果の検証

PM GET /workloads で登録した工数を取得し、日・プロジェクト・時間が正しいことを確認してユーザーに報告します。

安全チェック一覧

Tips

一括登録のパターン

複数日分の工数を一括登録する場合は、各日ごとに Step 2〜4 を繰り返します。 安全チェックでブロック条件に該当した日はスキップし、ユーザーに報告してください。

権限に関する注意

• 管理者権限がない場合、他の従業員の勤怠情報は取得できません（self_only 制約）
• 自分の工数登録のみであれば self_only 権限で実行可能です
• 他者の工数を登録する場合は管理者権限が必要です

リファレンス

• references/pm-workloads.md - 工数実績API詳細
• references/pm-people.md - 従業員（payroll_employee_id）
• references/pm-users.md - ログインユーザー
• references/hr-attendances.md - 勤怠API詳細
• recipes/pm-operations.md - 工数管理の基本操作
• recipes/hr-attendance-operations.md - 勤怠の操作

ファイルボックス（証憑ファイル）の操作

freee会計APIとカスタムツールを使ったファイルボックスの操作ガイド。

概要

ファイルボックスAPIを使って証憑ファイル（レシート・請求書等）のアップロード・検索・更新を行います。

利用可能なパス

ファイルアップロード

注意: freee_file_upload ツールはローカルモードでのみ利用可能です。Remote MCP をご利用の場合、ファイルのアップロードは freee Web UI から行ってください。

カスタムツール freee_file_upload を使う（推奨・ローカルモードのみ）

ローカルファイルをファイルボックスにアップロードするには、カスタムツール freee_file_upload を使います。 APIの POST /api/1/receipts は multipart/form-data が必要なため、通常の freee_api_post では利用できません。

freee_file_upload {
  "file_path": "/path/to/receipt.jpg",
  "company_id": 12345,
  "document_type": "receipt",
  "description": "ファミリーマート レシート",
  "receipt_metadatum_amount": 460,
  "receipt_metadatum_issue_date": "2024-09-29",
  "receipt_metadatum_partner_name": "ファミリーマート"
}

パラメータ:

company_id は他の freee_api_* ツールと同じく、現在の事業所と一致しない場合はエラーになります。事業所を切り替える場合は freee_set_current_company を使用してください。

使用例

証憑ファイル一覧を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/receipts",
  "query": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  }
}

特定の証憑ファイルを取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/receipts/432228305"
}

証憑ファイルのメタ情報を更新

freee_api_put {
  "service": "accounting",
  "path": "/api/1/receipts/432228305",
  "body": {
    "description": "ファミリーマート 一の橋店 レシート",
    "receipt_metadatum": {
      "partner_name": "ファミリーマート",
      "issue_date": "2024-09-29",
      "amount": 460
    },
    "document_type": "receipt"
  }
}

証憑ファイルを削除

freee_api_delete {
  "service": "accounting",
  "path": "/api/1/receipts/432228305"
}

Tips

アップロード後のWeb確認URL

ファイルをアップロードした後、以下のURLでWeb画面から確認できます:

https://secure.freee.co.jp/receipts/{id}

{id} は API レスポンスで返されるファイルボックスID（receipt.id）を使用します。

アップロード制限

• ファイルサイズ: 64MBまで
• 月間アップロード容量: 合計10GBまで
• 1分間あたりのアップロード数: 300ファイルまで
• プランによる月間アップロード数制限あり

リファレンス

詳細なAPIパラメータ（書類の種類、ステータス、カテゴリ等）は references/accounting-receipts.md を参照。

試算表・総勘定元帳の操作

freee会計APIを使った試算表・総勘定元帳の取得ガイド。

概要

試算表API・総勘定元帳APIを使って財務レポートを取得します。

重要: 未承認仕訳の取り扱いについて（必ず確認）

試算表・総勘定元帳APIを呼び出す前に、必ずユーザーに以下を確認すること:

未承認の仕訳（承認待ちの仕訳）を含めた数値を取得しますか？

デフォルトでは未承認の仕訳は除外されます。未承認仕訳を含めたい場合は approval_flow_status: "all" を指定します。

※ この設定はプレミアムプラン以上、かつ仕訳承認フローが有効な事業所でのみ利用可能です。

• ユーザーが「含める」と回答した場合: クエリパラメータに "approval_flow_status": "all" を追加
• ユーザーが「除外する」（デフォルト）と回答した場合: パラメータ指定不要（デフォルトの without_in_progress が適用される）
• ユーザーが判断できない場合: 安全側として "approval_flow_status": "all" を指定し、結果に「未承認仕訳を含む数値です」と注記する

この確認は初回のAPI呼び出し前に必ず行うこと。セッション内でユーザーの方針が決まったら、以降は同じ方針に従う。

利用可能なパス

• 試算表（BS/PL/CR）: references/accounting-trial-balance.md 参照
• 総勘定元帳: references/accounting-general-ledgers.md 参照

使用例

損益計算書を取得（未承認仕訳を含む）

freee_api_get {
  "service": "accounting",
  "path": "/api/1/reports/trial_pl",
  "query": {
    "fiscal_year": 2025,
    "approval_flow_status": "all"
  }
}

総勘定元帳を取得

freee_api_get {
  "service": "accounting",
  "path": "/api/1/reports/general_ledgers",
  "query": {
    "start_date": "2025-01-01",
    "end_date": "2025-03-31",
    "approval_flow_status": "all"
  }
}

リファレンス

詳細なパス一覧・パラメータ・レスポンス仕様は以下を参照:

• references/accounting-trial-balance.md - 試算表（BS/PL/CR）全17エンドポイント
• references/accounting-general-ledgers.md - 総勘定元帳

販売管理の操作

freee販売(sm)APIを使った案件・見積・受注・納品・売上・原価の管理ガイド。

重要: company_id は全リクエストで必須

sm APIは一覧・詳細の取得(GET)を含め、全エンドポイントで company_id が必須です。指定する場所はメソッドで異なります。

company_id が無いと初回から400になります。GETの使用例でも必ず query: { "company_id": ... } を付けてください。

ドメイン用語とパスの対応

ユーザーの言葉とAPIパスの用語が異なるため注意。

請求・入金は専用リソースではなく、売上(/sales)や受注(/sales_orders)の属性（billing_status / collection_status 等）として表現されます。

利用可能なパス

取消・復元・ロックなどの操作は各リソースのサブパス（/{id}/cancellation 等）で提供されます。下記Tips参照。

使用例

案件一覧を取得

freee_api_get {
  "service": "sm",
  "path": "/businesses",
  "query": { "company_id": 123456 }
}

案件詳細を取得

freee_api_get {
  "service": "sm",
  "path": "/businesses/01JPP4FD1CVQWCDSWA90VE1ZTM",
  "query": { "company_id": 123456 }
}

案件を作成

freee_api_post {
  "service": "sm",
  "path": "/businesses",
  "body": {
    "company_id": 123456,
    "name": "新規案件"
  }
}

案件を更新

送信したフィールドのみ更新されます。

freee_api_patch {
  "service": "sm",
  "path": "/businesses/01JPP4FD1CVQWCDSWA90VE1ZTM",
  "body": {
    "company_id": 123456,
    "name": "案件名変更",
    "internal_memo": "メモ更新"
  }
}

受注を作成

明細(lines)は deal_line_type_id 方式で指定します（name は使えません）。deal_line_type_id は GET /master/deal_line_types?type=sales で取得してください。

freee_api_post {
  "service": "sm",
  "path": "/sales_orders",
  "body": {
    "company_id": 123456,
    "sales_order_date": "2025-03-10",
    "customer_id": 1,
    "billing_partner_id": 1,
    "collecting_partner_id": 1,
    "billing_creating_method_type": "manually",
    "collection_method_type": "transfer",
    "lines": [
      {
        "line_type": "basic",
        "deal_line_type_id": "01JPP4FD1CVQWCDSWA90VE1ZTM",
        "quantity": 1,
        "unit_price": 10000,
        "withholding_enabled": false,
        "is_manual_tax_entry": false
      }
    ]
  }
}

lines の line_type は2種類:

• basic: deal_line_type_id / quantity / unit_price / withholding_enabled / is_manual_tax_entry が必須
• text: text（フリーテキスト行）のみ

enum 値:

• billing_creating_method_type: automatically（自動で請求書作成）/ manually（手動）
• collection_method_type: transfer（振込）/ cash（現金）/ bill_payable（手形）/ direct_debit（口座振替）

受注一覧を取得

freee_api_get {
  "service": "sm",
  "path": "/sales_orders",
  "query": { "company_id": 123456 }
}

Tips

ID は ULID 形式

案件・受注・売上などのIDは 01JPP4FD1CVQWCDSWA90VE1ZTM のようなULID文字列です（このガイドの /businesses/1 のような数値は説明用）。詳細・更新には一覧で取得した実際のIDを使ってください。

取消・ロック・復元の違い

取消は「無かったことにする」、ロックは「確定させて編集を止める」操作で別物です。一覧の canceled や closed フィールドで状態を判別できます。

請求・入金ステータス

売上(/sales)・見積(/quotations)の絞り込みで使うステータスの意味:

• billing_status: 請求書の送付状況（not_billed 未送付 / billed 送付済 / none 対象外）
• collection_status: 入金（決済）状況（not_settled 未決済 / partially_settled 一部決済済 / settled 決済済 / none 対象外）

ページネーション

一覧は limit（既定20・最大100）と offset でページングします。全件取得は offset を limit ずつ進めて、返却件数が limit 未満になるまでループします。

freee_api_get {
  "service": "sm",
  "path": "/sales",
  "query": { "company_id": 123456, "limit": 100, "offset": 0 }
}

関連API

マスタ情報の取得:

• references/sm-master.md - マスタ情報（商品・明細取引タイプ・案件フェーズ・受注確度・従業員等）

リファレンス

詳細なAPIパラメータは以下を参照:

• references/sm-businesses.md - 案件
• references/sm-quotations.md - 見積
• references/sm-sales-orders.md - 受注
• references/sm-deliveries.md - 納品
• references/sm-sales.md - 売上
• references/sm-cost-budgets.md - 原価予算
• references/sm-other-costs.md - その他原価
• references/sm-master.md - マスタ

トラブルシューティング

freee API スキル使用時の一般的な問題と解決方法。

認証関連

接続モードの確認

freee_server_info を実行すると、transport フィールドで現在の接続モードを確認できます。remote なら Remote MCP、stdio ならローカルモードです。

Remote MCP での認証について

Remote MCP では認証は MCP OAuth プロトコルにより自動的に処理されます。初回接続時にブラウザで freee へのログインが求められます。

Remote MCP で認証に問題がある場合:

1. ブラウザのポップアップブロックを確認 2. AI ツール（Claude Desktop 等）でカスタムコネクタを一度削除し、再度追加 3. freee に別タブでログインしてからリトライ

問題: "401 Unauthorized"

原因: 認証トークンの有効期限切れ

解決方法:

• Remote MCP の場合: MCP クライアントが自動的に再認証を促します。解決しない場合はカスタムコネクタを再追加してください。
• ローカルモードの場合:

freee_authenticate

再認証後、再度操作を実行してください。

問題: "403 Forbidden"

原因: 必要な権限がない、またはレートリミット

解決方法:

1. freee 開発者ポータルでアプリケーションの権限を確認 2. 必要な権限が有効化されているか確認 3. 権限を追加した場合は再認証が必要

freee_clear_auth
freee_authenticate

レートリミットの場合は数分待ってから再試行してください。

問題: OAuth 認証画面が表示されない（ローカルモードの場合）

原因: ブラウザがブロックしている可能性

解決方法:

1. ポップアップブロックを一時的に無効化 2. 手動でコールバック URL にアクセス 3. 別のブラウザを試す

事業所関連

問題: "Company not found"

原因: 指定した事業所 ID が存在しないか、アクセス権限がない

解決方法:

# 利用可能な事業所を確認
freee_list_companies

# 正しい事業所IDを設定
freee_set_current_company { "company_id": 12345 }

問題: 事業所を切り替えたい

解決方法:

freee_list_companies
freee_set_current_company { "company_id": 12345 }
freee_get_current_company  # 切り替わったことを確認

問題: 複数事業所がある場合どれを選ぶべきか

解決方法:

• 操作したい事業所を選択
• 不明な場合は経理部門に確認
• freee_list_companies で事業所の説明を確認

問題: "company_id の不整合"

原因: リクエストに含まれる company_id と、現在設定されている事業所が異なる

解決方法:

# 現在の事業所を確認
freee_get_current_company

# 方法1: 事業所を切り替える
freee_set_current_company { "company_id": 12345 }

# 方法2: リクエストの company_id を現在の事業所に合わせる

注意: company_id を含むリクエストは、必ず現在の事業所と一致している必要があります。

工数管理・販売API関連

問題: freee工数管理またはfreee販売APIで "500 Internal Server Error"

原因: company_id がリクエストに含まれていない

解決方法: recipes/pm-operations.md および recipes/sm-operations.md の company_id 指定方法を参照。

経費申請作成時のエラー

問題: "expense_application_line_template_id が無効"

原因: 指定した経費科目 ID が存在しない、または事業所で無効化されている

解決方法:

# 有効な経費科目IDを確認
freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_application_line_templates"
}

詳細: 各事業所で利用可能な経費科目は異なります。必ず事前に確認してください。

問題: "amount must be positive"

原因: 金額が 0 以下または数値でない

解決方法: 正の整数を指定

"amount": 5000     // 正しい
"amount": -100     // 負の数 - NG
"amount": 0        // ゼロ - NG
"amount": "5000"   // 文字列 - NG（JSONでは整数で指定）
"amount": 5000.5   // 小数 - NG（整数のみ）

問題: "Invalid date format"

原因: 日付形式が不正

解決方法: "yyyy-mm-dd" 形式を使用

"transaction_date": "2025-10-19"           // 正しい
"transaction_date": "10/19/2025"           // NG - スラッシュ区切り
"transaction_date": "2025-10-19T00:00:00Z" // NG - 時刻部分は不要
"transaction_date": "20251019"             // NG - ハイフンなし

問題: "issue_date must be after transaction_date"

原因: 申請日が発生日より前

解決方法: 申請日を発生日以降に設定

"transaction_date": "2025-10-15",  // 発生日
"issue_date": "2025-10-19"         // 申請日は発生日以降

注意: 通常、申請日は「今日」または発生日以降の日付を指定します。

問題: "title is required"

原因: 申請タイトルが空または未設定

解決方法: わかりやすいタイトルを設定

"title": "2025年10月 東京出張経費"  // 具体的で推奨
"title": "経費申請"                  // 抽象的だが可
"title": ""                         // 空文字 - NG

問題: "expense_application_lines is required"

原因: 経費明細が空または未設定

解決方法: 少なくとも 1 つの経費明細を含める

{
  "expense_application_lines": [
    {
      "expense_application_line_template_id": 1001,
      "amount": 5000,
      "transaction_date": "2025-10-19"
    }
  ]
}

問題: "section_id が無効"

原因: 指定した部門 ID が存在しない

解決方法:

# 部門一覧を確認
freee_api_get {
  "service": "accounting",
  "path": "/api/1/sections"
}

問題: 申請作成後に内容を確認したい

解決方法:

# 最近の申請を確認
freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_applications",
  "query": { "limit": 10 }
}

Web画面での確認: https://secure.freee.co.jp/expense_applications/{id}

データ取得時の問題

問題: 経費科目一覧が取得できない

原因:

• company_id が未設定または不正
• 権限がない

解決方法:

# 現在の事業所を確認
freee_get_current_company

# 経費科目を取得
freee_api_get {
  "service": "accounting",
  "path": "/api/1/expense_application_line_templates"
}

問題: "経費科目が多すぎてどれを選べばいいかわからない"

解決方法:

1. 経費科目の name と description を確認 2. 一般的な科目:

• 交通費: 電車、バス、タクシー
• 宿泊費: ホテル、旅館
• 接待交際費: 会食、接待
• 消耗品費: 文房具、備品

3. 不明な場合は経理部門に確認

パフォーマンス関連

問題: レスポンスが遅い

原因:

• 大量のデータを取得している
• ネットワークの問題

解決方法:

• limit パラメータで取得件数を制限
• 必要なデータのみ取得するよう条件を絞る

よくある質問

Q: 経費申請を下書き保存できますか？

A: freee API では、申請作成時に自動的に申請されます。下書き保存したい場合は、ローカルでデータを保存しておき、後で API を実行してください。

Q: 領収書画像を添付できますか？

A: ファイルボックス API (/api/1/receipts) を使用して証憑をアップロードし、receipt_ids で経費申請や取引に紐づけることができます。

Q: 作成した申請を修正できますか？

A: 下書き・差戻し状態の経費申請は PUT API で更新できます。申請中・承認済みの場合は freee Web UI を使用してください。

Q: 複数の経費をまとめて申請すべきですか？

A: 以下を考慮してください:

• 同じ出張: まとめる（例: 交通費+宿泊費）
• 同じ月の交通費: まとめることが多い
• 異なる種類の経費: 別々に申請することを推奨
• 会社の方針に従ってください

API の機能制限に関する問題

freee API 自体が対応していない操作については、freee-mcp（クライアント）側では解決できません。

以下のようなケースは API の機能制限に該当します:

• 特定の承認経路（部門・役職ベース等）で API から申請ができない
• 特定の条件（外貨を含む等）のデータが API で取得できない
• Web UI では可能な操作が API では提供されていない
• 特定のエンドポイントやフィールドが存在しない

このような場合は、freee Public API のリクエストフォームから要望を送信してください:

• freee Public API リクエストフォーム: https://docs.google.com/forms/d/e/1FAIpQLSdG19OrIdc0nbI-F5L1hkYRAfh4l-qD0ugvuFqxvaOUdXVqXg/viewform

API の機能制限を freee-mcp の GitHub Issues に報告いただいても、クライアント側では対応できません。

サポートが必要な場合

freee API 公式ドキュメント

https://developer.freee.co.jp/docs

freee Public API リクエストフォーム

API の機能拡充や改善の要望は、freee Public API リクエストフォームから送信してください:

• https://docs.google.com/forms/d/e/1FAIpQLSdG19OrIdc0nbI-F5L1hkYRAfh4l-qD0ugvuFqxvaOUdXVqXg/viewform

GitHub Issues（freee-mcp の不具合・改善要望）

https://github.com/freee/freee-mcp/issues

freee-mcp（MCP サーバー）自体の不具合や改善要望は、上記リポジトリの Issue で報告してください。freee API が提供していない機能のリクエストは、freee Public API リクエストフォーム（https://docs.google.com/forms/d/e/1FAIpQLSdG19OrIdc0nbI-F5L1hkYRAfh4l-qD0ugvuFqxvaOUdXVqXg/viewform）へお願いします。freee サポートでは freee-mcp に関するお問い合わせは受け付けておりません。

問い合わせ前に確認すること

1. freee_auth_status で認証を確認しましたか？ 2. freee_get_current_company で事業所を確認しましたか？ 3. エラーメッセージを正確にコピーしましたか？ 4. API の機能制限ではなく、freee-mcp の問題であることを確認しましたか？

Account groups

概要

決算書表示名

エンドポイント一覧

POST /api/1/account_groups

操作: 決算書表示名の作成

説明: 概要 指定した事業所の決算書表示名を作成する

リクエストボディ

(必須)

• company_id (必須): integer(int64) - 事業所ID 例: 1
• name (必須): string - 決算書表示名 (20文字以内) 例: 新しい決算書表示名
• account_category_id (必須): integer(int64) - 勘定科目カテゴリーID Selectablesフォーム用選択項目情報エンドポイント(account_groups.account_category_id)で取得可能です 例: 1
• index (任意): integer(int64) - 表示順 例: 1

レスポンス (201)

• account_group (必須): object
• company_id (必須): integer(int64) - 事業所ID 例: 1
• id (必須): integer(int64) - 決算書表示名(小カテゴリー)ID 例: 1
• name (必須): string - 決算書表示名 例: 新しい決算書表示名
• account_structure_id (必須): integer(int64) - 年度ID 例: 1
• account_category_id (必須): integer(int64) - 勘定科目カテゴリID 例: 1
• index (必須): integer(int64) - 表示順 例: 1

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

Account items

概要

勘定科目

エンドポイント一覧

GET /api/1/account_items/{id}

操作: 勘定科目の取得

説明: 概要 指定した勘定科目を取得する 事業所の設定で勘定科目コードを使用する設定にしている場合、レスポンスで勘定科目コード(code)を返します

パラメータ

レスポンス (200)

• account_item (必須): object
• id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• name (必須): string - 勘定科目名 (30文字以内) 例: ソフトウェア
• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• account_category (必須): string - 勘定科目カテゴリー 例: 現金・預金
• account_category_id (必須): integer(int64) - 勘定科目のカテゴリーID 例: 1 (最小: 1)
• shortcut (任意): string - ショートカット1 (20文字以内) 例: SOFUTO
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 123
• code (任意): string - 勘定科目コード 例: 123
• searchable (必須): integer(int64) - 検索可能:2, 検索不可：3 例: 2 (最小: 2, 最大: 3)
• accumulated_dep_account_item_name (任意): string - 減価償却累計額勘定科目（法人のみ利用可能） 例: 減価償却累計額
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• items (任意): array[object]
• partners (任意): array[object]
• available (必須): boolean - 勘定科目の使用設定（true: 使用する、false: 使用しない） 例: true
• walletable_id (必須): integer(int64) - 口座ID 例: 1 (最小: 1)
• group_name (任意): string - 決算書表示名（小カテゴリー） 例: 売掛金
• group_id (任意): integer(int64) - 決算書表示名ID（小カテゴリー） 例: 1 (最小: 1)
• corresponding_income_name (任意): string - 収入取引相手勘定科目名 例: 売掛金
• corresponding_income_id (任意): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_name (任意): string - 支出取引相手勘定科目名 例: 買掛金
• corresponding_expense_id (任意): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)

PUT /api/1/account_items/{id}

操作: 勘定科目の更新

説明: 概要 指定した勘定科目を更新する

注意点 tax_codeは、指定した事業所の税区分一覧の取得APIでavailableの値がtrue、かつ経過措置税区分ではない5%の税区分を確認して、そのcodeを指定して勘定科目の更新をしてください。例 課対仕入の場合、34を指定してください codeを利用するには、事業所の設定で勘定科目コードを使用する設定にする必要があります。

パラメータ

リクエストボディ

(必須)

• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• account_item (必須): object
• name (任意): string - 勘定科目名 (30文字以内)

口座に紐付かない勘定科目の更新時は必須です。 口座に紐付く勘定科目の更新時は指定することができません。 例: 新しい勘定科目

• shortcut (任意): string - ショートカット1 (20文字以内) 例: NEWACCOUNTITEM
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 999
• code (任意): string - 勘定科目コード 例: 999 (パターン: ^[0-9a-zA-Z_-]+$)
• tax_code (必須): integer(int64) - 税区分コード 指定できるコードは本APIの注意点をご確認ください。 例: 1 (最小: 0, 最大: 2147483647)
• group_name (必須): string - 決算書表示名（小カテゴリー） Selectablesフォーム用選択項目情報エンドポイント(account_groups.name)で取得可能です 例: その他預金
• account_category_id (必須): integer(int64) - 勘定科目カテゴリーID Selectablesフォーム用選択項目情報エンドポイント(account_groups.account_category_id)で取得可能です 例: 1 (最小: 1)
• corresponding_income_id (必須): integer(int64) - 収入取引相手勘定科目ID 例: 1
• corresponding_expense_id (必須): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• searchable (任意): integer(int64) - 検索可能:2, 検索不可：3(登録時未指定の場合は2で登録されます。更新時未指定の場合はsearchableは変更されません。) 例: 2 (最小: 2, 最大: 3)
• items (任意): array[object] - 品目
• partners (任意): array[object] - 取引先

レスポンス (200)

• account_item (必須): object
• id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• name (必須): string - 勘定科目名 (30文字以内) 例: ソフトウェア
• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• account_category (必須): string - 勘定科目カテゴリー 例: 現金・預金
• account_category_id (必須): integer(int64) - 勘定科目のカテゴリーID 例: 1 (最小: 1)
• shortcut (任意): string - ショートカット1 (20文字以内) 例: SOFUTO
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 123
• code (任意): string - 勘定科目コード 例: 123
• searchable (必須): integer(int64) - 検索可能:2, 検索不可：3 例: 2 (最小: 2, 最大: 3)
• accumulated_dep_account_item_name (任意): string - 減価償却累計額勘定科目（法人のみ利用可能） 例: 減価償却累計額
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• items (任意): array[object]
• partners (任意): array[object]
• available (必須): boolean - 勘定科目の使用設定（true: 使用する、false: 使用しない） 例: true
• walletable_id (必須): integer(int64) - 口座ID 例: 1 (最小: 1)
• group_name (任意): string - 決算書表示名（小カテゴリー） 例: 売掛金
• group_id (任意): integer(int64) - 決算書表示名ID（小カテゴリー） 例: 1 (最小: 1)
• corresponding_income_name (任意): string - 収入取引相手勘定科目名 例: 売掛金
• corresponding_income_id (任意): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_name (任意): string - 支出取引相手勘定科目名 例: 買掛金
• corresponding_expense_id (任意): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)

DELETE /api/1/account_items/{id}

操作: 勘定科目の削除

説明: 概要 指定した勘定科目を削除する

注意点 削除できる勘定科目は、追加で作成したカスタム勘定科目のみです。 デフォルトで存在する勘定科目や口座の勘定科目は削除できません。

パラメータ

レスポンス (204)

GET /api/1/account_items

操作: 勘定科目一覧の取得

説明: 概要 指定した事業所の勘定科目一覧を取得する

定義 default_tax_code : リクエストした日時を基準とした税区分コード

注意点 default_tax_code は勘定科目作成・更新時に利用するものではありません 事業所の設定で勘定科目コードを使用する設定にしている場合、レスポンスで勘定科目コード(code)を返します

パラメータ

レスポンス (200)

• account_items (必須): array[object]

配列の要素:

• id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• name (必須): string - 勘定科目名 (30文字以内) 例: ソフトウェア
• tax_code (必須): integer(int64) - 税区分コード 例: 1
• shortcut (任意): string - ショートカット1 (20文字以内) 例: SOFUTO
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 123
• code (任意): string - 勘定科目コード 例: 123
• default_tax_code (必須): integer(int64) - デフォルト設定がされている税区分コード 例: 34
• account_category (必須): string - 勘定科目カテゴリー 例: 現金・預金
• account_category_id (必須): integer(int64) - 勘定科目のカテゴリーID 例: 1 (最小: 1)
• categories (必須): array[string]
• available (必須): boolean - 勘定科目の使用設定（true: 使用する、false: 使用しない） 例: true
• walletable_id (必須): integer(int64) - 口座ID 例: 1 (最小: 1)
• group_name (任意): string - 決算書表示名（小カテゴリー） 例: 売掛金
• group_id (任意): integer(int64) - 決算書表示名ID（小カテゴリー） 例: 1 (最小: 1)
• corresponding_income_name (任意): string - 収入取引相手勘定科目名 例: 売掛金
• corresponding_income_id (任意): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_name (任意): string - 支出取引相手勘定科目名 例: 買掛金
• corresponding_expense_id (任意): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)
• update_date (任意): string - 更新日(yyyy-mm-dd) 例: 2020-06-15

POST /api/1/account_items

操作: 勘定科目の作成

説明: 概要 指定した事業所の勘定科目を作成する

注意点 tax_codeは、指定した事業所の税区分一覧の取得APIでavailableの値がtrue、かつ経過措置税区分ではない5%の税区分を確認して、そのcodeを指定して勘定科目の作成をしてください。例 課対仕入の場合、34を指定してください codeを利用するには、事業所の設定で勘定科目コードを使用する設定にする必要があります。

リクエストボディ

(必須)

• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• account_item (必須): object
• name (必須): string - 勘定科目名 (30文字以内) 例: 新しい勘定科目
• shortcut (任意): string - ショートカット1 (20文字以内) 例: NEWACCOUNTITEM
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 999
• code (任意): string - 勘定科目コード 例: 999 (パターン: ^[0-9a-zA-Z_-]+$)
• tax_code (必須): integer(int64) - 税区分コード 指定できるコードは本APIの注意点をご確認ください。 例: 1 (最小: 0, 最大: 2147483647)
• group_name (必須): string - 決算書表示名（小カテゴリー） Selectablesフォーム用選択項目情報エンドポイント(account_groups.name)で取得可能です 例: その他預金
• account_category_id (必須): integer(int64) - 勘定科目カテゴリーID Selectablesフォーム用選択項目情報エンドポイント(account_groups.account_category_id)で取得可能です 例: 1 (最小: 1)
• corresponding_income_id (必須): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_id (必須): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• searchable (任意): integer(int64) - 検索可能:2, 検索不可：3(登録時未指定の場合は2で登録されます。更新時未指定の場合はsearchableは変更されません。) 例: 2 (最小: 2, 最大: 3)
• items (任意): array[object] - 品目
• partners (任意): array[object] - 取引先

レスポンス (201)

• account_item (必須): object
• id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• name (必須): string - 勘定科目名 (30文字以内) 例: ソフトウェア
• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• account_category (必須): string - 勘定科目カテゴリー 例: 現金・預金
• account_category_id (必須): integer(int64) - 勘定科目のカテゴリーID 例: 1 (最小: 1)
• shortcut (任意): string - ショートカット1 (20文字以内) 例: SOFUTO
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 123
• code (任意): string - 勘定科目コード 例: 123
• searchable (必須): integer(int64) - 検索可能:2, 検索不可：3 例: 2 (最小: 2, 最大: 3)
• accumulated_dep_account_item_name (任意): string - 減価償却累計額勘定科目（法人のみ利用可能） 例: 減価償却累計額
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• items (任意): array[object]
• partners (任意): array[object]
• available (必須): boolean - 勘定科目の使用設定（true: 使用する、false: 使用しない） 例: true
• walletable_id (必須): integer(int64) - 口座ID 例: 1 (最小: 1)
• group_name (任意): string - 決算書表示名（小カテゴリー） 例: 売掛金
• group_id (任意): integer(int64) - 決算書表示名ID（小カテゴリー） 例: 1 (最小: 1)
• corresponding_income_name (任意): string - 収入取引相手勘定科目名 例: 売掛金
• corresponding_income_id (任意): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_name (任意): string - 支出取引相手勘定科目名 例: 買掛金
• corresponding_expense_id (任意): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)

PUT /api/1/account_items/code/upsert

操作: 勘定科目の更新（存在しない場合は作成）

説明: 概要 勘定科目コードをキーに、指定した勘定科目の情報を更新（存在しない場合は作成）する

注意点 tax_codeは、指定した事業所の税区分一覧の取得APIでavailableの値がtrue、かつ経過措置税区分ではない5%の税区分を確認して、そのcodeを指定して勘定科目の更新をしてください。例 課対仕入の場合、34を指定してください codeを利用するには、事業所の設定で勘定科目コードを使用する設定にする必要があります。

リクエストボディ

(必須)

• code (必須): string - 勘定科目コード 例: 999 (パターン: ^[0-9a-zA-Z_-]+$)
• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• account_item (必須): object
• name (任意): string - 勘定科目名 (30文字以内)

口座に紐付かない勘定科目の更新時は必須です。 口座に紐付く勘定科目の更新時は指定することができません。 例: 新しい勘定科目

• shortcut (任意): string - ショートカット1 (20文字以内) 例: NEWACCOUNTITEM
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 999
• tax_code (必須): integer(int64) - 税区分コード 指定できるコードは本APIの注意点をご確認ください。 例: 1 (最小: 0, 最大: 2147483647)
• group_name (必須): string - 決算書表示名（小カテゴリー） Selectablesフォーム用選択項目情報エンドポイント(account_groups.name)で取得可能です 例: その他預金
• account_category_id (必須): integer(int64) - 勘定科目カテゴリーID Selectablesフォーム用選択項目情報エンドポイント(account_groups.account_category_id)で取得可能です 例: 1 (最小: 1)
• corresponding_income_id (必須): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_id (必須): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• searchable (任意): integer(int64) - 検索可能:2, 検索不可：3(登録時未指定の場合は2で登録されます。更新時未指定の場合はsearchableは変更されません。) 例: 2 (最小: 2, 最大: 3)
• items (任意): array[object] - 品目
• partners (任意): array[object] - 取引先

レスポンス (200)

• account_item (必須): object
• id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• name (必須): string - 勘定科目名 (30文字以内) 例: ソフトウェア
• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• account_category (必須): string - 勘定科目カテゴリー 例: 現金・預金
• account_category_id (必須): integer(int64) - 勘定科目のカテゴリーID 例: 1 (最小: 1)
• shortcut (任意): string - ショートカット1 (20文字以内) 例: SOFUTO
• shortcut_num (任意): string - ショートカット2 (20文字以内) 例: 123
• code (任意): string - 勘定科目コード 例: 123
• searchable (必須): integer(int64) - 検索可能:2, 検索不可：3 例: 2 (最小: 2, 最大: 3)
• accumulated_dep_account_item_name (任意): string - 減価償却累計額勘定科目（法人のみ利用可能） 例: 減価償却累計額
• accumulated_dep_account_item_id (任意): integer(int64) - 減価償却累計額勘定科目ID（法人のみ利用可能） 例: 1 (最小: 1)
• items (任意): array[object]
• partners (任意): array[object]
• available (必須): boolean - 勘定科目の使用設定（true: 使用する、false: 使用しない） 例: true
• walletable_id (必須): integer(int64) - 口座ID 例: 1 (最小: 1)
• group_name (任意): string - 決算書表示名（小カテゴリー） 例: 売掛金
• group_id (任意): integer(int64) - 決算書表示名ID（小カテゴリー） 例: 1 (最小: 1)
• corresponding_income_name (任意): string - 収入取引相手勘定科目名 例: 売掛金
• corresponding_income_id (任意): integer(int64) - 収入取引相手勘定科目ID 例: 1 (最小: 1)
• corresponding_expense_name (任意): string - 支出取引相手勘定科目名 例: 買掛金
• corresponding_expense_id (任意): integer(int64) - 支出取引相手勘定科目ID 例: 1 (最小: 1)

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

Approval flow routes

概要

申請経路

エンドポイント一覧

GET /api/1/approval_flow_routes

操作: 申請経路一覧の取得

説明: 概要 指定した事業所の申請経路一覧を取得する 各種申請APIの使い方については、freee会計の各種申請APIの使い方をご参照ください 経費精算APIの使い方については、freee会計の経費精算APIの使い方をご参照ください

注意点 申請経路、承認者の指定として部門役職データ連携を活用し、以下のいずれかを利用している申請と申請経路はAPI経由で参照は可能ですが、作成と更新、承認ステータスの変更ができません。 役職指定（申請者の所属部門） 役職指定（申請時に部門指定） 部門および役職指定

パラメータ

• TxnApproval - 仕訳承認
• ExpenseApplication - 経費精算
• PaymentRequest - 支払依頼
• ApprovalRequest - 各種申請
• DocApproval - 請求書等 (見積書・納品書・請求書・発注書) (選択肢: TxnApproval, ExpenseApplication, PaymentRequest, ApprovalRequest, DocApproval) |

| request_form_id | query | いいえ | integer | 申請フォームID request_form_id指定時はusage条件をApprovalRequestに指定してください。指定しない場合無効になります。 |

レスポンス (200)

• approval_flow_routes (必須): array[object]

配列の要素:

• id (必須): integer(int64) - 申請経路ID 例: 1 (最小: 1)
• name (任意): string - 申請経路名 例: 申請経路
• description (任意): string - 申請経路の説明 例: 申請経路の説明
• user_id (任意): integer(int64) - 更新したユーザーのユーザーID 例: 1 (最小: 1)
• definition_system (任意): boolean - システム作成の申請経路かどうか 例: true
• first_step_id (任意): integer(int64) - 最初の承認ステップのID 例: 1 (最小: 1)
• usages (任意): array[string] - 申請種別（申請経路を使用できる申請種別を示します。例えば、ApprovalRequest の場合は、各種申請で使用できる申請経路です。）
• TxnApproval - 仕訳承認
• ExpenseApplication - 経費精算
• PaymentRequest - 支払依頼
• ApprovalRequest - 各種申請
• DocApproval - 請求書等 (見積書・納品書・請求書・発注書)
• request_form_ids (任意): array[integer] - 申請経路で利用できる申請フォームID配列
• default_route (必須): boolean - 基本経路として設定されているかどうか<br><br>

リクエストパラメータusageに下記のいずれかが指定され、かつ、基本経路の場合はtrueになります。

• TxnApproval - 仕訳承認
• ExpenseApplication - 経費精算
• PaymentRequest - 支払依頼
• ApprovalRequest(リクエストパラメータrequest_form_idを同時に指定) - 各種申請
• DocApproval - 請求書等 (見積書・納品書・請求書・発注書)

<a href="https://support.freee.co.jp/hc/ja/articles/900000507963" target="_blank">申請フォームの基本経路設定</a> 例: true

GET /api/1/approval_flow_routes/{id}

操作: 申請経路の取得

説明: 概要 指定した事業所の申請経路を取得する 各種申請APIの使い方については、freee会計の各種申請APIの使い方をご参照ください 経費精算APIの使い方については、freee会計の経費精算APIの使い方をご参照ください

注意点 申請経路、承認者の指定として部門役職データ連携を活用し、以下のいずれかを利用している申請と申請経路はAPI経由で参照は可能ですが、作成と更新、承認ステータスの変更ができません。 役職指定（申請者の所属部門） 役職指定（申請時に部門指定） 部門および役職指定

パラメータ

レスポンス (200)

• approval_flow_route (必須): object
• id (必須): integer(int64) - 申請経路ID 例: 1 (最小: 1)
• name (任意): string - 申請経路名 例: 申請経路
• description (任意): string - 申請経路の説明 例: 申請経路の説明
• user_id (任意): integer(int64) - 更新したユーザーのユーザーID 例: 1 (最小: 1)
• definition_system (任意): boolean - システム作成の申請経路かどうか 例: true
• first_step_id (任意): integer(int64) - 最初の承認ステップのID 例: 1 (最小: 1)
• usages (任意): array[string] - 申請種別（申請経路を使用できる申請種別を示します。例えば、ApprovalRequest の場合は、各種申請で使用できる申請経路です。）
• TxnApproval - 仕訳承認
• ExpenseApplication - 経費精算
• PaymentRequest - 支払依頼
• ApprovalRequest - 各種申請
• DocApproval - 請求書等 (見積書・納品書・請求書・発注書)
• request_form_ids (必須): array[integer] - 申請経路で利用できる申請フォームID配列
• steps (任意): array[object] - 承認ステップ（配列）

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

Banks

概要

連携サービス

エンドポイント一覧

GET /api/1/banks

操作: 連携サービス一覧の取得

説明: 概要 連携しているサービス一覧を取得する

定義 type bank_account : 銀行口座 credit_card : クレジットカード wallet : その他の決済口座

パラメータ

レスポンス (200)

• banks (必須): array[object]

配列の要素:

• id (必須): integer(int64) - 連携サービスID 例: 1 (最小: 1)
• name (任意): string - 連携サービス名 例: フリー銀行
• type (任意): string - 連携サービス種別: (銀行口座: bank_account, クレジットカード: credit_card, 現金: wallet) (選択肢: bank_account, credit_card, wallet) 例: bank_account
• name_kana (任意): string - 連携サービス名(カナ) 例: フリーギンコウ

GET /api/1/banks/{id}

操作: 連携サービスの取得

説明: 概要 連携しているサービスを取得する

定義 type bank_account : 銀行口座 credit_card : クレジットカード wallet : その他の決済口座

パラメータ

レスポンス (200)

• bank (必須): object
• id (必須): integer(int64) - 連携サービスID 例: 1 (最小: 1)
• name (任意): string - 連携サービス名 例: フリー銀行
• type (任意): string - 連携サービス種別: (銀行口座: bank_account, クレジットカード: credit_card, 現金: wallet) (選択肢: bank_account, credit_card, wallet) 例: bank_account
• name_kana (任意): string - 連携サービス名(カナ) 例: フリーギンコウ

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

Expense application line templates

概要

経費科目

エンドポイント一覧

GET /api/1/expense_application_line_templates

操作: 経費科目一覧の取得

説明: 概要 指定した事業所の経費科目一覧を取得する

パラメータ

レスポンス (200)

• expense_application_line_templates (必須): array[object]

配列の要素:

• id (必須): integer(int64) - 経費科目ID 例: 1 (最小: 1)
• source_line_template_id (必須): integer(int64) - 経費科目の元となるテンプレートを識別するID。経費科目の設定を変更しても変わらない固定値 例: 1 (最小: 0)
• name (必須): string - 経費科目名 例: 交通費
• account_item_id (任意): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• account_item_name (必須): string - 勘定科目名 例: 旅費交通費
• tax_code (任意): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• tax_name (必須): string - 税区分名 例: 課対仕入
• description (任意): string - 経費科目の説明 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意 例: true

POST /api/1/expense_application_line_templates

操作: 経費科目の作成

リクエストボディ

(必須)

• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• name (必須): string - 経費科目名 (100文字以内) 例: 交通費
• account_item_id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• item_id (任意): integer(int64) - 品目ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード（税区分のdisplay_categoryがtax_5: 5%表示の税区分, tax_r8: 軽減税率8%表示の税区分に該当するtax_codeのみ利用可能です。税区分のdisplay_categoryは /taxes/companies/{:company_id}のAPIから取得可能です。） 例: 1 (最小: 0, 最大: 2147483647)
• description (任意): string - 経費科目の説明 (1000文字以内) 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 (1000文字以内) 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意<br>

falseを指定した時は申請時の領収書の添付を任意とします。<br> trueを指定した時は申請時の領収書の添付を必須とします。<br> 未指定の時は申請時の領収書の添付を任意とします。 例: true

レスポンス (201)

• expense_application_line_template (必須): object
• id (必須): integer(int64) - 経費科目ID 例: 1 (最小: 1)
• source_line_template_id (必須): integer(int64) - 経費科目の元となるテンプレートを識別するID。経費科目の設定を変更しても変わらない固定値 例: 1 (最小: 0)
• name (必須): string - 経費科目名 例: 交通費
• account_item_id (任意): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• account_item_name (必須): string - 勘定科目名 例: 旅費交通費
• tax_code (任意): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• tax_name (必須): string - 税区分名 例: 課対仕入
• description (任意): string - 経費科目の説明 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意 例: true

GET /api/1/expense_application_line_templates/{id}

操作: 経費科目の取得

パラメータ

レスポンス (200)

• expense_application_line_template (必須): object
• id (必須): integer(int64) - 経費科目ID 例: 1 (最小: 1)
• source_line_template_id (必須): integer(int64) - 経費科目の元となるテンプレートを識別するID。経費科目の設定を変更しても変わらない固定値 例: 1 (最小: 0)
• name (必須): string - 経費科目名 例: 交通費
• account_item_id (任意): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• account_item_name (必須): string - 勘定科目名 例: 旅費交通費
• tax_code (任意): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• tax_name (必須): string - 税区分名 例: 課対仕入
• description (任意): string - 経費科目の説明 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意 例: true

PUT /api/1/expense_application_line_templates/{id}

操作: 経費科目の更新

パラメータ

リクエストボディ

(必須)

• company_id (必須): integer(int64) - 事業所ID 例: 1 (最小: 1)
• name (必須): string - 経費科目名 (100文字以内) 例: 交通費
• account_item_id (必須): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• item_id (任意): integer(int64) - 品目ID 例: 1 (最小: 1)
• tax_code (必須): integer(int64) - 税区分コード（税区分のdisplay_categoryがtax_5: 5%表示の税区分, tax_r8: 軽減税率8%表示の税区分に該当するtax_codeのみ利用可能です。税区分のdisplay_categoryは /taxes/companies/{:company_id}のAPIから取得可能です。） 例: 1 (最小: 0, 最大: 2147483647)
• description (任意): string - 経費科目の説明 (1000文字以内) 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 (1000文字以内) 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意<br>

falseを指定した時は申請時の領収書の添付を任意とします。<br> trueを指定した時は申請時の領収書の添付を必須とします。<br> 未指定の時は申請時の領収書の添付を任意とします。 例: true

レスポンス (200)

• expense_application_line_template (必須): object
• id (必須): integer(int64) - 経費科目ID 例: 1 (最小: 1)
• source_line_template_id (必須): integer(int64) - 経費科目の元となるテンプレートを識別するID。経費科目の設定を変更しても変わらない固定値 例: 1 (最小: 0)
• name (必須): string - 経費科目名 例: 交通費
• account_item_id (任意): integer(int64) - 勘定科目ID 例: 1 (最小: 1)
• account_item_name (必須): string - 勘定科目名 例: 旅費交通費
• tax_code (任意): integer(int64) - 税区分コード 例: 1 (最小: 0, 最大: 2147483647)
• tax_name (必須): string - 税区分名 例: 課対仕入
• description (任意): string - 経費科目の説明 例: 電車、バス、飛行機などの交通費
• line_description (任意): string - 内容の補足 例: 移動区間
• required_receipt (任意): boolean - 添付ファイルの必須/任意 例: true

DELETE /api/1/expense_application_line_templates/{id}

操作: 経費科目の削除

パラメータ

レスポンス (204)

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

Fixed assets

概要

固定資産台帳

エンドポイント一覧

GET /api/1/fixed_assets

操作: 固定資産一覧の取得

説明: 概要 指定した事業所の固定資産一覧を取得する

定義 このAPIは法人エンタープライズに加入している事業所のみが利用できます。 target_date : 表示したい会計期間の開始年月日。開始年月日以外を指定した場合は、その日付が含まれる会計期間が対象となります。 depreciation_amount : 本年分の償却費合計 depreciation_method : 償却方法 depreciation_account_item_id : 減価償却に使う勘定科目 acquisition_cost : 取得価額 opening_balance : 期首残高 undepreciated_balance : 未償却残高。土地などの償却しない固定資産はnullが返ります。 opening_accumulated_depreciation : 期首減価償却累計額 closing_accumulated_depreciation : 期末減価償却累計額

注意点 up_to_dateがfalseの場合、残高の集計が完了していません。最新の集計結果を確認したい場合は、時間を空けて再度取得する必要があり...

パラメータ

レスポンス (200)

• fixed_assets (必須): array[object]

配列の要素:

• company_id (任意): integer(int64) - 事業所ID 例: 1 (最小: 1)
• id (任意): integer(int64) - 固定資産ID 例: 1 (最小: 1)
• name (任意): string - 固定資産名 例: pc
• management_number (任意): string - 管理番号 例: pc-0001
• account_item_id (任意): integer(int64) - 勘定科目ID 例: 22 (最小: 1)
• section_id (任意): integer(int64) - 部門ID 例: 0 (最小: 1)
• item_id (任意): integer(int64) - 品目ID 例: 0 (最小: 1)
• depreciation_method (任意): string - 償却方法:(少額償却: small_sum_method, 一括償却: lump_sum_method, 定額法: straight_line_method, 定率法: multiple_method, 旧定率法: old_multiple_method, 旧定額法: old_straight_line_method, 償却なし: non_depreciate_method, 任意償却: voluntary_method, 即時償却: immediate_method, 均等償却: equal_method) (選択肢: small_sum_method, lump_sum_method, straight_line_method, multiple_method, old_multiple_method, old_straight_line_method, non_depreciate_method, voluntary_method, immediate_method, equal_method) 例: straight_line_method
• depreciation_account_item_id (任意): integer(int64) - 減価償却に使う勘定科目ID 例: 99 (最小: 1)
• prefecture_code (任意): integer(int64) - 都道府県コード（-1: 設定しない、0:北海道、1:青森、2:岩手、3:宮城、4:秋田、5:山形、6:福島、7:茨城、8:栃木、9:群馬、10:埼玉、11:千葉、12:東京、13:神奈川、14:新潟、15:富山、16:石川、17:福井、18:山梨、19:長野、20:岐阜、21:静岡、22:愛知、23:三重、24:滋賀、25:京都、26:大阪、27:兵庫、28:奈良、29:和歌山、30:鳥取、31:島根、32:岡山、33:広島、34:山口、35:徳島、36:香川、37:愛媛、38:高知、39:福岡、40:佐賀、41:長崎、42:熊本、43:大分、44:宮崎、45:鹿児島、46:沖縄 例: 4 (最小: -1, 最大: 46)
• city_name (任意): string - 申告先市区町村 例: 港区
• depreciation_amount (任意): integer(int64) - 本年分の償却費合計 例: 18533
• acquisition_cost (任意): integer(int64) - 取得価額 例: 150000
• opening_balance (任意): integer(int64) - 期首残高（取得日が会計期間に含まれるとき期首残高は0になります。） 例: 92000
• undepreciated_balance (任意): integer(int64) - 未償却残高 例: 46000
• opening_accumulated_depreciation (任意): integer(int64) - 期首減価償却累計額 例: 100000
• closing_accumulated_depreciation (任意): integer(int64) - 期末減価償却累計額 例: 46000
• life_years (任意): integer(int64) - 耐用年数 例: 5
• acquisition_date (任意): string(date) - 取得日 例: 2021-07-13
• created_at (任意): string - 作成日時（ISO8601形式） 例: 2021-07-15T18:30:24+09:00
• depreciation_status (任意): string - 売却もしくは除却ステータス: (売却済: sold, 除却済: retired, 償却済: depreciated, 償却中: depreciation, 償却なし: non_depreciation) (選択肢: sold, retired, depreciated, depreciation, non_depreciation) 例: depreciation
• retire_date (任意): string(date) - 除却日、もしくは売却日 例: 2022-03-24
• fiscal_year (必須): object
• start_date (必須): string - 会計年度開始日 (yyyy-mm-dd) 例: 2022-01-01
• end_date (必須): string - 会計年度終了日 (yyyy-mm-dd) 例: 2022-12-31
• up_to_date (必須): boolean - 集計結果が最新かどうか 例: true
• up_to_date_reasons (必須): array[object] - 集計が最新でない場合の要因情報

配列の要素:

• code (必須): string - コード (選択肢: depreciation_creating, depreciation_create_error) 例: depreciation_creating
• message (必須): string - 集計が最新でない理由 例: 当期の固定資産の償却作成が完了していないため、正しい集計結果でない可能性があります。

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs

有給申請

概要

有給申請の操作

エンドポイント一覧

参考情報

• freee API公式ドキュメント: https://developer.freee.co.jp/docs