Api Gateway Zh

API 网关

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

快速开始

bashCopy code
# 原生 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

Copy code
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 密钥：

Copy code
Authorization: Bearer $MATON_API_KEY

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

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

bashCopy code
export MATON_API_KEY="YOUR_API_KEY"

获取 API 密钥

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

连接管理

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

列出连接

bashCopy code
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）

响应：

jsonCopy code
{
  "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": {}
    }
  ]
}

创建连接

bashCopy code
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）

获取连接

bashCopy code
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

响应：

jsonCopy code
{
  "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 授权。

删除连接

bashCopy code
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 头来指定使用哪个连接：

bashCopy code
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

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

支持的服务

查看 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）

bashCopy code
# 原生 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）

bashCopy code
# 原生 HubSpot API: POST https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'properties': {'email': 'john@example.com', '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）

bashCopy code
# 原生 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）

bashCopy code
# 原生 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）

bashCopy code
# 原生 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）

bashCopy code
# 原生 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）

bashCopy code
# 原生 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)

javascriptCopy code
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

pythonCopy code
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!'}
)

错误处理

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

故障排除：API 密钥问题

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

bashCopy code
echo $MATON_API_KEY

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

bashCopy code
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. 确保您有该应用的活动连接。列出您的连接以验证：

bashCopy code
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 支持