freee APIとGASを使って商品が購入されたら自動で仕訳登録する (前編)

はじめに

bocci bocciを運営している@shoji-kaiです。
最近では、「AI」「SDGs」「DX」などの言葉が氾濫しており猫も杓子もとった感がありますが、農業界もご多分に漏れず「農業DX構想」なるものが農林水産省より発表されております。

bocci bocciでも積極的にDX化を進めているところであり(#好きでやっているだけ)、
今回は経理のDX化にチャレンジしてみたいと思います。

毎年、年度末になると夏休みの最終日のように慌てて確認申告の準備をしているわけですが、
エンジニアたるもの、煩雑な定型業務はRPA(Robotic Process Automation)化したいところです。
そこで、ここでは商品が購入されたら自動で仕訳登録する処理を作ってみようと思います。

クラウド会計ソフトはAPIが整備されている freee を採用しました。
私のショップの場合、購入されるとGmailにメールが届くので、GAS(Google Apps Script)で定期的にポーリングして商品が購入されていたらfreee APIをたたくイメージです。

今回は文章が長くなってしまったので、前編(freee API編)・中編(GAS編)・後編(実践編)の3部構成にしようと思います。
それでは、まずはfreee APIのほうから見ていきます。

freee APIのセットアップ

freee API スタートガイドに沿ってやっていきます。

1. 開発用アカウントの作成

こちらより開発用アカウントを作成します。
freeeから案内される手順に沿っていくとアクセストークンを取得できます。
これ以降の説明では自分のアクセストークンを$ACCESS_TOKENとして表記しますので、適宜ご自身の環境に置き換えてお読みください。

2. company_idの取得

はじめてのAPIとしてcompany_idを取得してみます。
ブラウザから実行することもできますが、ここではCLIで行います。

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://api.freee.co.jp/api/1/companies | jq -r

以下のようなデータが返ってきたら成功です。

{
  "companies": [
    {
      "id": <company_id>,
      "name": null,
      "name_kana": null,
      "display_name": "開発用テスト事業所",
      "role": "admin"
    }
  ]
}

company_idはこれ以降も使用するので環境変数に保存しておきます。

export COMPANY_ID=<company_id>

3. 取引データを登録する

次に、以下の取引を想定したデータを登録してみます。

2020年11月1日に1,000円の文具を購入するというケースで、勘定科目は事務用品費、税区分は消費税10%の課対仕入で取引登録します。

勘定科目IDの取得

まずは事務用品費の勘定科目IDを調べるため、勘定科目IDの一覧を取得します。

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.freee.co.jp/api/1/account_items?company_id=$COMPANY_ID"

大量のJSONデータが返ってきます。ここでは見やすいようにjqコマンドで事務用品費のみ抽出します。

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.freee.co.jp/api/1/account_items?company_id=$COMPANY_ID" | \
  jq -r '.account_items[] | select(.name == "事務用品費")'

事務用品費の勘定科目IDが取得できました。

{
  "id": 538987945,   # <= 勘定科目ID
  "name": "事務用品費",
  "tax_code": 34,
  "shortcut": "JIMUYOU",
  "shortcut_num": "711",
  "default_tax_id": 439551147,
  "account_category_id": 32,
  "corresponding_income_name": "未収収益",
  "corresponding_expense_name": "未払金",
  "corresponding_income_id": 538987866,
  "corresponding_expense_id": 538987903,
  "group_name": "消耗品費",
  "group_id": 446605175,
  "default_tax_code": 136,
  "account_category": "経費",
  "categories": [
    "資本",
    "差引損益計算",
    "営業損益",
    "経費"
  ],
  "available": true,
  "walletable_id": null
}

税区分コードの取得

「消費税10%の課対仕入」の税区分コードを取得します。
こちらもjqコマンドで必要な項目のみ抽出します。

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.freee.co.jp/api/1/taxes/codes" | \
  jq -r '.taxes[] | select(.name_ja == "課対仕入10%")'

税区分コードが取得できました。

{
  "code": 136,   # <= 税区分コード
  "name": "purchase_with_tax_10",
  "name_ja": "課対仕入10%"
}

取引データを登録する

勘定科目IDと税区分コードが取得できたので、実際に取引データを登録してみます。
取引データを登録するには、さらにtype(収支区分)、issue_date(発生日)、details[].amount(取引金額）の情報が必要です。
実際のデータは以下のようになります。

{
  "issue_date": "2020-11-01",   # 発生日
  "type": "expense",            # 収支区分 (income:収入、expense:支出)
  "company_id": $COMPANY_ID,    # 会社ID
  "details": [
    {
      "tax_code": 136,                             # 税区分コード
      "account_item_id": 538987945,                # 勘定科目ID
      "amount": 1100,                              # 取引金額
      "description": "ノートとボールペンをコンビニで購入"   # 備考 (オプション)
    }
  ]
}

必須項目以外にdescription(備考)も追加してみました。
その他、設定可能な項目については APIリファレンス から確認できますので、詳細はそちらをご参照ください。

それでは、こちらのデータを実際に登録してみます。

cat <<. | curl -s -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.freee.co.jp/api/1/deals" -d @- | jq -r
{
  "issue_date": "2020-11-01",
  "type": "expense",
  "company_id": $COMPANY_ID,
  "details": [
    {
      "tax_code": 136,
      "account_item_id": 538987945,
      "amount": 1100,
      "description": "ノートとボールペンをコンビニで購入"
    }
  ]
}
.

以下のようなデータが返ってきたら成功です。

{
  "deal": {
    "id": 1019688438,
    "company_id": <company_id>,
    "issue_date": "2020-11-01",
    "due_date": null,
    "amount": 1100,
    "due_amount": 1100,
    "type": "expense",
    "partner_id": null,
    "partner_code": null,
    "ref_number": "",
    "status": "unsettled",
    "details": [
      {
        "id": 2706491703,
        "account_item_id": 538987945,
        "tax_code": 136,
        "item_id": null,
        "section_id": null,
        "tag_ids": [],
        "amount": 1100,
        "vat": 100,
        "description": "ノートとボールペンをコンビニで購入",
        "entry_side": "debit"
      }
    ],
    "receipts": []
  }
}

念の為、freeeの画面からも取引データが登録されていることを確認してみましょう。
freee会計 > レポート > 仕訳帳で取引日を2020-11-01に指定すると確認できます。

おわりに

以上でfreee APIのセットアップと基本的な使い方が分かったかと思います。
次回はGASを使ってfreee APIを叩くところまでをやってみます。