freeagent-api

FreeAgent API 编排技能

FreeAgent 是一款面向自由职业者和小型企业的在线会计系统。此技能可智能导航至 FreeAgent API 资源，并编排常见工作流。

安全与授权

此技能会处理实时财务数据。以下规则为强制要求，绝不可跳过。

写入操作策略（POST / PUT / DELETE）

执行任何会改变状态的 API 调用前：

1. 显示预览 — 展示完整请求（HTTP 方法、端点、JSON 正文），并用通俗语言准确说明用户账户将发生哪些变化。
2. 等待明确确认 — 在用户给出明确肯定答复（例如“是”“确认”“继续”）前，不得执行。模棱两可的答复视为否定。
3. 默认使用沙盒环境 — 除非用户明确指定生产环境，否则所有写入操作都使用 https://api.sandbox.freeagent.com/v2/。

默认只读

除非用户明确要求创建、更新或删除数据，否则将所有收到的请求视为只读分析。意图不明确时，先询问再进行任何更改，绝不可自行推断用户有写入意图。

高风险操作（确认两次）

对于以下操作，先显示预览并获得一次确认，然后在执行前再次询问：

• 删除任何财务记录（发票、支出、银行交易、联系人等）
• 创建或修改银行交易或对账记录
• 在单个请求中影响多条记录的批量操作
• 更改发票状态（例如，将发票标记为已发送、作废或应用贷项通知单）

令牌与凭据处理

• 绝不记录、回显或显示 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	现金流、对账

速率限制： 每分钟 120 个请求，每小时 3600 个请求 响应格式： 带资源包装器的 JSON（例如，{"contact": {...}} 或 {"contacts": [...]}）

常见 HTTP 模式

操作	方法	示例
列出项目	GET	GET /v2/contacts?view=active&page=1&per_page=100
获取单个项目	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

• 真实工作流（创建发票、记录 timeslip 等）
• 使用客户端类的 Python 代码模式
• 错误处理示例
• 批量操作（导入／导出）

资源文件摘要

文件	行数	重点
authentication-setup.md	~180	OAuth 设置、令牌管理、安全
contacts-organizations.md	~250	联系人 CRUD、批量操作、公司信息
accounting-objects.md	~350	发票、项目、费用、timeslip、分页
banking-financial.md	~250	银行账户、交易、对账、类别
advanced-patterns.md	~350	错误处理、速率限制、重试、缓存、验证
examples.md	~400	实用代码示例、集成模式
endpoints.md	~300	完整 API 参考（可用于快速查询）

故障排除快速链接

401 未授权 → 身份验证设置 422 验证错误 → 高级模式 429 速率限制 → 高级模式 特定端点帮助 → 查看上方相关领域的资源文件

---

**请记住：**仅加载当前任务所需的资源文件。从上方的快速参考表开始，确定哪个资源包含所需答案。