Freee の会計 API を活用すれば、銀行の入金情報を気軽にシステムに連携できる

今回は、Freee の会計 API を使って、銀行口座への入金情報をシステムと連携する際、全体的な流れと各ステップごとに使うAPIを説明します。
処理の詳細を全部書くと長くなってしまうので、使う API と注意点だけ書きます。

全体の流れ

システム側の銀行口座の取引詳細を Freee に同期する設定をしておく必要があります
- 同期を設定することで、銀行口座の取引明細情報が Freee 側に同期されます
Freee 会計システムの画面上に、API アクセスするためのリフレッシュトークンとアクセストークンを設定済みであること（設定手順はいくつ記事があるので、割愛します）
- 普段の API リクエストはアクセストークンを使いますが、Freee の仕様としてアクセストークンの有効期限は 24 時間だけなので、期限切れの場合、リフレッシュトークンを使って再度アクセストークンを発行する必要がある
- 注意点：リフレッシュトークントークンを使ってアクセストークンを発行すると、リフレッシュトークン自体も変わるので、両方とも発行あとの値をシステム上に保持しておく必要がある
Freee の API は、ほぼ全部の API に company_id パラメータが必要になっています
- このパラメータは、 Freee システム上の「事務所」になっています
- 実際の使う場合は、１サービスごとに、１事務所になるはずなので、システム上で設定値として保持する必要がある

処理内容
- 得意先の名前や銀行口座の番号などの情報を freee 側に「取引先」として登録する
使う API
- POST /api/1/partners
- 必要なデータ
  - 名前だけ必須項目なので、最小限は名前だけで登録できる
注意点
- 作成したあと、レスポンスに「取引先ID」があるので、それを得意先に保持しておきましょう。ステップ２でこのIDを使います
- 業務上得意先が固定の場合、Freee の画面上で登録しておいて、IDだけシステム上に保持すれば問題ありません
- API を使って登録する場合、ドキュメントに特に書かれていませんが、「取引先名」項目は、ユニーク制限があります。重複が許されないので、「氏名_得意先ID」のようにユニークなIDを入れるほうが良さそうです
- [2020/07/17追記]住所情報を連携する場合は、Freee 側は 県/市区町村・番地/建物名・部屋番号など ３項目だけなので、 県/都市/市区郡村市区町村・番地/建物名・部屋番号 ４つの項目を保持しているシステムの場合、都市の値を市区郡村・番地の頭に入れて連携する必要があります

処理内容
- システム上に業務に従って取引を作成しておく
- システム上発生した取引の内容を Freee 側に登録する
- Freee 側の取引IDをシステム上の取引に紐付いて保持する
使う API
- POST /api/1/deals
- 必要なデータ
  - 発生日
  - 収支区分：income（収入）　# コメント：本記事の場合入金情報を同期するためなので、「収入」にしている
  - 明細行（最小限の項目は税区分、勘定科目、金額）
注意点
- 勘定科目IDは、Freee システム上の「勘定科目」設定にあるレコードの ID の値を使う必要があるが、画面上からはその ID の値を確認する手段がないようで、GET /api/1/account_items API を呼び出して取得する必要がある
- システム上の取引はどの勘定科目を使うべきかは業務次第なので、本記事では割愛します

いくつ注意点と課題がありますが、Freee の会計 API を使えば、銀行との連携も気軽に対応できるので、ありがたいです。