Xero：自动化会计与财务管理 - Openclaw Skills

什么是 Xero？

Xero 技能在您的 AI 代理与 Xero 会计平台之间提供了强大的桥梁。通过利用托管的 OAuth 网关，它消除了手动刷新令牌和管理标头的复杂性。此 Openclaw Skills 集成允许开发人员以编程方式管理联系人、发票和银彳交易，同时通过简化的代理生成详细的财务报告，如损益表或资产负债表。

该技能专为需要在不构建自定义 OAuth 流程的情况下将财务工作流集成到应用程序中的开发人员而设计，简化了与 Xero 广泛的会计功能的交互。无论您是自动化计费还是同步 CRM 数据，此 Openclaw Skills 资源都提供了企业级财务自动化所需的安全性、托管基础设施。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/xero

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install xero

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 xero。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Xero 应用场景

• 自动化创建销售发票 (ACCREC) 和采购 (ACCPAY)。
• 将 CRM 联系人数据与 Xero 会计记录同步，以确保数据一致性。
• 生成实时财务报告，如损益表或试算表，用于商业智能。
• 跨多个账户跟踪和列出付款及银彳交易。
• 构建自定义仪表板，通过统一的 API 网关可视化 Xero 账簿数据。

Xero 工作原理

1. 用户使用其 Maton API 密钥进行身份验证，以访问安全网关。
2. 通过 Maton 控制面板建立并授权 OAuth 连接。
3. 网关自动将所需的 OAuth Bearer 令牌和 Xero-Tenant-Id 注入到通过 Openclaw Skills 发出的每个请求中。
4. API 调用通过安全基础设施代理到原生 Xero 端点 (api.xero.com)。
5. 该技能处理速率限制和透传错误响应，将干净的 JSON 数据返回给调用代理。

Xero 配置指南

1. 从 maton.ai 设置页面获取您的 API 密钥。
2. 在终端中设置环境变量：

export MATON_API_KEY="YOUR_API_KEY"

3. 使用控制 API 创建与 Xero 的连接：

curl -X POST https://ctrl.maton.ai/connections r
  -H "Authorization: Bearer $MATON_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"app": "xero"}'

4. 在浏览器中打开返回的 URL，以完成与您的 Xero 账户的 OAuth 授权。

Xero 数据架构与分类体系

该技能遵循原生 Xero Accounting API 模式。常见对象包括：

对象	描述	关键字段
Contacts	客户或供应商信息	Name, EmailAddress, ContactID
Invoices	销售或	Type (ACCREC/ACCPAY), LineItems, Total
Accounts	会计科目表	AccountCode, Name, Type
Reports	财务报表	ReportID, ReportName, Rows
Payments	交易记录	PaymentID, Amount, Date

name: xero
description: |
  Xero API integration with managed OAuth. Manage contacts, invoices, payments, accounts, and run financial reports. Use this skill when users want to interact with Xero accounting data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Xero

Access the Xero API with managed OAuth authentication. Manage contacts, invoices, payments, bank transactions, and run financial reports.

Quick Start

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/xero/api.xro/2.0/Contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/xero/{native-api-path}

Replace {native-api-path} with the actual Xero API endpoint path. The gateway proxies requests to api.xero.com and automatically injects your OAuth token and Xero-Tenant-Id header.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Xero OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=xero&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'xero'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "xero",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Xero connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/xero/api.xro/2.0/Contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Contacts

List Contacts

GET /xero/api.xro/2.0/Contacts

Get Contact

GET /xero/api.xro/2.0/Contacts/{contactId}

Create Contact

POST /xero/api.xro/2.0/Contacts
Content-Type: application/json

{
  "Contacts": [{
    "Name": "John Doe",
    "EmailAddress": "[email protected]",
    "Phones": [{"PhoneType": "DEFAULT", "PhoneNumber": "555-1234"}]
  }]
}

Invoices

List Invoices

GET /xero/api.xro/2.0/Invoices

Create Invoice

POST /xero/api.xro/2.0/Invoices
Content-Type: application/json

{
  "Invoices": [{
    "Type": "ACCREC",
    "Contact": {"ContactID": "xxx"},
    "LineItems": [{
      "Description": "Service",
      "Quantity": 1,
      "UnitAmount": 100.00,
      "AccountCode": "200"
    }]
  }]
}

Accounts

List Accounts

GET /xero/api.xro/2.0/Accounts

Payments

List Payments

GET /xero/api.xro/2.0/Payments

Bank Transactions

List Bank Transactions

GET /xero/api.xro/2.0/BankTransactions

Reports

Profit and Loss

GET /xero/api.xro/2.0/Reports/ProfitAndLoss?fromDate=2024-01-01&toDate=2024-12-31

Balance Sheet

GET /xero/api.xro/2.0/Reports/BalanceSheet?date=2024-12-31

Trial Balance

GET /xero/api.xro/2.0/Reports/TrialBalance?date=2024-12-31

Organisation

GET /xero/api.xro/2.0/Organisation

Invoice Types

• ACCREC - Accounts Receivable (sales invoice)
• ACCPAY - Accounts Payable (bill)

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/xero/api.xro/2.0/Contacts',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/xero/api.xro/2.0/Contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

Notes

• Xero-Tenant-Id header is automatically injected
• Dates are in YYYY-MM-DD format
• Multiple records can be created in a single request using arrays
• Use where query parameter for filtering
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with xero. For example:

• Correct: https://gateway.maton.ai/xero/api.xro/2.0/Contacts
• Incorrect: https://gateway.maton.ai/api.xro/2.0/Contacts

Resources

• Xero API Overview
• Contacts
• Invoices
• Accounts
• Payments
• Reports
• Maton Community
• Maton Support