api-gateway-zh

name	api-gateway-zh
description	连接 100+ API（Google Workspace、Microsoft 365、GitHub、Notion、Slack、Airtable、HubSpot 等），支持托管 OAuth 认证。 当用户需要与外部服务交互时使用此技能。 安全说明：MATON_API_KEY 仅用于 Maton.ai 身份验证，本身不授予对第三方服务的访问权限。每个服务都需要用户通过 Maton 的连接流程进行明确的 OAuth 授权。访问权限严格限制在用户已授权的连接范围内。由 Maton 提供 (https://maton.ai)。
compatibility	需要网络访问和有效的 Maton API 密钥
metadata	{"author":"maton","version":"1.0","clawdbot":{"emoji":"🧠","homepage":"https://maton.ai","requires":{"env":["MATON_API_KEY"]}}}

API 网关

由 Maton 提供的透传代理，可通过托管 OAuth 连接直接访问第三方 API。API 网关让您可以直接调用原生 API 端点。

快速开始

# 原生 Slack API 调用
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello from gateway!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', 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

基础 URL

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

将 {app} 替换为服务名称，将 {native-api-path} 替换为实际的 API 端点路径。

重要提示：URL 路径必须以连接的应用名称开头（例如 /google-mail/...）。此前缀告诉网关使用哪个应用连接。例如，原生 Gmail API 路径以 gmail/v1/ 开头，因此完整路径类似于 /google-mail/gmail/v1/users/me/messages。

身份验证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

API 网关会自动为目标服务注入适当的 OAuth 令牌。

环境变量： 您可以将 API 密钥设置为 MATON_API_KEY 环境变量：

export MATON_API_KEY="YOUR_API_KEY"

获取 API 密钥

1. 登录或在 maton.ai 创建账户
2. 前往 maton.ai/settings
3. 点击 API Key 部分右侧的复制按钮进行复制

连接管理

连接管理使用单独的基础 URL：https://ctrl.maton.ai

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=slack&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

查询参数（可选）：

• app - 按服务名称过滤（例如 slack、hubspot、salesforce）
• status - 按连接状态过滤（ACTIVE、PENDING、FAILED）

响应：

{
  "connections": [
    {
      "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=5e9...",
      "app": "slack",
      "method": "OAUTH2",
      "metadata": {}
    }
  ]
}

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).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

请求体：

• app（必需）- 服务名称（例如 slack、notion）
• method（可选）- 连接方式（API_KEY、BASIC、OAUTH1、OAUTH2、MCP）

获取连接

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

响应：

{
  "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=5e9...",
    "app": "slack",
    "metadata": {}
  }
}

在浏览器中打开返回的 URL 以完成 OAuth 授权。

删除连接

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

指定连接

如果您对同一应用有多个连接，可以通过添加带有连接 ID 的 Maton-Connection 头来指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用该应用的默认（最早）活动连接。

支持的服务

服务	应用名称	代理的基础 URL
ActiveCampaign	active-campaign	{account}.api-us1.com
Acuity Scheduling	acuity-scheduling	acuityscheduling.com
Airtable	airtable	api.airtable.com
Apollo	apollo	api.apollo.io
Asana	asana	app.asana.com
Attio	attio	api.attio.com
Basecamp	basecamp	3.basecampapi.com
Baserow	baserow	api.baserow.io
beehiiv	beehiiv	api.beehiiv.com
Box	box	api.box.com
Brevo	brevo	api.brevo.com
Calendly	calendly	api.calendly.com
Cal.com	cal-com	api.cal.com
CallRail	callrail	api.callrail.com
Chargebee	chargebee	{subdomain}.chargebee.com
ClickFunnels	clickfunnels	{subdomain}.myclickfunnels.com
ClickSend	clicksend	rest.clicksend.com
ClickUp	clickup	api.clickup.com
Clockify	clockify	api.clockify.me
Coda	coda	coda.io
Confluence	confluence	api.atlassian.com
CompanyCam	companycam	api.companycam.com
Cognito Forms	cognito-forms	www.cognitoforms.com
Constant Contact	constant-contact	api.cc.email
Dropbox	dropbox	api.dropboxapi.com
Dropbox Business	dropbox-business	api.dropboxapi.com
ElevenLabs	elevenlabs	api.elevenlabs.io
Eventbrite	eventbrite	www.eventbriteapi.com
Fathom	fathom	api.fathom.ai
Firebase	firebase	firebase.googleapis.com
Fireflies	fireflies	api.fireflies.ai
GetResponse	getresponse	api.getresponse.com
GitHub	github	api.github.com
Gumroad	gumroad	api.gumroad.com
Granola MCP	granola	mcp.granola.ai
Google Ads	google-ads	googleads.googleapis.com
Google BigQuery	google-bigquery	bigquery.googleapis.com
Google Analytics Admin	google-analytics-admin	analyticsadmin.googleapis.com
Google Analytics Data	google-analytics-data	analyticsdata.googleapis.com
Google Calendar	google-calendar	www.googleapis.com
Google Classroom	google-classroom	classroom.googleapis.com
Google Contacts	google-contacts	people.googleapis.com
Google Docs	google-docs	docs.googleapis.com
Google Drive	google-drive	www.googleapis.com
Google Forms	google-forms	forms.googleapis.com
Gmail	google-mail	gmail.googleapis.com
Google Merchant	google-merchant	merchantapi.googleapis.com
Google Meet	google-meet	meet.googleapis.com
Google Play	google-play	androidpublisher.googleapis.com
Google Search Console	google-search-console	www.googleapis.com
Google Sheets	google-sheets	sheets.googleapis.com
Google Slides	google-slides	slides.googleapis.com
Google Tasks	google-tasks	tasks.googleapis.com
Google Workspace Admin	google-workspace-admin	admin.googleapis.com
HubSpot	hubspot	api.hubapi.com
Instantly	instantly	api.instantly.ai
Jira	jira	api.atlassian.com
Jobber	jobber	api.getjobber.com
JotForm	jotform	api.jotform.com
Keap	keap	api.infusionsoft.com
Kit	kit	api.kit.com
Klaviyo	klaviyo	a.klaviyo.com
Lemlist	lemlist	api.lemlist.com
Linear	linear	api.linear.app
LinkedIn	linkedin	api.linkedin.com
Mailchimp	mailchimp	{dc}.api.mailchimp.com
MailerLite	mailerlite	connect.mailerlite.com
Mailgun	mailgun	api.mailgun.net
ManyChat	manychat	api.manychat.com
Manus	manus	api.manus.ai
Microsoft Excel	microsoft-excel	graph.microsoft.com
Microsoft Teams	microsoft-teams	graph.microsoft.com
Microsoft To Do	microsoft-to-do	graph.microsoft.com
Monday.com	monday	api.monday.com
Motion	motion	api.usemotion.com
Netlify	netlify	api.netlify.com
Notion	notion	api.notion.com
Notion MCP	notion	mcp.notion.com
OneDrive	one-drive	graph.microsoft.com
Outlook	outlook	graph.microsoft.com
PDF.co	pdf-co	api.pdf.co
Pipedrive	pipedrive	api.pipedrive.com
Podio	podio	api.podio.com
PostHog	posthog	{subdomain}.posthog.com
QuickBooks	quickbooks	quickbooks.api.intuit.com
Quo	quo	api.openphone.com
Reducto	reducto	platform.reducto.ai
Salesforce	salesforce	{instance}.salesforce.com
Sentry	sentry	{subdomain}.sentry.io
SignNow	signnow	api.signnow.com
Slack	slack	slack.com
Snapchat	snapchat	adsapi.snapchat.com
Square	squareup	connect.squareup.com
Squarespace	squarespace	api.squarespace.com
Sunsama MCP	sunsama	MCP server
Stripe	stripe	api.stripe.com
Systeme.io	systeme	api.systeme.io
Tally	tally	api.tally.so
Telegram	telegram	api.telegram.org
TickTick	ticktick	api.ticktick.com
Todoist	todoist	api.todoist.com
Toggl Track	toggl-track	api.track.toggl.com
Trello	trello	api.trello.com
Twilio	twilio	api.twilio.com
Typeform	typeform	api.typeform.com
Unbounce	unbounce	api.unbounce.com
Vimeo	vimeo	api.vimeo.com
WhatsApp Business	whatsapp-business	graph.facebook.com
WooCommerce	woocommerce	{store-url}/wp-json/wc/v3
WordPress.com	wordpress	public-api.wordpress.com
Xero	xero	api.xero.com
YouTube	youtube	www.googleapis.com
Zoho Bigin	zoho-bigin	www.zohoapis.com
Zoho Bookings	zoho-bookings	www.zohoapis.com
Zoho Books	zoho-books	www.zohoapis.com
Zoho Calendar	zoho-calendar	calendar.zoho.com
Zoho CRM	zoho-crm	www.zohoapis.com
Zoho Inventory	zoho-inventory	www.zohoapis.com
Zoho Mail	zoho-mail	mail.zoho.com
Zoho People	zoho-people	people.zoho.com
Zoho Projects	zoho-projects	projectsapi.zoho.com
Zoho Recruit	zoho-recruit	recruit.zoho.com

查看 references/ 获取每个提供商的详细路由指南：

• ActiveCampaign - 联系人、交易、标签、列表、自动化、营销活动
• Acuity Scheduling - 预约、日历、客户、可用性
• Airtable - 记录、基地、表格
• Apollo - 人员搜索、数据增强、联系人
• Asana - 任务、项目、工作区、Webhook
• Attio - 人员、公司、记录、任务
• Basecamp - 项目、待办事项、消息、日程、文档
• Baserow - 数据库行、字段、表格、批量操作
• beehiiv - 出版物、订阅、帖子、自定义字段
• Box - 文件、文件夹、协作、共享链接
• Brevo - 联系人、邮件营销、事务性邮件、模板
• Calendly - 事件类型、已安排事件、可用性、Webhook
• Cal.com - 事件类型、预订、日程、可用时段、Webhook
• CallRail - 通话、跟踪器、公司、标签、分析
• Chargebee - 订阅、客户、发票
• ClickFunnels - 联系人、产品、订单、课程、Webhook
• ClickSend - 短信、彩信、语音消息、联系人、列表
• ClickUp - 任务、列表、文件夹、空间、Webhook
• Clockify - 时间跟踪、项目、客户、任务、工作区
• Coda - 文档、页面、表格、行、公式、控件
• Confluence - 页面、空间、博客文章、评论、附件
• CompanyCam - 项目、照片、用户、标签、组、文档
• Cognito Forms - 表单、条目、文档、文件
• Constant Contact - 联系人、邮件营销、列表、细分
• Dropbox - 文件、文件夹、搜索、元数据、版本、标签
• Dropbox Business - 团队成员、组、团队文件夹、设备、审计日志
• ElevenLabs - 文本转语音、语音克隆、音效、音频处理
• Eventbrite - 活动、场地、门票、订单、参与者
• Fathom - 会议录音、转录、摘要、Webhook
• Firebase - 项目、Web应用、Android应用、iOS应用、配置
• Fireflies - 会议转录、摘要、AskFred AI、频道
• GetResponse - 营销活动、联系人、通讯、自动回复、标签、细分
• GitHub - 仓库、问题、拉取请求、提交
• Gumroad - 产品、销售、订阅者、许可证、Webhook
• Granola MCP - 基于 MCP 的会议笔记、转录、查询接口
• Google Ads - 营销活动、广告组、GAQL 查询
• Google Analytics Admin - 报告、维度、指标
• Google Analytics Data - 报告、维度、指标
• Google BigQuery - 数据集、表、作业、SQL 查询
• Google Calendar - 事件、日历、忙碌/空闲
• Google Classroom - 课程、课程作业、学生、教师、公告
• Google Contacts - 联系人、联系人群组、人员搜索
• Google Docs - 文档创建、批量更新
• Google Drive - 文件、文件夹、权限
• Google Forms - 表单、问题、回复
• Gmail - 邮件、会话、标签
• Google Meet - 空间、会议记录、参与者
• Google Merchant - 产品、库存、促销、报告
• Google Play - 应用内产品、订阅、评论
• Google Search Console - 搜索分析、站点地图
• Google Sheets - 值、范围、格式化
• Google Slides - 演示文稿、幻灯片、格式化
• Google Tasks - 任务列表、任务、子任务
• Google Workspace Admin - 用户、组、组织单元、域、角色
• HubSpot - 联系人、公司、交易
• Instantly - 营销活动、潜在客户、账户、邮件外联
• Jira - 问题、项目、JQL 查询
• Jobber - 客户、工作、发票、报价 (GraphQL)
• JotForm - 表单、提交、Webhook
• Keap - 联系人、公司、标签、任务、机会、营销活动
• Kit - 订阅者、标签、表单、序列、广播
• Klaviyo - 配置文件、列表、营销活动、流程、事件
• Lemlist - 营销活动、潜在客户、活动、日程、退订
• Linear - 问题、项目、团队、周期 (GraphQL)
• LinkedIn - 个人资料、帖子、分享、媒体上传
• Mailchimp - 受众、营销活动、模板、自动化
• MailerLite - 订阅者、组、营销活动、自动化、表单
• Mailgun - 邮件发送、域、路由、模板、邮件列表、退订
• ManyChat - 订阅者、标签、流程、消息
• Manus - AI 代理任务、项目、文件、Webhook
• Microsoft Excel - 工作簿、工作表、范围、表格、图表
• Microsoft Teams - 团队、频道、消息、成员、聊天
• Microsoft To Do - 任务列表、任务、检查项、链接资源
• Monday.com - 看板、项目、列、组 (GraphQL)
• Motion - 任务、项目、工作区、日程
• Netlify - 站点、部署、构建、DNS、环境变量
• Notion - 页面、数据库、块
• Notion MCP - 基于 MCP 的页面、数据库、评论、团队、用户接口
• OneDrive - 文件、文件夹、驱动器、共享
• Outlook - 邮件、日历、联系人
• PDF.co - PDF 转换、合并、拆分、编辑、文本提取、条形码
• Pipedrive - 交易、人员、组织、活动
• Podio - 组织、工作区、应用、项目、任务、评论
• PostHog - 产品分析、功能开关、会话录制、实验、HogQL 查询
• QuickBooks - 客户、发票、报告
• Quo - 通话、消息、联系人、对话、Webhook
• Reducto - 文档解析、提取、拆分、编辑
• Salesforce - SOQL、sObjects、CRUD
• SignNow - 文档、模板、邀请、电子签名
• SendGrid - 邮件发送、联系人、模板、退订、统计
• Sentry - 问题、事件、项目、团队、发布
• Slack - 消息、频道、用户
• Snapchat - 广告账户、营销活动、广告组、广告、创意、受众
• Square - 支付、客户、订单、目录、库存、发票
• Squarespace - 产品、库存、订单、配置文件、交易
• Sunsama MCP - 基于 MCP 的任务、日历、积压、目标、时间跟踪接口
• Stripe - 客户、订阅、支付
• Systeme.io - 联系人、标签、课程、社区、Webhook
• Tally - 表单、提交、工作区、Webhook
• Telegram - 消息、聊天、机器人、更新、投票
• TickTick - 任务、项目、任务列表
• Todoist - 任务、项目、分区、标签、评论
• Toggl Track - 时间条目、项目、客户、标签、工作区
• Trello - 看板、列表、卡片、检查清单
• Twilio - 短信、语音通话、电话号码、消息
• Typeform - 表单、回复、洞察
• Unbounce - 落地页、潜在客户、账户、子账户、域
• Vimeo - 视频、文件夹、相册、评论、点赞
• WhatsApp Business - 消息、模板、媒体
• WooCommerce - 产品、订单、客户、优惠券
• WordPress.com - 帖子、页面、站点、用户、设置
• Xero - 联系人、发票、报告
• YouTube - 视频、播放列表、频道、订阅
• Zoho Bigin - 联系人、公司、管道、产品
• Zoho Bookings - 预约、服务、员工、工作区
• Zoho Books - 发票、联系人、账单、费用
• Zoho Calendar - 日历、事件、参与者、提醒
• Zoho CRM - 线索、联系人、账户、交易、搜索
• Zoho Inventory - 项目、销售订单、发票、采购订单、账单
• Zoho Mail - 消息、文件夹、标签、附件
• Zoho People - 员工、部门、职称、考勤、请假
• Zoho Projects - 项目、任务、里程碑、任务列表、评论
• Zoho Recruit - 候选人、职位、面试、申请

示例

Slack - 发送消息（原生 API）

# 原生 Slack API: POST https://slack.com/api/chat.postMessage
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json; charset=utf-8')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

HubSpot - 创建联系人（原生 API）

# 原生 HubSpot API: POST https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'properties': {'email': '[e-mail]', 'firstname': 'John', 'lastname': 'Doe'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts', 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

Google Sheets - 获取电子表格值（原生 API）

# 原生 Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Salesforce - SOQL 查询（原生 API）

# 原生 Salesforce API: GET https://{instance}.salesforce.com/services/data/v64.0/query?q=...
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v64.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Airtable - 列出表格（原生 API）

# 原生 Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/meta/bases/appgqan2NzWGP5sBK/tables')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Notion - 查询数据库（原生 API）

# 原生 Notion API: POST https://api.notion.com/v1/data_sources/{id}/query
python <<'EOF'
import urllib.request, os, json
data = json.dumps({}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/data_sources/23702dc5-9a3b-8001-9e1c-000b5af0a980/query', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Stripe - 列出客户（原生 API）

# 原生 Stripe API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

代码示例

JavaScript (Node.js)

const response = await fetch('https://gateway.maton.ai/slack/api/chat.postMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({ channel: 'C0123456', text: 'Hello!' })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/slack/api/chat.postMessage',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'channel': 'C0123456', 'text': 'Hello!'}
)

错误处理

状态码	含义
400	缺少请求应用的连接
401	Maton API 密钥无效或缺失
429	限流（每账户每秒 10 个请求）
500	内部服务器错误
4xx/5xx	来自目标 API 的透传错误

来自目标 API 的错误会以其原始状态码和响应体透传。

故障排除：API 密钥问题

1. 检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥是否有效：

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

故障排除：无效的应用名称

1. 验证您的 URL 路径以正确的应用名称开头。路径必须以 /google-mail/ 开头。例如：

• 正确：https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• 错误：https://gateway.maton.ai/gmail/v1/users/me/messages

2. 确保您有该应用的活动连接。列出您的连接以验证：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&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

故障排除：服务器错误

500 错误可能表示 OAuth 令牌已过期。尝试通过上面的连接管理部分创建新连接并完成 OAuth 授权。如果新连接状态为 "ACTIVE"，请删除旧连接以确保网关使用新连接。

速率限制

• 每账户每秒 10 个请求
• 目标 API 的速率限制同样适用

注意事项

• 使用 curl 处理包含括号的 URL（fields[]、sort[]、records[]）时，请使用 -g 标志禁用 glob 解析
• 将 curl 输出管道到 jq 时，环境变量可能在某些 shell 中无法正确展开，这可能导致"Invalid API key"错误

提示

1. 使用原生 API 文档：参考每个服务的官方 API 文档了解端点路径和参数。

2. 请求头会被转发：自定义请求头（除了 Host 和 Authorization）会被转发到目标 API。

3. 查询参数有效：URL 查询参数会被透传到目标 API。

4. 支持所有 HTTP 方法：GET、POST、PUT、PATCH、DELETE 均受支持。

5. QuickBooks 特殊情况：在路径中使用 :realmId，它将被替换为已连接的 realm ID。

可选资源

• Github
• API 参考
• Maton 社区
• Maton 支持