xero-api-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xero API Integration Skill

Xero API集成技能

Secure, read-only integration with Xero accounting software for financial data extraction and analysis.

与Xero会计软件的安全只读集成，用于财务数据提取与分析。

When to Use

适用场景

Activate this skill when the task requires:

Extracting financial data from Xero
Generating accounting reports
Analyzing transaction history
Auditing chart of accounts
Reviewing asset registers

当任务需要以下操作时，激活此技能：

从Xero提取财务数据
生成会计报表
分析交易历史
审计会计科目表
查看资产登记簿

⚠️ CRITICAL CONSTRAINT

⚠️ 关键约束

READ-ONLY OPERATION

Only read scopes are authorized
NEVER modify any Xero data
All changes are recommendations only

只读操作

仅授权只读权限范围
绝不修改任何Xero数据
所有修改仅为建议内容

OAuth 2.0 Authentication

OAuth 2.0认证

Required Scopes

所需权限范围

offline_access              # For refresh token
accounting.transactions.read # Bank transactions, invoices, payments
accounting.reports.read      # Financial reports
accounting.contacts.read     # Suppliers and customers
accounting.settings          # Chart of accounts, organization info
openid profile email         # User identity

offline_access              # For refresh token
accounting.transactions.read # Bank transactions, invoices, payments
accounting.reports.read      # Financial reports
accounting.contacts.read     # Suppliers and customers
accounting.settings          # Chart of accounts, organization info
openid profile email         # User identity

Authorization Flow

授权流程

┌─────────────────────────────────────────────────────────────────┐
│ 1. REDIRECT USER                                                │
│    https://login.xero.com/identity/connect/authorize            │
│    ?client_id={CLIENT_ID}                                       │
│    &redirect_uri={REDIRECT_URI}                                 │
│    &scope=offline_access accounting.transactions.read           │
│           accounting.reports.read accounting.contacts.read      │
│           accounting.settings openid profile email              │
│    &response_type=code                                          │
│    &state={STATE}                                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. USER AUTHORIZES                                              │
│    User logs into Xero                                          │
│    Grants read-only access to organization                      │
│    Xero redirects to REDIRECT_URI with authorization code       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. EXCHANGE CODE FOR TOKENS                                     │
│    POST https://identity.xero.com/connect/token                 │
│    Body: grant_type=authorization_code                          │
│          code={AUTH_CODE}                                       │
│          redirect_uri={REDIRECT_URI}                            │
│    Headers: Authorization: Basic {base64(client_id:secret)}     │
│                                                                 │
│    Response: access_token, refresh_token, expires_in            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. GET TENANT ID                                                │
│    GET https://api.xero.com/connections                         │
│    Headers: Authorization: Bearer {access_token}                │
│                                                                 │
│    Response: [{ tenantId, tenantType, tenantName }]             │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 1. REDIRECT USER                                                │
│    https://login.xero.com/identity/connect/authorize            │
│    ?client_id={CLIENT_ID}                                       │
│    &redirect_uri={REDIRECT_URI}                                 │
│    &scope=offline_access accounting.transactions.read           │
│           accounting.reports.read accounting.contacts.read      │
│           accounting.settings openid profile email              │
│    &response_type=code                                          │
│    &state={STATE}                                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. USER AUTHORIZES                                              │
│    User logs into Xero                                          │
│    Grants read-only access to organization                      │
│    Xero redirects to REDIRECT_URI with authorization code       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. EXCHANGE CODE FOR TOKENS                                     │
│    POST https://identity.xero.com/connect/token                 │
│    Body: grant_type=authorization_code                          │
│          code={AUTH_CODE}                                       │
│          redirect_uri={REDIRECT_URI}                            │
│    Headers: Authorization: Basic {base64(client_id:secret)}     │
│                                                                 │
│    Response: access_token, refresh_token, expires_in            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. GET TENANT ID                                                │
│    GET https://api.xero.com/connections                         │
│    Headers: Authorization: Bearer {access_token}                │
│                                                                 │
│    Response: [{ tenantId, tenantType, tenantName }]             │
└─────────────────────────────────────────────────────────────────┘

Token Refresh

令牌刷新

POST https://identity.xero.com/connect/token
Body: grant_type=refresh_token
      refresh_token={REFRESH_TOKEN}
Headers: Authorization: Basic {base64(client_id:secret)}

POST https://identity.xero.com/connect/token
Body: grant_type=refresh_token
      refresh_token={REFRESH_TOKEN}
Headers: Authorization: Basic {base64(client_id:secret)}

API Endpoints

API端点

Organization Information

组织信息

http

GET https://api.xero.com/api.xro/2.0/Organisation
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/api.xro/2.0/Organisation
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Chart of Accounts

会计科目表

http

GET https://api.xero.com/api.xro/2.0/Accounts
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/api.xro/2.0/Accounts
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Bank Transactions

银行交易记录

http

GET https://api.xero.com/api.xro/2.0/BankTransactions
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - where: Date>=DateTime(2024,07,01)
  - page: 1

http

GET https://api.xero.com/api.xro/2.0/BankTransactions
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - where: Date>=DateTime(2024,07,01)
  - page: 1

Invoices

发票

http

GET https://api.xero.com/api.xro/2.0/Invoices
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - where: Type=="ACCREC" AND Status!="DELETED"
  - page: 1

http

GET https://api.xero.com/api.xro/2.0/Invoices
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - where: Type=="ACCREC" AND Status!="DELETED"
  - page: 1

Manual Journals

手工日记账

http

GET https://api.xero.com/api.xro/2.0/ManualJournals
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/api.xro/2.0/ManualJournals
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Payments

付款记录

http

GET https://api.xero.com/api.xro/2.0/Payments
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/api.xro/2.0/Payments
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Trial Balance Report

试算平衡表

http

GET https://api.xero.com/api.xro/2.0/Reports/TrialBalance
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - date: 2024-06-30

http

GET https://api.xero.com/api.xro/2.0/Reports/TrialBalance
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - date: 2024-06-30

Profit and Loss Report

损益表

http

GET https://api.xero.com/api.xro/2.0/Reports/ProfitAndLoss
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - fromDate: 2023-07-01
  - toDate: 2024-06-30

http

GET https://api.xero.com/api.xro/2.0/Reports/ProfitAndLoss
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - fromDate: 2023-07-01
  - toDate: 2024-06-30

Balance Sheet Report

资产负债表

http

GET https://api.xero.com/api.xro/2.0/Reports/BalanceSheet
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - date: 2024-06-30

http

GET https://api.xero.com/api.xro/2.0/Reports/BalanceSheet
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}
Parameters:
  - date: 2024-06-30

Fixed Assets

固定资产

http

GET https://api.xero.com/assets.xro/1.0/Assets
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/assets.xro/1.0/Assets
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Contacts

联系人

http

GET https://api.xero.com/api.xro/2.0/Contacts
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

http

GET https://api.xero.com/api.xro/2.0/Contacts
Authorization: Bearer {access_token}
xero-tenant-id: {tenant_id}

Data Extraction Process

数据提取流程

┌────────────────────────────────────────────────────────────────┐
│                    1. AUTHENTICATE                             │
│ • Validate access token (refresh if expired)                   │
│ • Confirm tenant ID                                            │
│ • Verify organization access                                   │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    2. EXTRACT STRUCTURE                        │
│ • Fetch Organization info                                      │
│ • Fetch Chart of Accounts                                      │
│ • Identify account types and structure                         │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    3. EXTRACT REPORTS                          │
│ • Trial Balance (per FY)                                       │
│ • Profit & Loss (per FY)                                       │
│ • Balance Sheet (current)                                      │
│ • Cache for analysis                                           │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    4. EXTRACT TRANSACTIONS                     │
│ • Bank Transactions (paginated)                                │
│ • Invoices                                                     │
│ • Manual Journals                                              │
│ • Payments                                                     │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    5. EXTRACT ASSETS                           │
│ • Fixed Asset Register                                         │
│ • Depreciation schedules                                       │
└────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────┐
│                    1. 认证                                    │
│ • 验证访问令牌（过期则刷新）                                   │
│ • 确认租户ID                                                  │
│ • 验证组织访问权限                                           │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    2. 提取结构信息                            │
│ • 获取组织信息                                                │
│ • 获取会计科目表                                              │
│ • 识别账户类型与结构                                           │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    3. 提取报表                                │
│ • 试算平衡表（按财年）                                       │
│ • 损益表（按财年）                                           │
│ • 资产负债表（当前）                                          │
│ • 缓存数据用于分析                                           │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    4. 提取交易记录                            │
│ • 银行交易记录（分页）                                        │
│ • 发票                                                       │
│ • 手工日记账                                                  │
│ • 付款记录                                                     │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                    5. 提取资产信息                            │
│ • 固定资产登记簿                                             │
│ • 折旧计划表                                                 │
└────────────────────────────────────────────────────────────────┘

Rate Limiting

速率限制

Limit Type	Value
Daily limit	5,000 calls per tenant
Minute limit	60 calls per minute
Concurrent limit	4 pending requests

Best Practices:

Implement exponential backoff
Cache responses where appropriate
Use pagination efficiently
Monitor rate limit headers

限制类型	数值
每日限制	每个租户5000次调用
每分钟限制	每分钟60次调用
并发限制	4个待处理请求

最佳实践：

实现指数退避机制
合理缓存响应结果
高效使用分页功能
监控速率限制头信息

Error Handling

错误处理

Error	HTTP Code	Recovery
Token expired	401	Refresh token
Rate limited	429	Wait and retry
Not found	404	Check endpoint/params
Forbidden	403	Check scopes
Server error	500+	Retry with backoff

错误类型	HTTP状态码	恢复方式
令牌过期	401	刷新令牌
速率受限	429	等待后重试
资源未找到	404	检查端点/参数
禁止访问	403	检查权限范围
服务器错误	500+	退避后重试

Security Requirements

安全要求

Token Storage
- Encrypt tokens at rest
- Never log access tokens
- Secure refresh token storage
API Calls
- HTTPS only
- Validate SSL certificates
- Log API calls (not tokens)
Authorization
- Request minimal scopes
- Verify tenant access
- Handle revocation gracefully

令牌存储
- 静态存储时加密令牌
- 绝不记录访问令牌
- 安全存储刷新令牌
API调用
- 仅使用HTTPS
- 验证SSL证书
- 记录API调用（不包含令牌）
授权管理
- 请求最小必要权限范围
- 验证租户访问权限
- 优雅处理权限撤销

Output Data Structure

输出数据结构

typescript

interface XeroExtraction {
  organization: {
    name: string;
    abn: string;
    financialYearEndMonth: number;
  };
  
  accounts: Account[];
  
  reports: {
    trialBalance: Map<FY, Report>;
    profitAndLoss: Map<FY, Report>;
    balanceSheet: Report;
  };
  
  transactions: {
    bankTransactions: BankTransaction[];
    invoices: Invoice[];
    manualJournals: ManualJournal[];
    payments: Payment[];
  };
  
  assets: FixedAsset[];
  
  contacts: Contact[];
  
  metadata: {
    extractedAt: Date;
    financialYears: FY[];
    transactionCount: number;
  };
}

typescript

interface XeroExtraction {
  organization: {
    name: string;
    abn: string;
    financialYearEndMonth: number;
  };
  
  accounts: Account[];
  
  reports: {
    trialBalance: Map<FY, Report>;
    profitAndLoss: Map<FY, Report>;
    balanceSheet: Report;
  };
  
  transactions: {
    bankTransactions: BankTransaction[];
    invoices: Invoice[];
    manualJournals: ManualJournal[];
    payments: Payment[];
  };
  
  assets: FixedAsset[];
  
  contacts: Contact[];
  
  metadata: {
    extractedAt: Date;
    financialYears: FY[];
    transactionCount: number;
  };
}

Financial Year Handling

财年处理

typescript

// Australian Financial Year: 1 July - 30 June
function getFinancialYear(date: Date): string {
  const month = date.getMonth(); // 0-11
  const year = date.getFullYear();
  
  if (month >= 6) { // July onwards
    return `FY${year}-${(year + 1).toString().slice(2)}`;
  } else {
    return `FY${year - 1}-${year.toString().slice(2)}`;
  }
}

// FY2024-25: 1 Jul 2024 - 30 Jun 2025

typescript

// 澳大利亚财年：7月1日 - 6月30日
function getFinancialYear(date: Date): string {
  const month = date.getMonth(); // 0-11
  const year = date.getFullYear();
  
  if (month >= 6) { // July onwards
    return `FY${year}-${(year + 1).toString().slice(2)}`;
  } else {
    return `FY${year - 1}-${year.toString().slice(2)}`;
  }
}

// FY2024-25: 1 Jul 2024 - 30 Jun 2025