freeagent-api

FreeAgent API オーケストレーションスキル

FreeAgent は、フリーランスや小規模事業者向けのオンライン会計システムです。このスキルは、FreeAgent API リソースへの適切なナビゲーションと、一般的なワークフローのオーケストレーションを提供します。

セキュリティと認可

このスキルは、実際の財務データを扱います。以下のルールは必須であり、決して省略してはいけません。

書き込み操作のポリシー（POST / PUT / DELETE）

状態を変更する API 呼び出しを実行する前に、次の手順を行ってください。

1. プレビューを表示する — リクエスト全体（HTTP メソッド、エンドポイント、JSON 本文）を表示し、アカウント内で何が変更されるのかを平易な言葉で正確に説明します。
2. 明示的な確認を待つ — ユーザーが明確に肯定する返答（例：「はい」、「確認しました」、「進めてください」）をするまで、先に進んではいけません。曖昧な返答は否定として扱います。
3. デフォルトではサンドボックスを使用する — ユーザーが本番環境を明示的に指定しない限り、すべての書き込み操作で https://api.sandbox.freeagent.com/v2/ を使用します。

読み取り専用がデフォルト

ユーザーがデータの作成、更新、または削除を明示的に求めない限り、受け取ったすべてのリクエストを読み取り専用の分析として扱います。意図が曖昧な場合は、変更を行う前に確認してください。書き込みの意図を推測してはいけません。

高リスク操作（2 回確認）

以下の操作では、プレビューを表示して一度確認を受けた後、実行前にもう一度確認してください。

• 財務記録（請求書、経費、銀行取引、連絡先など）の削除
• 銀行取引または照合記録の作成・変更
• 1 回のリクエストで複数のレコードに影響する一括操作
• 請求書のステータス変更（例：送信済みとしてマークする、無効にする、クレジットノートを適用する）

トークンと認証情報の取り扱い

• FREEAGENT_ACCESS_TOKEN または FREEAGENT_REFRESH_TOKEN の値を記録、エコー、表示してはいけません。
• 認証情報をソースコードに保存してはいけません。環境変数のみを使用します。
• トークンの有効期限切れが疑われる場合（401 レスポンス）は、通知せずに更新を試みるのではなく、再認証の手順をユーザーに案内します。

クイックリファレンス：必要なリソースはどれですか？

タスク	読み込むリソース	API ドメイン
OAuth の設定、トークンの管理、API のテスト	resources/authentication-setup.md	OAuth 2.0、トークン管理
連絡先の作成・更新、クライアント・サプライヤーの管理	resources/contacts-organizations.md	連絡先、企業、ユーザー
請求書、プロジェクト、経費、タイムスリップの管理	resources/accounting-objects.md	中核となる財務エンティティ
銀行口座、取引、照合	resources/banking-financial.md	銀行業務、キャッシュフロー
エラー処理、レート制限、再試行、キャッシュ	resources/advanced-patterns.md	本番環境でのパターン
一般的なワークフロー、コード例、統合のヒント	resources/examples.md	実際の使用例
すべてのエンドポイント（リファレンスのみ）	resources/endpoints.md	API 完全リファレンス

オーケストレーションプロトコル

フェーズ 1：タスクの分析

ユーザーが必要としていることを特定します。

リソースの種類別：

• 認証の問題ですか？ → authentication-setup.md
• 連絡先・クライアントの管理ですか？ → contacts-organizations.md
• 財務データ（請求書、経費、プロジェクト）ですか？ → accounting-objects.md
• 銀行業務・照合ですか？ → banking-financial.md
• エラーまたは本番環境に関する懸念ですか？ → advanced-patterns.md
• 実用的な例が必要ですか？ → examples.md

HTTP メソッド別：

• GET：一覧表示または取得 → 該当するドメインのリソースを確認
• POST：作成 → リソースファイルを読み込み、必須フィールドを確認
• PUT：更新 → リソースファイルを読み込み、パッチフィールドを確認
• DELETE：削除 → リソース固有の制約を確認

フェーズ 2：リソースの確認

適切なリソースファイルを読み込み、次の手順を行います。

1. エンドポイントのセクション（例：「連絡先」、「請求書」、「銀行口座」）を見つけます。
2. 必須・任意のパラメーターを確認します。
3. リクエストとレスポンスの形式を確認します。
4. 提供されている curl または Python の例を使用します。

テンプレートコードには、templates/api-request-template.sh（bash）または templates/python-client.py（Python）を使用します。

フェーズ 3：実行と検証

API 呼び出しの前：

• 認証が設定されていることを確認します（必要に応じて authentication-setup.md を確認してください）
• 必須フィールドがすべて指定されていることを検証します
• 日付は ISO 8601（YYYY-MM-DD）、タイムスタンプは（YYYY-MM-DDTHH:MM:SSZ）形式にします
• 正しいリソース URL を使用します（例：https://api.freeagent.com/v2/contacts/123）
• POST / PUT / DELETE の場合： 書き込み操作ポリシーに従い、実行前にプレビューを表示して、ユーザーから明示的な確認を得ます。ユーザーが本番環境を明示的に指定していない限り、サンドボックス URL を使用してください。

API 呼び出し中：

• テンプレートを出発点として使用します
• レート制限ヘッダー X-RateLimit-Remaining を監視します
• 429 エラーに対する再試行ロジックを実装します（advanced-patterns.md を参照）

API 呼び出しの後：

• レスポンスのステータスコードを確認します
• JSON レスポンスを解析します（リソース名は最上位のキーです）
• 必要に応じてエラー処理パターンを適用します

クイックスタート：認証

1. OAuth アプリを作成します：https://dev.freeagent.com/
2. 認証コードを取得します：https://api.freeagent.com/v2/approve_app?client_id=YOUR_ID
3. https://api.freeagent.com/v2/token_endpoint でトークンと交換します
4. 環境変数 FREEAGENT_ACCESS_TOKEN、FREEAGENT_REFRESH_TOKEN に保存します
5. すべてのリクエストに含めます：Authorization: Bearer $FREEAGENT_ACCESS_TOKEN

→ 詳しい手順については、認証とセットアップを参照してください

API ドメインの概要

本番 URL： https://api.freeagent.com/v2/ サンドボックス URL： https://api.sandbox.freeagent.com/v2/（本番環境に影響を与えずにテストできます）

ドメイン	主なエンドポイント	用途
認証	/token_endpoint	OAuth フロー、トークンの更新
連絡先と組織	/contacts、/company、/users	クライアント／サプライヤーの管理
会計オブジェクト	/invoices、/projects、/expenses、/timeslips、/estimates、/credit_notes	中核となる財務ワークフロー
銀行と財務	/bank_accounts、/bank_transactions、/categories、/tasks	キャッシュフロー、照合

レート制限： 1 分あたり 120 リクエスト、1 時間あたり 3600 リクエスト レスポンス形式： リソースラッパーを含む JSON（例：{"contact": {...}} または {"contacts": [...]}）

一般的な HTTP パターン

操作	メソッド	例
項目の一覧表示	GET	GET /v2/contacts?view=active&page=1&per_page=100
1 件の項目を取得	GET	GET /v2/contacts/123
項目の作成	POST	POST /v2/contacts（JSON ボディを指定）
項目の更新	PUT	PUT /v2/invoices/456（部分的な JSON を指定）
項目の削除	DELETE	DELETE /v2/timeslips/789
結果のフィルタリング	GET パラメーター	?view=open_or_overdue、?updated_since=2025-01-01T00:00:00Z

テンプレートとコード例

Bash/cURL テンプレート： templates/api-request-template.sh

• あらゆるエンドポイントに使える柔軟な curl テンプレート
• GET/POST/PUT/DELETE に対応
• ヘッダーとパラメーターを設定可能

Python クライアント： templates/python-client.py

• 再利用可能な FreeAgentClient クラス
• エラー処理とレート制限に対応
• よく使うリソース向けの便利なメソッド

実践例： resources/examples.md

• 実際のワークフロー（請求書の作成、タイムスリップの記録など）
• クライアントクラスを使った Python コードパターン
• エラー処理の例
• 一括操作（インポート／エクスポート）

リソースファイルの概要

ファイル	行数	内容
authentication-setup.md	~180	OAuth のセットアップ、トークン管理、セキュリティ
contacts-organizations.md	~250	連絡先の CRUD、一括操作、会社情報
accounting-objects.md	~350	請求書、プロジェクト、経費、タイムスリップ、ページネーション
banking-financial.md	~250	銀行口座、取引、照合、カテゴリ
advanced-patterns.md	~350	エラー処理、レート制限、再試行、キャッシュ、検証
examples.md	~400	実践的なコード例、統合パターン
endpoints.md	~300	API リファレンスの全一覧（すばやく調べる際に使用）

トラブルシューティングのクイックリンク

401 Unauthorized → 認証の設定 422 Validation Error → 高度なパターン 429 Rate Limit → 高度なパターン 特定のエンドポイントに関するヘルプ → 上記の関連するドメインリソースファイルを確認してください

---

注意： 現在のタスクに必要なリソースファイルのみを読み込んでください。まず上記のクイックリファレンステーブルを確認し、回答を含むリソースを特定してください。