Freee 会計 API を使って銀行口座の入金情報と連携する

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

• サービスを提供するとき、小額ならクレジットカード支払いが便利だが、ちょっと大きい金額になると、やはり銀行振込の方が安心ですね
• 一方で、銀行システムと連携すると言われると、導入コスト（費用面と開発コストとも）大きい印象が受けています
• でも実は、Freee の 会計 API を活用すれば、銀行口座への入金情報をシステムに連携することは、意外に気軽にできます。

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

全体の流れ

ステップごとの詳細

前提

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

1. 取引先作成処理

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

2. 請求取引作成処理

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

3. 入金処理（システム外）

• このステップは、システム外の内容であり、全体のフローを説明するために書いています
• 処理内容
  • 得意先はシステムが指定した Freee と連携している銀行口座に振り込む
  • 銀行側の取引が成立したら、Freee にその取引情報を連携する（具体的な連携頻度は不明）
  • Freee システム上は、銀行から連携された取引が自動で登録され、更にシステム上の取引を消込むことができる
    • この辺は会計の知識が必要になるので、本記事では割愛しますが、ここでは単に「銀行から連携された入金取引と、ステップ２で登録した収入取引を紐付けできる」と理解すればよい
  • この紐付け処理で、ステップ２で登録した取引に「入金日、金額」などの入金情報が登録される

4. 入金情報取得（定期的に実行する処理）

• 処理内容

  • 定期的な処理で、システム上の未入金取引に対して、Freee 側の取引情報を取得し、入金情報があるかどうかを確認する。下記のように、取引ごとに、payments という項目に入金情報を取得できる（配列になっているのは、複数回入金も対応できるようです）

  "payments": [
    {
      "id": 202,
      "date": "2013-01-28",
      "from_walletable_type": "bank_account",
      "from_walletable_id": 103,
      "amount": 5250
    }
  ],
  
  

  • 入金情報が入っていれば、「入金日」を取得し、システム上の取引の入金日に設定し、ステータスを入金済みに更新する

• 使う API

  • GET /api/1/deals/:id
  • 必要なデータ
    • Freee 側の取引ID（ステップ２で設定した）

まとめ

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

参考資料

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