Back to Details

freeagent-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

FreeAgent API Orchestration Skill

FreeAgent API编排技能

FreeAgent is an online accounting system for freelancers and small businesses. This skill provides intelligent navigation to FreeAgent API resources and orchestrates common workflows.
FreeAgent是面向自由职业者和小企业的在线会计系统。本技能提供对FreeAgent API资源的智能导航，并编排常见工作流。

Quick Reference: Which Resource Do I Need?

快速参考：我需要哪个资源？

TaskLoad ResourceAPI Domains
Set up OAuth, manage tokens, test API
resources/authentication-setup.md
OAuth 2.0, token management
Create/update contacts, manage clients/suppliers
resources/contacts-organizations.md
Contacts, companies, users
Manage invoices, projects, expenses, timeslips
resources/accounting-objects.md
Core financial entities
Bank accounts, transactions, reconciliation
resources/banking-financial.md
Banking, cash flow
Error handling, rate limits, retries, caching
resources/advanced-patterns.md
Production patterns
Common workflows, code examples, integration tips
resources/examples.md
Real-world usage
All endpoints (reference only)
resources/endpoints.md
Complete API reference
任务加载资源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参考

Orchestration Protocol

编排协议

Phase 1: Task Analysis

阶段1：任务分析

Identify what the user needs:
By Resource Type:
  • Authentication issue? → 
    authentication-setup.md
  • Managing contacts/clients? → 
    contacts-organizations.md
  • Financial data (invoices, expenses, projects)? → 
    accounting-objects.md
  • Banking/reconciliation? → 
    banking-financial.md
  • Error or production concern? → 
    advanced-patterns.md
  • Practical example needed? → 
    examples.md
By HTTP Method:
  • GET: List or retrieve → check relevant domain resource
  • POST: Create → load resource file, check required fields
  • PUT: Update → load resource file, verify patch fields
  • DELETE: Remove → check resource-specific constraints
确定用户需求：
按资源类型：
  • 认证问题？ → 
    authentication-setup.md
  • 管理联系人/客户？ → 
    contacts-organizations.md
  • 财务数据（发票、费用、项目）？ → 
    accounting-objects.md
  • 银行业务/对账？ → 
    banking-financial.md
  • 错误或生产环境相关问题？ → 
    advanced-patterns.md
  • 需要实用示例？ → 
    examples.md
按HTTP方法：
  • GET：列出或检索 → 查看相关领域资源
  • POST：创建 → 加载资源文件，检查必填字段
  • PUT：更新 → 加载资源文件，验证补丁字段
  • DELETE：删除 → 检查资源特定约束

Phase 2: Resource Navigation

阶段2：资源导航

Load the appropriate resource file and:
  1. Find the endpoint section (e.g., "Contacts", "Invoices", "Bank Accounts")
  2. Review required/optional parameters
  3. Check request and response formats
  4. Use provided curl or Python examples
For template code: 
templates/api-request-template.sh
(bash) or 
templates/python-client.py
(Python)
加载合适的资源文件并执行以下操作：
  1. 找到端点章节（如“联系人”“发票”“银行账户”）
  2. 查看必填/可选参数
  3. 检查请求和响应格式
  4. 使用提供的curl或Python示例
模板代码：
templates/api-request-template.sh
（bash）或
templates/python-client.py
（Python）

Phase 3: Execution & Validation

阶段3：执行与验证

Before API call:
  • Verify authentication is set up (check 
    authentication-setup.md
    if needed)
  • Validate required fields are present
  • Format dates as ISO 8601 (YYYY-MM-DD) and timestamps (YYYY-MM-DDTHH:MM:SSZ)
  • Use correct resource URLs (e.g., 
    https://api.freeagent.com/v2/contacts/123
    )
During API call:
  • Use templates as starting points
  • Monitor rate limit headers: 
    X-RateLimit-Remaining
  • Implement retry logic for 429 errors (see 
    advanced-patterns.md
    )
After API call:
  • Check response status code
  • Parse JSON response (resource name is top-level key)
  • Apply error handling patterns if needed
API调用前：
  • 确认已完成认证设置（如有需要，查看
    authentication-setup.md
    ）
  • 验证必填字段是否存在
  • 日期格式化为ISO 8601（YYYY-MM-DD），时间戳格式化为（YYYY-MM-DDTHH:MM:SSZ）
  • 使用正确的资源URL（如
    https://api.freeagent.com/v2/contacts/123
    ）
API调用中：
  • 以模板为起点
  • 监控速率限制头：
    X-RateLimit-Remaining
  • 为429错误实现重试逻辑（查看
    advanced-patterns.md
    ）
API调用后：
  • 检查响应状态码
  • 解析JSON响应（资源名称为顶级键）
  • 如有需要，应用错误处理模式

Quick Start: Authentication

快速开始：认证

  1. Create OAuth app: https://dev.freeagent.com/
  2. Get authorization code: 
    https://api.freeagent.com/v2/approve_app?client_id=YOUR_ID
  3. Exchange for tokens at 
    https://api.freeagent.com/v2/token_endpoint
  4. Store in environment variables: 
    FREEAGENT_ACCESS_TOKEN
    , 
    FREEAGENT_REFRESH_TOKEN
  5. Include in every request: 
    Authorization: Bearer $FREEAGENT_ACCESS_TOKEN
→ See Authentication & Setup for detailed walkthrough
  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 Domain Overview

API领域概述

Production URL: 
https://api.freeagent.com/v2/
Sandbox URL: 
https://api.sandbox.freeagent.com/v2/
(test without affecting production)
DomainPrimary EndpointsUse Case
Authentication
/token_endpoint
OAuth flows, token refresh
Contacts & Organizations
/contacts
, 
/company
, 
/users
Client/supplier management
Accounting Objects
/invoices
, 
/projects
, 
/expenses
, 
/timeslips
, 
/estimates
, 
/credit_notes
Core financial workflow
Banking & Financial
/bank_accounts
, 
/bank_transactions
, 
/categories
, 
/tasks
Cash flow, reconciliation
Rate Limits: 120 requests/minute, 3600 requests/hour Response Format: JSON with resource wrapper (e.g., 
{"contact": {...}}
or 
{"contacts": [...]}
)
生产环境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": [...]}
）

Common HTTP Patterns

常见HTTP模式

OperationMethodExample
List itemsGET
GET /v2/contacts?view=active&page=1&per_page=100
Get one itemGET
GET /v2/contacts/123
Create itemPOST
POST /v2/contacts
(with JSON body)
Update itemPUT
PUT /v2/invoices/456
(with partial JSON)
Delete itemDELETE
DELETE /v2/timeslips/789
Filter resultsGET params
?view=open_or_overdue
, 
?updated_since=2025-01-01T00:00:00Z
操作方法示例
列出项目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

Templates & Code Examples

模板与代码示例

Bash/cURL Template: 
templates/api-request-template.sh
  • Flexible curl template for any endpoint
  • GET/POST/PUT/DELETE support
  • Header and parameter configuration
Python Client: 
templates/python-client.py
  • Reusable FreeAgentClient class
  • Error handling and rate limit support
  • Convenience methods for common resources
Practical Examples: 
resources/examples.md
  • Real-world workflows (create invoice, log timeslip, etc.)
  • Python code patterns with the client class
  • Error handling examples
  • Bulk operations (import/export)
Bash/cURL模板： 
templates/api-request-template.sh
  • 适用于任意端点的灵活curl模板
  • 支持GET/POST/PUT/DELETE
  • 头部和参数配置
Python客户端： 
templates/python-client.py
  • 可复用的FreeAgentClient类
  • 支持错误处理和速率限制
  • 常见资源的便捷方法
实用示例： 
resources/examples.md
  • 实际场景工作流（创建发票、记录工时等）
  • 基于客户端类的Python代码模式
  • 错误处理示例
  • 批量操作（导入/导出）

Resource Files Summary

资源文件摘要

FileLinesFocus
authentication-setup.md
~180OAuth setup, token management, security
contacts-organizations.md
~250Contact CRUD, bulk operations, company info
accounting-objects.md
~350Invoices, projects, expenses, timeslips, pagination
banking-financial.md
~250Bank accounts, transactions, reconciliation, categories
advanced-patterns.md
~350Error handling, rate limits, retries, caching, validation
examples.md
~400Practical code examples, integration patterns
endpoints.md
~300Complete API reference (use for quick lookup)
文件行数重点
authentication-setup.md
~180OAuth设置、令牌管理、安全
contacts-organizations.md
~250联系人增删改查、批量操作、公司信息
accounting-objects.md
~350发票、项目、费用、工时记录、分页
banking-financial.md
~250银行账户、交易、对账、分类
advanced-patterns.md
~350错误处理、速率限制、重试、缓存、验证
examples.md
~400实用代码示例、集成模式
endpoints.md
~300完整API参考（用于快速查询）

Troubleshooting Quick Links

故障排查快速链接

401 Unauthorized → Authentication Setup 422 Validation Error → Advanced Patterns 429 Rate Limit → Advanced Patterns Specific Endpoint Help → Check relevant domain resource file above
Remember: Load only the resource file(s) you need for the current task. Start with the Quick Reference table above to identify which resource contains your answer.
401 未授权 → 认证设置 422 验证错误 → 进阶模式 429 速率限制 → 进阶模式 特定端点帮助 → 查看上方相关领域的资源文件
注意： 仅加载当前任务所需的资源文件。先通过上方的快速参考表格确定哪个资源包含你需要的答案。