Diggle と freee の連携方法と設定手順ガイド

1. Diggle と freee の概要と連携のメリット

Diggle はタスク単位で作業時間を計測できる SaaS 型ツールで、プロジェクトごとの工数集計やレポート機能が充実しています。一方、freee は会計・給与・勤怠を一元管理し、仕訳自動化や税務申告までサポートするクラウド基盤です。

両者を連携させると、タスク完了時に記録された工数が即座に freee の仕訳へ反映され、手入力の手間が排除されるだけでなく、経費科目や部門コードとの整合性も保たれます。結果として、作業効率と会計精度が同時に向上します。

1‑1. 主な機能比較

1‑2. 連携で得られる具体的効果

• 工数データの自動同期：タスク完了と同時に freee の「外注費」や「人件費」へ仕訳が生成。
• 月次締め作業の削減：手入力によるミスが激減し、締め前チェックが数クリックで完了。
• リアルタイム可視化：プロジェクト別工数と会計科目を同一ダッシュボードで比較可能。

2. 事前に確認すべき条件と準備

連携設定中に「権限が足りません」や「プランが非対応」といったエラーが出るのは、利用しているプラン・スコープが要件を満たしていないことが原因です。ここでは最新公式情報（2024 年 12 月時点）に基づく要件を整理します。

2‑1. 必要なアカウント権限とプラン要件

※上記プラン要件は 2024 年 12 月時点の情報です。実際に導入する前に各ベンダーの最新プラン表を必ず確認してください。

2‑2. API スコープの選定ポイント

freee の API はスコープ単位で権限を細分化できます。最低限必要なスコープは以下です。

• attendance.read / attendance.write （勤怠データ取得・登録）
• accounting.transactions.create（仕訳作成）
• accounting.accounts.read（科目一覧参照）

不要なスコープを付与しないことで、最小権限の原則 を遵守できます。Diggle 側は 1 つの固定スコープ（diggle.api.full_access）で全機能にアクセスできる設計ですが、将来的に細分化された場合は同様に必要最低限だけを選択してください。

3. freee 側で外部連携を有効化する手順

freee の管理画面から API トークンを取得し、適切なスコープと保存方法を設定します。以下の手順はブラウザ（Chrome/Edge 推奨）で実施してください。

3‑1. API トークン取得手順

1. 管理者としてログイン → 左サイドメニューの「設定」→「連携サービス」をクリック。
2. 「外部アプリ連携」スイッチを ON にする（未オンの場合はエラーメッセージが表示されます）。
3. 【API トークン発行】 ボタンを選択し、ポップアップで以下を設定。
4. トークン名：diggle-sync-2024（任意）
5. 有効期限：デフォルトは 90 日（推奨）。期限切れ前に自動リフレッシュできるようスクリプト化すると便利です。
6. スコープ：attendance.read、attendance.write、accounting.transactions.create、accounting.accounts.read にチェック。
7. 「発行」ボタンをクリックし、表示された シークレット文字列 を必ずコピーしてください（画面遷移後は再表示できません）。

3‑2. トークンの安全な保管方法

推奨：本番環境ではクラウドシークレットマネージャを使用し、CI/CD パイプラインからは環境変数経由で参照する形にすると、コードベースへの漏洩リスクが最小化できます。

4. Diggle 側で接続設定とデータマッピングを行う

freee のトークンを取得したら、Diggle の管理画面で認証情報を登録し、項目の紐付けを行います。

4‑1. 接続情報入力手順

1. Diggle に 管理者 アカウントでログイン。
2. 左メニュー → 「設定」→「外部サービス連携」を選択。
3. 「freee 連携追加」ボタンをクリックし、以下の項目を入力。
4. API エンドポイント：https://api.freee.co.jp（デフォルト）
5. アクセストークン：先ほど取得した freee のシークレット文字列
6. スコープ：attendance.read,attendance.write,accounting.transactions.create,accounting.accounts.read（カンマ区切りで入力）
7. 「認証テスト」ボタンを実行し、「認証成功」 が表示されたら 保存 をクリック。

4‑2. データマッピング例と注意点

• データ型の整合性：Diggle が返す時間は分単位。freee の仕訳 API は金額（整数）を必須とするため、単価 × 時間 (h) に変換するロジックを Diggle 側で設定してください。
• バリデーション：マッピング時に空白や未定義のプロジェクトコードがあると 400 エラーになるので、事前に「未割り当てタスク」用のフォールバック科目（例: 「雑費」）を作成しておくと安全です。

4‑3. 同期スケジュールの設定と推奨値

※ レートリミット は freee の API が 1 分間に最大 60 リクエスト（プランにより変動）です。大量タスクを同時送信する場合はバッチ方式を選択し、スロットリング処理を組み込むことが重要です。

5. 接続テスト、典型的なエラーと対処法

設定完了後は必ず接続テストを実施し、エラーログを確認します。以下に代表的なエラーコードとその解決策をまとめました。

5‑1. テスト実施手順

1. Diggle の「外部サービス連携」画面で対象の freee 接続行を選択し、「接続テスト」 をクリック。
2. 成功時は 200 OK とともに 「認証成功」 メッセージが表示されます。失敗した場合はステータスコードとエラーメッセージがログ領域に出力されます。
3. ログは JSON 形式 で保存できるため、後続のトラブルシューティングに活用してください（例: diggle_freee_test_20240621.log）。

5‑2. エラーパターン一覧

ポイント：エラーが発生した場合、まずは ログのステータスコードとメッセージ を確認し、上表の対処法を順に実施してください。

6. セキュリティベストプラクティス

連携で扱うトークンは「システム間のパスワード」と同等の機密情報です。以下の指針に沿って運用することで、漏洩リスクを最小化できます。

6‑1. トークンローテーションの根拠と実装例

• 根拠：OWASP API Security Project が推奨する「トークンは最大 90 日で更新」(2023 年版) に準拠。長期間同一トークンを使用すると、万が一漏洩した際の被害範囲が拡大します。
• 自動ローテーション例（bash + AWS Secrets Manager）

上スクリプトは CI/CD のジョブ または cron（Linux）/Task Scheduler（Windows） に登録し、90 日ごとに自動実行させます。

6‑2. 最小権限の原則とスコープ設定

• 必要な機能だけを許可するスコープを選択し、不要な accounting.read や company.full_access といった広範囲権限は付与しない。
• 変更が必要になった場合は 追加 のみ行い、削除は必ず レビュー（例えば社内の情報セキュリティ委員会）を経て実施。

6‑3. ログ・監査の確保

7. Zapier と Make を使った代替連携パターン

Diggle が提供する API が利用できない環境（例：無料プランや社内ネットワーク制限）でも、Zapier や Make の Webhook 機能で同様の自動化が可能です。

7‑1. Zapier の設定フロー

注意点

• Zapier の無料プランでは月 100 タスクまでしか実行できないため、利用頻度が高い場合は有料プランへのアップグレードが必須。
• freee API は 1 分間 60 リクエスト が上限なので、Zapier 側で「Delay」アクションを入れ、同時送信数を制御するとレートリミットエラーを回避できる。

7‑2. Make (Integromat) のシナリオ構築例

1. シナリオ作成 → 空のシナリオに名前付与（Diggle→freee 工数同期）。
2. Webhook モジュールを追加し、Custom webhook を選択。生成された URL を Diggle の「Outgoing Webhook」設定に貼り付ける。
3. フィルターモジュールで duration_minutes > 0 のみ通過させ、無駄なリクエストを削減。
4. HTTP リクエストモジュール（freee）を追加し、以下の設定：
   - Method: POST
   - URL: https://api.freee.co.jp/api/v1/accounting/transactions
   - Headers: Authorization: Bearer {{token}}、Content-Type: application/json
   - Body (JSON): { "company_id": "{{company_id}}", "entry_date": "{{today}}", "details": [{ "account_item_id": 12345, "amount": {{duration_minutes}}/60 * {{hourly_rate}}, "description": "{{task_name}}" }] } |
5. エラーハンドリング：HTTP モジュールの「Error handling」タブで Retry on 429（指数バックオフ）と、失敗時に Slack に通知するアクションを設定。
6. スケジューラー：シナリオ実行頻度は「10 分ごと」に設定し、Zapier と同様にレートリミット対策を施す。

注意点

• Make の無料プランは月 1,000 操作までなので、大規模プロジェクトでは有料プランが必要です。
• Webhook ペイロードの Content-Type が application/json であること、エンコードが UTF‑8 であることを必ず確認してください（文字化けは API エラーの原因になる）。

8. まとめ

1. プラン要件とスコープ を公式ドキュメントで最新情報を確認し、freee の Standard 以上・Diggle の Pro 以上が最低条件です。
2. freee の API トークンは 90 日ごとのローテーション と 環境変数／シークレットマネージャ に保存することで安全性を確保します。
3. Diggle 側の接続設定では、認証テストとデータマッピングを慎重に行い、バリデーションエラー を事前に防ぎます。
4. 接続テストで得られるステータスコードはトラブルシューティングの第一手がかりです。代表的なエラーと対処法を表で把握しておきましょう。
5. セキュリティは 最小権限、定期ローテーション、監査ログ の 3 本柱で構築し、OWASP 推奨に沿った運用を心がけます。
6. Zapier や Make を使う代替パターンでも、レートリミット対策 と エラーハンドリング を忘れずに実装すれば、無料プランや API 制限下でも安定した自動化が可能です。

以上の手順とベストプラクティスに従えば、Diggle の工数情報を freee の仕訳へシームレスに連携でき、業務効率化と会計精度向上という二重の効果を実現できます。ぜひ本ガイドを参考に、まずはテスト環境で試験運用から始めてみてください。