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

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

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

## 全体の流れ
![freee.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4777/7fbe9140-c8d8-b97c-2a4f-8afc5dc1fadd.png)

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

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

### 2. 請求取引作成処理
- 処理内容
    - システム上に業務に従って取引を作成しておく
    - システム上発生した取引の内容を Freee 側に登録する
    - Freee 側の取引IDをシステム上の取引に紐付いて保持する
- 使う API
    - [POST /api/1/deals](https://developer.freee.co.jp/docs/accounting/reference#/Deals/create_deal)
    - 必要なデータ
        - 発生日
        - 収支区分：income（収入）　# コメント：本記事の場合入金情報を同期するためなので、「収入」にしている
        - 明細行（最小限の項目は税区分、勘定科目、金額）
- 注意点
    - 勘定科目IDは、Freee システム上の「勘定科目」設定にあるレコードの ID の値を使う必要があるが、画面上からはその ID の値を確認する手段がないようで、[GET /api/1/account_items](https://developer.freee.co.jp/docs/accounting/reference#/Account%20items/get_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](https://developer.freee.co.jp/docs/accounting/reference#/Deals/get_deal)
    - 必要なデータ
        - Freee 側の取引ID（ステップ２で設定した）

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

## 参考資料
- 公式 API ドキュメント：https://developer.freee.co.jp/docs