介绍
# Systeme.io
使用托管的 OAuth 身份验证访问 Systeme.io API。管理联系人、标签、课程、社区和订阅。
## 快速开始
```bash # List contacts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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 ```
## Base URL
``` https://gateway.maton.ai/systeme/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Systeme.io API 端点路径。网关将请求代理到 `api.systeme.io` 并自动注入您的 API 密钥。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Systeme.io 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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 ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'systeme'}).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 ```
### 获取连接
```bash 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 ```
**响应：** ```json { "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": "systeme", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash 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 ```
### 指定连接
如果您有多个 Systeme.io 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/systeme/api/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 ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 联系人操作
#### 列出联系人
```bash GET /systeme/api/contacts ```
**查询参数：** - `limit` - 每页项目数 (10-100，可选) - `startingAfter` - 用于分页的最后接收项目的 ID (可选) - `order` - 排序顺序：`asc` 或 `desc` (默认：`desc`，可选)
#### 获取联系人
```bash GET /systeme/api/contacts/{id} ```
#### 创建联系人
```bash POST /systeme/api/contacts Content-Type: application/json
{ "email": "[email protected]", "firstName": "John", "lastName": "Doe", "phoneNumber": "+1234567890", "locale": "en", "fields": [ { "slug": "custom_field_slug", "value": "custom value" } ] } ```
#### 更新联系人
```bash PATCH /systeme/api/contacts/{id} Content-Type: application/merge-patch+json
{ "firstName": "Jane", "lastName": "Smith" } ```
#### 删除联系人
```bash DELETE /systeme/api/contacts/{id} ```
### 标签操作
#### 列出标签
```bash GET /systeme/api/tags ```
#### 获取标签
```bash GET /systeme/api/tags/{id} ```
#### 创建标签
```bash POST /systeme/api/tags Content-Type: application/json
{ "name": "VIP Customer" } ```
#### 更新标签
```bash PUT /systeme/api/tags/{id} Content-Type: application/json
{ "name": "Premium Customer" } ```
#### 删除标签
```bash DELETE /systeme/api/tags/{id} ```
### 联系人标签操作
#### 为联系人分配标签
```bash POST /systeme/api/contacts/{id}/tags Content-Type: application/json
{ "tagId": 12345 } ```
#### 从联系人移除标签
```bash DELETE /systeme/api/contacts/{id}/tags/{tagId} ```
### 联系人字段操作
#### 列出联系人字段
```bash GET /systeme/api/contact_fields ```
#### 创建联系人字段
```bash POST /systeme/api/contact_fields Content-Type: application/json
{ "name": "Company Name", "slug": "company_name" } ```
#### 更新联系人字段
```bash PATCH /systeme/api/contact_fields/{slug} Content-Type: application/merge-patch+json
{ "name": "Organization Name" } ```
#### 删除联系人字段
```bash DELETE /systeme/api/contact_fields/{slug} ```
### 课程操作
#### 列出课程
```bash GET /systeme/api/school/courses ```
#### 列出注册
```bash GET /systeme/api/school/enrollments ```
#### 创建注册
```bash 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` 数组。
#### 删除注册
```bash DELETE /systeme/api/school/enrollments/{id} ```
### 社区操作
#### 列出社区
```bash GET /systeme/api/community/communities ```
#### 列出成员资格
```bash GET /systeme/api/community/memberships ```
#### 创建成员资格
```bash POST /systeme/api/community/communities/{communityId}/memberships Content-Type: application/json
{ "contactId": 12345 } ```
#### 删除成员资格
```bash DELETE /systeme/api/community/memberships/{id} ```
### 订阅操作
#### 列出订阅
```bash GET /systeme/api/payment/subscriptions ```
#### 取消订阅
```bash POST /systeme/api/payment/subscriptions/{id}/cancel ```
## 分页
Systeme.io 使用基于游标的分页，包含以下参数：
```bash GET /systeme/api/contacts?limit=50&startingAfter=12345&order=asc ```
**参数：** - `limit` - 每页项目数 (10-100) - `startingAfter` - 上一页最后一个项目的 ID - `order` - 排序顺序：`asc` 或 `desc` (默认：`desc`)
**响应：** ```json { "items": [...], "hasMore": true } ```
当 `hasMore` 为 `true` 时，使用 `items` 中最后一个项目的 ID 作为 `startingAfter` 来获取下一页。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/systeme/api/contacts', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/systeme/api/contacts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
### 创建带标签的联系人
```python import os import requests
# Create contact contact = requests.post( 'https://gateway.maton.ai/systeme/api/contacts', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'email': '[email protected]', 'firstName': 'New', 'lastName': 'Contact' } ).json()
# Assign tag requests.post( f'https://gateway.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` 标头传递） - 网关会自动处理身份验证标头转换 - 对 PATCH 请求使用 `application/merge-patch+json` 内容类型 - 联系人、标签、课程和注册 ID 是数字整数 - 速率限制通过 `X-RateLimit-*` 标头执行 - Systeme.io 会验证电子邮件域 - 仅接受具有有效 MX 记录的真实电子邮件地址 - 如果未配置支付功能，订阅端点 (`/api/payment/subscriptions`) 可能会返回 404 - 重要：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Systeme.io 连接或错误请求 | | 401 | 无效或缺失的 Maton API 密钥 | | 429 | 速率受限 (检查 `Retry-After` 标头) | | 4xx/5xx | 来自 Systeme.io API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接验证 API 密钥是否有效：
```bash 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 路径以 `systeme` 开头。例如：
- 正确：`https://gateway.maton.ai/systeme/api/contacts` - 错误：`https://gateway.maton.ai/api/contacts`
## 资源
- [Systeme.io API 参考](https://developer.systeme.io/reference) - [Systeme.io API 概述](https://developer.systeme.io/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])