SkillogyQiitaを読む
コラム一覧に戻る

freee APIで会計データを連携するには|できることと開発の進め方

販売管理や受発注のシステムで作った売上データを、毎月CSVに書き出してfreee会計に取り込んでいる。経費の申請はスプレッドシートで受け付け、経理担当者が手で入力し直している。こうした二重入力をなくす方法として検討されるのが、freee APIによる連携です。

freee APIを使うと、自社のシステムからfreee会計に取引を登録したり、freee会計の仕訳や試算表のデータを取り出して分析に使ったりできます。会計システムとの連携を自動化できれば、転記の手間と入力ミスを減らし、月次の締めを早められます。

ただし、APIで送れば何でも正しく記帳されるわけではありません。勘定科目、税区分、取引先、部門、品目といったマスタを自社のシステム側の値とどう対応させるかを決めないまま開発を始めると、登録はできても経理が使えないデータが溜まることになります。

この記事では、freee会計APIで扱えるデータ、認証とアプリの種類、利用制限、連携開発の進め方、よくある注意点を、公式の開発者向けドキュメントの内容をもとに整理します。

freee APIで連携できる会計データ

freee APIで連携できる会計データ

freeeは、会計のほか人事労務、請求書、工数管理、販売などの製品ごとにAPIを公開しています。ここでは会計システムとの連携で使うことが多いfreee会計APIを扱います。公式のAPIリファレンスに掲載されている主なデータは次のとおりです。

データ APIでできること 使われる場面
取引(収入・支出) 一覧の取得、登録、更新、削除。支払行や+更新行の操作 販売管理の売上や、経費の支払いを登録する
振替伝票 一覧の取得、登録、更新、削除 決算整理や、取引の形で表せない仕訳を登録する
仕訳帳 ファイルの作成を依頼し、作成後にダウンロードする(非同期) 仕訳データをまとめて分析基盤に取り込む
試算表などのレポート 貸借対照表・損益計算書の形の集計値を取得する 月次の数字をダッシュボードに表示する
勘定科目、税区分、取引先、部門、品目、メモタグ マスタの取得。取引先・部門・品目などは登録・更新もできる 自社システムの値とfreeeの値を対応づける
口座と明細 銀行口座・クレジットカードなどの口座と、その入出金明細の取得・登録 入出金の状況を確認する
証憑ファイル(ファイルボックス) 領収書などのファイルの登録、取得 申請システムで受け付けた領収書を会計側に渡す
経費申請・各種申請 申請の一覧取得、登録 独自の申請画面からfreeeの申請に流す

使えるAPIは、freee会計の契約プランによって異なります。公式リファレンスによると、Web版で使える機能はAPIでも使えるのが原則ですが、総勘定元帳APIや固定資産台帳APIのように一部のプランに限られるものがあります。部門とは別に集計軸を持てるセグメントタグも、上位のプランでのみ指定できます。連携を設計する前に、自社の事業所の契約プランで必要なAPIが使えるかを確認してください。

なお、請求書と見積書の作成は、インボイス制度への対応に伴ってfreee会計のAPIからfreee請求書のAPIに移っています。請求書の発行まで連携したい場合は、会計とは別のAPIを使うことになります。

参考:会計APIリファレンス/freee Developers Community

参考:【重要】freee会計APIの仕様変更(インボイス制度対応)について/freee Developers Community

認証の仕組みとアプリの種類

認証の仕組みとアプリの種類

freee APIの認証には、OAuth2.0が使われます。公式のスタートガイドでは、Authorization Code Grantという方式が推奨されています。流れを簡単に言うと、freeeの画面で利用者が連携を許可すると認可コードが発行され、それをアクセストークンに交換し、以後のAPIの呼び出しにそのトークンを付けます。

トークンの扱いで押さえておきたい点は次のとおりです。

  • アクセストークンの有効期限は6時間で、期限が切れる前にリフレッシュトークンを使って再取得する
  • 1つのリフレッシュトークンで2回アクセストークンを取得することはできない。再取得のたびに返される新しいリフレッシュトークンを保存し直す必要がある
  • リフレッシュトークンの有効期限は、以前の「有効期限なし」から発行後90日間に変更されている。長期間使われない連携は、利用者に再度許可してもらう必要が出る
  • Client IDとClient Secretは、他人に知られないよう管理する

実務で問題になりやすいのは、2つ目と3つ目です。複数の処理が同時にトークンを更新しようとして古いリフレッシュトークンを使ってしまう、夜間のバッチ処理が止まっている間に期限が切れる、といった理由で連携が止まることがあります。トークンの保存場所を1か所にまとめ、更新を1つの処理に限定する設計にしておくと安全です。

連携用のアプリを作る際には、アプリの種類を選びます。公式のFAQによると、種類は次の2つで、作成後に変更することはできません。

種類 目的 利用できる事業所数 アプリストアへの掲載
プライベートアプリ 特定の事業所での利用 5以下 できない
パブリックアプリ 複数の事業所での利用(配布) 既定では20以下 審査の上で掲載できる

自社の会計データを自社のシステムとつなぐだけならプライベートアプリで足ります。複数の顧客企業に連携機能を提供するサービスを作る場合は、パブリックアプリを選び、事業所数の上限やアプリストアへの掲載の要否を早めに確認しておきます。開発用のテスト事業所ではプライベートアプリしか作れない点にも注意が必要です。

参考:アクセストークンを取得する/freee Developers Community

参考:アプリについて/freee Developers Community

利用制限と大量データを扱うときの考え方

利用制限と大量データを扱うときの考え方

freee会計APIには、呼び出し回数の制限があります。公式リファレンスに記載されている内容は次のとおりです。

制限の種類 内容
1日のAPIコール数(事業所とアプリごと) 法人エンタープライズプランは10,000回、法人アドバンスプラン(および旧法人プロフェッショナルプラン)は5,000回、それ以外は3,000回
レポートのAPI 1秒に10回まで。超えるとステータスコード429が返る
証憑ファイルのダウンロード 1秒に3回まで。超えるとステータスコード429が返る
一定期間の過度なアクセス ステータスコード403で制限され、10分程度で解除される

一覧を取得するAPIは、1回に取得できる件数が決まっています。たとえば取引の一覧は、既定で20件、最大で100件ずつ取得します。月に数千件の取引がある事業所のデータを全件取り直す処理を毎日動かすと、ページ送りの回数だけで1日の上限に近づくことがあります。

大量のデータを扱う場合は、次のように設計します。

  • 毎回全件を取り直さず、発生日や更新日で範囲を絞って差分だけを取得する
  • 仕訳をまとめて分析に使う場合は、取引を1件ずつ取得するより、仕訳帳のファイル作成APIで一括して受け取る方法を検討する
  • 429や403が返ったときは、時間を置いて再試行する処理を入れる
  • 同じ事業所に複数の連携アプリがある場合、それぞれの呼び出しを合計して上限に収まるかを見ておく

また、公式リファレンスでは、新しい項目の追加やレスポンスの項目の順番の変更などは、後方互換性のある変更として通知なく行われることがあると明記されています。知らない項目が返ってきても処理が止まらないように実装しておくことが前提です。

freee API連携の開発の進め方

freee API連携の開発の進め方

会計システムとの連携には、APIで個別に開発する以外にも、CSVの取り込み機能を使う方法や、freeeのアプリストアに掲載されている既製の連携アプリを使う方法があります。個別開発を選ぶ前に、次の基準で比べておくと無駄がありません。

状況 向いている方法
月の件数が少なく、月1回まとめて取り込めばよい CSVの取り込み。開発費がかからない
使っている販売管理やECのサービスに既製の連携アプリがある 既製の連携アプリ。対応範囲と月額を確認する
自社開発のシステムや、既製の連携がないサービスとつなぎたい APIで個別に開発する
会計データを取り出して分析基盤やダッシュボードに使いたい APIで取得する処理を開発する。既製のデータ連携ツールが対応していればそれも候補

APIで開発する場合の進め方は、おおむね次のとおりです。

  1. 連携の方向(freeeへ登録するのか、freeeから取得するのか)と、対象のデータ、頻度を決める
  2. 今の手作業の入力を、どの勘定科目・税区分・取引先・部門・品目で行っているかを経理担当者と洗い出す
  3. 自社システムの値とfreeeのマスタの対応表を作る
  4. テスト事業所を使って、登録と取得の処理を試作する
  5. 実際の1か月分のデータで登録し、経理担当者が帳簿と試算表を確認する
  6. エラー時の通知、再実行の方法、二重登録を防ぐ仕組みを入れて本番に切り替える

freeeからデータを取り出して分析に使う場合は、登録とは別の設計になります。仕訳帳のファイル作成APIは、freee汎用形式のCSVや弥生会計形式のCSV、PDFといった出力形式を選べ、汎用形式では文字コードを指定しない場合はShift_JISで出力されます。分析基盤に取り込む処理では、文字コードの変換と、会計年度をまたぐ期間の指定(指定しない場合は当期の開始日と終了日が自動で設定される)に注意してください。

2番目と3番目は、開発会社だけでは決められません。どの取引をどの勘定科目で処理するかは会計の方針であり、顧問の税理士の確認が必要なこともあります。発注側が最初に用意すべきなのは、仕様書よりも、この対応表の元になる「今どう入力しているか」の実例です。

5番目の確認も省かないでください。APIでの登録が成功していても、税区分の選び方が違って消費税の集計がずれている、といった問題は帳簿を見ないと分かりません。

連携で起きやすい問題と対策

連携で起きやすい問題と対策

freee APIの連携で起きやすい問題の多くは、プログラムの不具合ではなく、マスタと会計処理の取り決めの不足から生まれます。代表的なものと対策は次のとおりです。

起きやすい問題 原因 対策
消費税の集計が合わない 取引の明細ごとに税区分の指定が必須で、軽減税率や非課税の区別を連携元が持っていない 商品や費目ごとに税区分を決めた対応表を作り、連携元のマスタに持たせる
金額が税抜で登録される 取引の明細の金額は税込で指定する仕様だが、連携元が税抜の金額を持っている どちらの金額を送るかを仕様に明記し、消費税額の端数の扱いを経理と決める
部門別・品目別の集計ができない 部門や品目を指定せずに登録している 部門・品目の要否を決め、自社システムのコードとfreeeのIDを対応づける
同じ取引が二重に登録される エラー後の再実行で、登録済みのものを再送している 自社システム側に登録済みの記録とfreee側のIDを残し、再送の前に確認する
取引先が重複して増える 表記の違う同じ取引先を、新規として自動登録している 取引先は自動登録せず、対応表で既存のものに紐づける。コードで管理する
しばらくして連携が止まる トークンの期限切れ、マスタの削除、プランの変更 失敗時に担当者へ通知し、原因を画面やログで確認できるようにする

取引先、部門、品目などは、IDで指定する方法のほかに、事業所の設定でコードの利用を有効にすればコードでも指定できます。freee側のIDは事業所ごとに振られるため、テスト事業所と本番の事業所では同じ取引先でも値が異なります。自社システムのコードで管理したい場合は、コードの利用を有効にしたうえで、対応表をコードで作っておくと移行が楽になります。

また、経理担当者がfreeeの画面で勘定科目や部門を整理すると、連携側の対応表が古くなります。マスタを変更するときは連携の担当者にも知らせる、という運用ルールを最初に決めておきましょう。

まとめ

まとめ

freee会計APIでは、取引や振替伝票の登録、仕訳帳や試算表の取得、勘定科目・税区分・取引先・部門・品目などのマスタの取得ができます。認証はOAuth2.0で、アクセストークンは6時間で期限が切れ、リフレッシュトークンは1回しか使えないため、トークンの更新を確実に行う設計が必要です。1日のAPIコール数には、プランに応じて事業所とアプリごとに3,000〜10,000回の上限があります。

連携の成否を分けるのは、APIの実装よりも、自社システムの値とfreeeのマスタの対応表です。とくに税区分、税込・税抜の金額、部門と品目の扱いは、経理担当者や税理士と決めておく必要があります。

明日からできることとしては、連携したい取引を1か月分選び、それぞれをfreeeでどの勘定科目・税区分・取引先・部門・品目で入力しているかを一覧にしてみてください。この一覧があれば、CSVの取り込みで足りるのか、既製の連携アプリで済むのか、APIで開発すべきかを判断でき、開発を依頼する場合も見積もりの精度が上がります。