Systeme.io

通过托管的 OAuth 认证访问 Systeme.io API，用于管理联系人、标签、课程、社群和订阅。

快速开始

# 列出联系人
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/systeme/api/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

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

Maton 将请求代理至 api.systeme.io，并自动注入您的 API 密钥。

认证

所有请求均需在 Authorization 请求头中提供 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 在 maton.ai 登录或注册账户
2. 访问 maton.ai/settings
3. 复制您的 API 密钥

连接管理

在 https://api.maton.ai 管理您的 Systeme.io 连接。

列出连接

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

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'systeme'}).encode()
req = urllib.request.Request('https://api.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

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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": "{connection_id}",
    "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": "systeme",
    "metadata": {}
  }
}

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

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

指定连接

若您拥有多个 Systeme.io 连接，请使用 Maton-Connection 请求头明确指定目标连接：

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

当存在多个连接时，请始终包含该请求头，以确保请求被路由至预期账户。

安全与权限

• 访问范围限定于已连接的 Systeme.io 账户内的联系人、标签、课程、社群和订阅。
• 所有写入操作均需用户显式授权。 在执行任何创建、更新或删除调用前，必须向用户确认目标资源及预期变更效果。

API 参考文档

联系人操作

列出联系人

GET /systeme/api/contacts

查询参数：

• limit — 每页返回条目数（取值范围：10–100，可选）
• startingAfter — 分页用的上一页最后一条记录 ID（可选）
• order — 排序方式：asc 或 desc（默认为 desc，可选）

获取联系人

GET /systeme/api/contacts/{id}

创建联系人

POST /systeme/api/contacts
Content-Type: application/json

{
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "locale": "en",
  "fields": [
    {
      "slug": "custom_field_slug",
      "value": "custom value"
    }
  ]
}

更新联系人

PATCH /systeme/api/contacts/{id}
Content-Type: application/merge-patch+json

{
  "firstName": "Jane",
  "lastName": "Smith"
}

删除联系人

DELETE /systeme/api/contacts/{id}

标签操作

列出标签

GET /systeme/api/tags

获取标签

GET /systeme/api/tags/{id}

创建标签

POST /systeme/api/tags
Content-Type: application/json

{
  "name": "VIP Customer"
}

更新标签

PUT /systeme/api/tags/{id}
Content-Type: application/json

{
  "name": "Premium Customer"
}

删除标签

DELETE /systeme/api/tags/{id}

联系人标签操作

为联系人分配标签

POST /systeme/api/contacts/{id}/tags
Content-Type: application/json

{
  "tagId": 12345
}

从联系人移除标签

DELETE /systeme/api/contacts/{id}/tags/{tagId}

联系人字段操作

列出联系人字段

GET /systeme/api/contact_fields

创建联系人字段

POST /systeme/api/contact_fields
Content-Type: application/json

{
  "name": "Company Name",
  "slug": "company_name"
}

更新联系人字段

PATCH /systeme/api/contact_fields/{slug}
Content-Type: application/merge-patch+json

{
  "name": "Organization Name"
}

删除联系人字段

DELETE /systeme/api/contact_fields/{slug}

课程操作

列出课程

GET /systeme/api/school/courses

列出报名记录

GET /systeme/api/school/enrollments

创建报名记录

POST /systeme/api/school/courses/{courseId}/enrollments
Content-Type: application/json

{
  "contactId": 12345,
  "accessType": "full_access"
}

必需字段：

• contactId — 待报名联系人的 ID
• accessType — 访问类型：full_access、partial_access 或 dripping_content

注意：若 accessType 为 partial_access，则还需提供包含模块 ID 的 modules 数组。

删除报名记录

DELETE /systeme/api/school/enrollments/{id}

社群操作

列出社群

GET /systeme/api/community/communities

列出成员资格

GET /systeme/api/community/memberships

创建成员资格

POST /systeme/api/community/communities/{communityId}/memberships
Content-Type: application/json

{
  "contactId": 12345
}

删除成员资格

DELETE /systeme/api/community/memberships/{id}

订阅操作

列出订阅

GET /systeme/api/payment/subscriptions

取消订阅

POST /systeme/api/payment/subscriptions/{id}/cancel

分页

Systeme.io 使用基于游标的分页机制，支持以下参数：

GET /systeme/api/contacts?limit=50&startingAfter=12345&order=asc

参数说明：

• limit — 每页返回条目数（取值范围：10–100）
• startingAfter — 上一页最后一条记录的 ID
• order — 排序方式：asc 或 desc（默认为 desc）

响应格式：

{
  "items": [...],
  "hasMore": true
}

当 hasMore 为 true 时，请将 items 中最后一条记录的 ID 作为下一页请求的 startingAfter 参数值。

代码示例

JavaScript

const response = await fetch(
  'https://api.maton.ai/systeme/api/contacts',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/systeme/api/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

创建带标签的联系人

import os
import requests

# 创建联系人
contact = requests.post(
    'https://api.maton.ai/systeme/api/contacts',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'email': 'new@example.com',
        'firstName': 'New',
        'lastName': 'Contact'
    }
).json()

# 分配标签
requests.post(
    f'https://api.maton.ai/systeme/api/contacts/{contact["id"]}/tags',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={'tagId': 12345}
)

注意事项

• Systeme.io 原生采用 API 密钥认证（请求头为 X-API-Key）
• Maton 自动处理认证请求头的转换
• PATCH 请求请使用 application/merge-patch+json 内容类型
• 联系人、标签、课程和报名记录的 ID 均为数值型整数
• 速率限制通过 X-RateLimit-* 响应头实施
• Systeme.io 对邮箱域名进行校验 —— 仅接受具有有效 MX 记录的真实邮箱地址
• 订阅接口（/api/payment/subscriptions）在未配置支付功能时可能返回 404
• 重要提示：使用 curl 命令时，若 URL 包含方括号，请添加 -g 参数以禁用 glob 解析
• 重要提示：将 curl 输出管道传递给 jq 或其他命令时，在某些 Shell 环境中，$MATON_API_KEY 等环境变量可能无法正确展开

错误处理

故障排查：API 密钥问题

1. 确认已设置 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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 路径以 systeme 开头。例如：

• 正确：https://api.maton.ai/systeme/api/contacts
• 错误：https://api.maton.ai/api/contacts

相关资源

• Systeme.io API 参考文档
• Systeme.io API 概览
• Maton 社区
• Maton 支持