freee の請求書を API で自動作成する方法（エンジニア向け）

freee の請求書を手で作るのがだるい。

月に数十件、数百件の請求書を発行している会社なら、この作業を API で自動化したいと思ったことがあるはずです。

freee は API を公開していて、プログラムから請求書を作成できます。ただし、公式ドキュメントは網羅的な分、「結局どうすればいいの？」が分かりにくい。

この記事では、freee API で請求書を自動作成するために最低限やることを、実際のペイロード構造付きで解説します。

前提

freee の法人アカウントを持っている（個人事業主プランでも可）
プログラミングの基本は分かる（HTTP リクエストが送れるレベル）
言語は問わない（この記事では JSON ペイロードで説明する）

全体の流れ

freee API で請求書を作るまでの流れは 4 ステップです。

① OAuth 2.0 でアクセストークンを取得
② 取引先（partner）を検索 or 作成
③ 請求書（invoice）を作成
④ 商品明細（invoice_contents）を含めて登録

③と④は 1 回の API コールで同時にできます。つまり、実質 3 ステップ。

ステップ1: OAuth 2.0 認証

アプリの登録

freee の開発者ページ（app.secure.freee.co.jp/developers）でアプリを作成します。

必要な情報:

アプリ名
リダイレクト URI（認証後のコールバック先）
利用する API のスコープ

請求書の作成に必要なスコープは以下の 2 つ。

read — 取引先の検索に使う
write — 請求書の作成、取引先の新規登録に使う

アクセストークンの取得

標準的な OAuth 2.0 Authorization Code Flow です。

ユーザーを freee の認証画面にリダイレクト
ユーザーが許可すると、リダイレクト URI に認可コードが返る
認可コードをアクセストークンに交換

POST https://accounts.secure.freee.co.jp/public_api/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

レスポンスに access_token と refresh_token が返ります。アクセストークンの有効期限は 24 時間。期限切れ後は refresh_token で再取得してください。

事業所 ID の取得

freee API のほぼ全てのエンドポイントに company_id（事業所 ID）が必要です。

GET https://api.freee.co.jp/api/1/users/me
Authorization: Bearer ACCESS_TOKEN

レスポンスの companies[].id が事業所 ID です。複数事業所を持っている場合は、対象の事業所を選択してください。

ステップ2: 取引先の検索・作成

請求書を作るには、freee に登録済みの取引先 ID が必要です。

既存の取引先を検索する

GET https://api.freee.co.jp/api/1/partners?company_id=123&keyword=山田商店
Authorization: Bearer ACCESS_TOKEN

レスポンス:

{
  "partners": [
    {
      "id": 456,
      "name": "株式会社山田商店",
      "code": "Y001"
    }
  ]
}

ハマりどころ: 表記揺れ

keyword 検索は部分一致ですが、「（株）山田商店」で検索しても「株式会社山田商店」はヒットしません。検索前に「株式会社」「(株)」「（株）」の正規化をかけることを推奨します。

取引先を新規作成する

freee に未登録の取引先の場合は、先に作成します。

POST https://api.freee.co.jp/api/1/partners
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "company_id": 123,
  "name": "株式会社山田商店",
  "partner_bank_account_attributes": {
    "bank_name": "三菱UFJ銀行",
    "branch_name": "渋谷支店",
    "account_type": "ordinary",
    "account_number": "1234567",
    "account_name": "カ)ヤマダショウテン"
  }
}

ハマりどころ: 取引先の重複

freee は同じ名前の取引先を複数作成できてしまいます。API で自動登録する場合、必ず事前に検索して存在確認をしてください。重複すると、仕訳や請求書が分散して管理が混乱します。

対策としては:

登録前に keyword で検索
該当なし → 新規作成
該当あり → 既存の取引先 ID を使う
複数候補 → 名前の完全一致で絞り込む

ステップ3: 請求書を作成する

取引先 ID が分かったら、請求書を作成します。商品明細も同じリクエストに含められます。

POST https://api.freee.co.jp/api/1/invoices
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "company_id": 123,
  "partner_id": 456,
  "issue_date": "2026-03-31",
  "due_date": "2026-04-30",
  "booking_date": "2026-03-31",
  "payment_type": "transfer",
  "invoice_layout": "default_classic",
  "invoice_contents": [
    {
      "name": "有機トマト（1kg）",
      "quantity": 10,
      "unit_price": 800,
      "tax_entry_method": "inclusive",
      "vat": 8,
      "account_item_id": 789,
      "tax_code": 2
    },
    {
      "name": "配送用段ボール",
      "quantity": 5,
      "unit_price": 300,
      "tax_entry_method": "inclusive",
      "vat": 10,
      "account_item_id": 789,
      "tax_code": 1
    }
  ]
}

主要なフィールドの解説

フィールド	説明	注意点
`partner_id`	取引先 ID	ステップ2 で取得
`issue_date`	請求日	YYYY-MM-DD
`due_date`	支払期日	取引先ごとに異なる。自動計算するなら自分でロジックを書く
`payment_type`	決済方法	`transfer`（振込）、`direct_debit`（引落）等
`invoice_layout`	レイアウト	`default_classic` が一般的

商品明細のフィールド

フィールド	説明	注意点
`name`	商品名	自由テキスト
`quantity`	数量	小数可
`unit_price`	単価	税込 or 税抜は `tax_entry_method` で制御
`vat`	税率	8 or 10
`tax_code`	税区分コード	最大のハマりどころ。後述
`account_item_id`	勘定科目 ID	freee の勘定科目マスタから取得

ハマりどころ詳説

1. 税区分コード（tax_code）

これが一番厄介です。

freee の税区分コードは数十種類あり、同じ 10% でも「課税売上」「課税仕入」「非課税」「不課税」で異なるコードが割り当てられています。

請求書（売上側）で使う主なコード:

内容	tax_code
課税売上 10%	1
課税売上 8%（軽減）	2
非課税売上	6

勘定科目と税区分の組み合わせが不整合だと、API はエラーを返します。例えば、勘定科目が「売上高」なのに税区分が「課税仕入」だとエラーになる。

対策: 税区分コードの一覧は以下のエンドポイントで取得できます。

GET https://api.freee.co.jp/api/1/taxes/codes?company_id=123

自社の勘定科目設定に合わせて、正しいコードをマッピングしてください。

2. 勘定科目 ID（account_item_id）

勘定科目 ID は事業所ごとに異なります。ハードコードせず、API から動的に取得してください。

GET https://api.freee.co.jp/api/1/account_items?company_id=123

「売上高」の勘定科目 ID を使うのが一般的ですが、商品カテゴリごとに勘定科目を分けている場合はそれに合わせる必要があります。

3. 税込・税抜の指定

tax_entry_method には 2 つの値があります。

inclusive: 単価が税込
exclusive: 単価が税抜

元データが税込なのに exclusive を指定すると、二重課税になります。元データの税処理に合わせてください。

4. 日付のフォーマット

全て YYYY-MM-DD 形式。タイムゾーンの指定は不要です。

issue_date（請求日）を未来の日付にすると、freee の管理画面上で「発行予定」として表示されます。

エラーハンドリング

freee API のエラーレスポンスは比較的親切です。

{
  "status_code": 400,
  "errors": [
    {
      "type": "status",
      "messages": ["税区分と勘定科目の組み合わせが不正です"]
    }
  ]
}

よく遭遇するエラー:

HTTP ステータス	原因	対処
400	パラメータ不正（税区分・勘定科目の不整合等）	エラーメッセージを読んで修正
401	アクセストークン期限切れ	refresh_token で再取得
403	スコープ不足	アプリの権限設定を確認
429	レート制限（3,600 req/h）	リトライ間隔を空ける

レート制限は 1 時間あたり 3,600 リクエスト。1 秒 1 リクエストのペースなら問題ありません。大量の請求書を一括作成する場合は、間隔を空けるか、バッチ処理にしてください。

実装の手順まとめ

freee 開発者ページでアプリ登録 → client_id / client_secret を取得
OAuth 2.0 認証 → access_token を取得
事業所 ID を取得 → /users/me エンドポイント
勘定科目・税区分コードを取得 → 自社の設定を確認してマッピングテーブルを作る
取引先を検索 or 作成 → 重複チェックを忘れずに
請求書を作成 → 商品明細を含めて 1 リクエストで登録
エラーハンドリング → 特に税区分の不整合に注意

コード量としては、認証周りが一番重い。請求書作成自体は JSON を POST するだけなので、認証さえ通れば難しくありません。

自分で書くか、ツールに任せるか

ここまで読んで「自分で実装できそうだ」と思った方は、ぜひやってみてください。freee の API はドキュメントも充実していて、開発者フレンドリーです。

ただし、実際に運用し始めると、この記事で解説した以外にも考えることが出てきます。

受注データのソース（COREC、メール、FAX、Excel）ごとのパーサー
取引先の名寄せロジック（表記揺れは無限にある）
支払期日の自動計算（取引先ごとの支払いサイト管理）
トークンの自動リフレッシュ
エラー時のリトライと通知
複数事業所・複数ユーザーの管理

これらを全部自前で書いて保守するのは、本業がソフトウェア開発でない限り、割に合わないかもしれません。

Saturn は、こうした周辺処理も含めて請求書の自動作成を実装しています。COREC の受注データを取り込めば、名寄せ・税率判定・日付変換を経て freee の請求書が自動生成される。API のことを意識する必要はありません。