freee API スタートガイド

以下の手順に沿ってfreee APIの活用をはじめてみよう

ここでは最初のfreee APIコールをするためのテスト事業所やテストアプリケーション（以下の図の黄色）を作成するステップを説明していきます。

業務で利用する事業所に紐づくアプリケーションは別途チュートリアルを参照して作成してください。
通常業務ではエンジニアをしておらず、業務改善のためにAPIを活用してみたい方はノンエンジニア向けコンテンツも併せて活用してください。

ステップ

セットアップ：freeeアカウント、開発用テスト事業所、開発用テストアプリを作成する
- テスト事業所で、freeeにテストデータを入れたり、テストしたい設定にしたうえでAPIのレスポンスやデータ登録のテストができます。
- テストアプリでfreee APIを利用するのに必要な情報(client ID, secret, 認可コード、アクセストークン)を発行および管理できます。
APIを叩いてみる：APIリファレンスページを活用して、ブラウザからAPIをコールする
アプリケーション連携を実装する：ユースケースやSDKなどを学び、freeeとの連携を設計および実装していく

1.セットアップ

開発用テスト事業所、開発用テストアプリを作成します。
1. freeeアカウントをお持ちの方（お持ちでない方は次の”お持ちでない方” に移動してください）
  - 上記リンクからAPIコールに必要なアクセストークンを発行するための準備をします
2. freeeアカウントをお持ちでない方
  1. 無料の開発者向けアカウントをあわせて作成します
    - 上記操作を行ったブラウザとメーラーが異なる場合はメールのリンク（メール認証を開始）をコピーして操作を行ったブラウザで作業を続けます
  2. メール認証（メールアドレスが実在することを確認）を行います
以下の件名のメールが届きます。アクセストークン取得ページへのリンクをたどります
```
[freee API] 開発用テスト事業所の作成完了のお知らせ
```

2.最初のAPIコール（ブラウザから）

セットアップの最後の画面に表示されたアクセストークンをコピーします
会計APIリファレンスページの事業所一覧の取得に移動して右側にある鍵アイコンを押下します。
- APIをブラウザから呼び出すための準備です。

freee人事労務をお使いの方は、人事労務APIリファレンスのログインユーザの取得付近までスクロールして鍵アイコンを押下します

コピーしておいたアクセストークンを入力してAuthorizeを押下してCloseを押下します

多くのAPIで事業所ID(company_id)は必須となりますので、まずはその情報を取得してみましょう

freee会計 APIリファレンス内のCompanies（事業所）で、Try it outを押下、次にExecuteを押下し、以下のAPIレスポンスのパート(Server response)を確認してcompany_idを記録します

これで最初のAPIコールができました！
idの箇所に数字が入っています。この例ではYOUR_COMPANY_IDですが実際のIDは数字です

事業所ID(id属性, company_id)を活用し、Companies以外のエンドポイントで取引(deals)情報の参照ができるのか確認してみましょう

Try it outを押下し、Executeを押下し、以下のAPIレスポンスのパート(Server response)を確認する流れはどのAPIでも同じです。
事業所情報の参照だけでなく、取引(deals)登録をしてみたい場合はチュートリアルを参照して取引を登録してみましょう
エラーが出たら？
- APIを試す中でアクセス権限がない旨のエラーが出た場合、アプリ管理 > アプリ詳細でアプリの権限設定で権限を変更（勘定科目の参照や更新を可能にするなど）します。そのあと、上記の2-1の手順でアクセストークンを再発行して再度Authorizeを実行してみましょう

アクセストークンの有効期限が切れたら？

APIレスポンスに以下のエラーメッセージが含まれるようになります。
- ```
アクセスする権限がありません
```
APIレスポンスに以下のエラーコードが含まれるようになります。
- ```
expired_access_token
```
APIコールが正常にできなくなり、エラーとなります。アクセストークンを再度取得するか、リフレッシュトークンを利用してアクセストークンを更新します。
- アクセストークンを再度取得する場合、以下のURLの●をclient_idに入れ替えてアクセストークンを新たに取得します。client_idはアプリ管理 > アプリ詳細で確認できます。
- ```
https://accounts.secure.freee.co.jp/public_api/authorize?client_id=●&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=token
```

3.アプリケーション連携を実装する

API TIPSを参考に、ユースケースごとの連携の概要を学びます
- 例えば SFA、CRM、販売管理システムからfreee会計への連携やエクセルやgoogle spreadsheetからの連携を参照します
- ECサービスやPOSレジとの連携は設計ガイドラインを参照します
- 人事労務であれば、様々な入力インターフェイスからfreee人事労務へ勤怠を入力するや入退社情報を利用して別サービスのアカウントを管理するを参照します
ノンエンジニアの方
- ノンエンジニアのためのfreee会計 API活用講座
  - Google Spreadsheetから会計APIを活用するための簡易講座を参考にカスタマイズをスタートしましょう。
  - 講座内容をレジュメやサンプルも含めて公開しています
実利用向け事業所がすでにある場合はその事業所を活用、ない場合は事業所を新しく作成します
- セットアップで作成したのは開発者向けテスト事業所のため活用不可
- 事業所に紐づくアプリも別途アプリストアのアプリ管理で作成して、Client IDやSecretなど必要情報を取得、またコールバックURLを設定してアクセストークンやリフレッシュトークンを取得してください
API リファレンスを参照し、躓いた場合は freee Developer Community で質問してみましょう

「freee Developer Community」では迷った時、コミュニティページから質問を投稿することができます。コミュニティではAPIリファレンスだけでは分からない使い方や、もっと◯◯な使い方できないの？という疑問にfreeeのテクニカルサポートメンバーや他のメンバーが中心となってお答えします。
※投稿にはfreee Developer communityメンバー登録が必要です。

連携事例やユーザーの声を知ろう

APIで「freeeをもっと便利に使いたい」「新しいサービスを開発して販売したい」だけど、何かアイディアがほしい、ニーズが知りたいという声に答えていきます。
他社がどういった使い方をしているかを知って、freeeをより便利に活用してください。

freee Developer communityメンバー登録の特典2つ

APIのアップデート情報の通知を受け取ることができます。
APIベータ版の先行利用できます。

以下も併せて参照してください

freeeの基本的な使い方
- freee会計を中心に、基本的な使い方や活用方法を学べるコンテンツのリンク集です。freeeについて知りたい方は、こちらをご覧ください。
freee APIスタートガイド
- 最初のAPIコールに必要な環境準備とセットアップ、ブラウザでのAPIコールの方法などについて触れています。
freee会計 API概要
- freee会計 APIでできることを確認できます。事業所や取引、勘定科目、取引先の情報から経費精算申請の下書きの作成や更新について触れています。
freee会計 APIリファレンス
- freee会計 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
freee請求書 API概要
- freee請求書 APIでできることを確認できます。請求書、見積書の作成や更新について触れています。
freee請求書 APIリファレンス
- freee請求書 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
freee人事労務 API概要
- freee人事労務 APIでできることを確認できます。従業員一覧、日時勤怠、月次勤怠からタイムレコーダーの登録や取得について触れています。
freee人事労務 APIリファレンス
- freee人事労務 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
freee工数管理API概要
- freeeスマート受発注 APIでできることを確認できます。
freee工数管理 APIリファレンス
- freee工数管理APIの仕様を確認できます。