连接器 API
连接器 API 提供电商平台连接器的管理、健康检查和数据同步接口。
连接器管理
获取连接器列表
GET /api/v1/connectors
获取当前租户的所有连接器。
查询参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | integer | 否 | 页码，默认 1 |
page_size | integer | 否 | 每页条数，默认 20 |
status | string | 否 | 状态筛选：pending / connected / running / error |
platform | string | 否 | 平台筛选：tmall / taobao / douyin / jd / pdd |
成功响应（200）：
json
{
"code": 200,
"message": "success",
"data": {
"items": [
{
"id": "uuid-string",
"name": "天猫旗舰店",
"platform": "tmall",
"status": "running",
"shop_name": "品牌官方旗舰店",
"last_sync_at": "2026-03-14T10:15:00Z",
"next_sync_at": "2026-03-14T10:30:00Z",
"sync_interval_minutes": 15,
"created_at": "2026-01-20T08:00:00Z"
}
],
"total": 3,
"page": 1,
"page_size": 20,
"pages": 1
}
}创建连接器
POST /api/v1/connectors
创建新的平台连接器。
请求体：
json
{
"name": "天猫旗舰店",
"platform": "tmall",
"config": {
"app_key": "your_app_key",
"app_secret": "your_app_secret",
"shop_id": "shop_123456"
},
"sync_interval_minutes": 15
}成功响应（201）：
json
{
"code": 201,
"message": "连接器创建成功",
"data": {
"id": "uuid-string",
"name": "天猫旗舰店",
"platform": "tmall",
"status": "pending",
"auth_url": "https://oauth.taobao.com/authorize?...",
"created_at": "2026-03-14T10:30:00Z"
}
}授权流程
创建连接器后，响应中会返回 auth_url。引导用户访问该 URL 完成平台 OAuth 授权。授权成功后，连接器状态自动变更为 connected。
错误响应：
| 状态码 | 错误码 | 说明 |
|---|---|---|
| 403 | QUOTA_003 | 连接器数量已达订阅方案上限 |
| 409 | CONNECTOR_001 | 该平台店铺已存在连接器 |
| 422 | - | 参数校验失败 |
获取连接器详情
GET /api/v1/connectors/
成功响应（200）：
json
{
"code": 200,
"message": "success",
"data": {
"id": "uuid-string",
"name": "天猫旗舰店",
"platform": "tmall",
"status": "running",
"shop_name": "品牌官方旗舰店",
"config": {
"app_key": "your_***_key",
"shop_id": "shop_123456",
"sync_interval_minutes": 15
},
"stats": {
"total_products": 1250,
"total_orders_30d": 8500,
"last_sync_at": "2026-03-14T10:15:00Z",
"last_sync_status": "success",
"last_sync_duration_seconds": 45
},
"created_at": "2026-01-20T08:00:00Z",
"updated_at": "2026-03-14T10:15:00Z"
}
}更新连接器
PUT /api/v1/connectors/
请求体：
json
{
"name": "天猫旗舰店（更新）",
"sync_interval_minutes": 5
}删除连接器
DELETE /api/v1/connectors/
删除连接器及其同步配置。已同步的历史数据不会被删除。
成功响应（204）： 无返回体
健康检查
GET /api/v1/connectors/{connector_id}/health
检查连接器的连接状态和授权有效性。
成功响应（200）：
json
{
"code": 200,
"message": "success",
"data": {
"connector_id": "uuid-string",
"status": "healthy",
"checks": {
"auth_valid": true,
"api_reachable": true,
"rate_limit_ok": true,
"last_error": null
},
"auth_expires_at": "2026-06-20T08:00:00Z",
"checked_at": "2026-03-14T10:30:00Z"
}
}健康状态说明：
| 状态 | 说明 |
|---|---|
healthy | 连接正常，授权有效 |
degraded | 部分功能受限（如接近速率限制） |
unhealthy | 连接异常或授权过期 |
unknown | 尚未进行健康检查 |
数据同步
商品同步
POST /api/v1/connectors/{connector_id}/sync/products
触发商品数据的即时同步。
请求体（可选）：
json
{
"mode": "incremental",
"since": "2026-03-13T00:00:00Z"
}| 参数 | 说明 |
|---|---|
mode | full（全量）/ incremental（增量，默认） |
since | 增量同步的起始时间（仅增量模式有效） |
成功响应（202）：
json
{
"code": 202,
"message": "同步任务已提交",
"data": {
"task_id": "uuid-string",
"connector_id": "uuid-string",
"sync_type": "products",
"mode": "incremental",
"status": "queued",
"created_at": "2026-03-14T10:30:00Z"
}
}订单同步
POST /api/v1/connectors/{connector_id}/sync/orders
触发订单数据的即时同步。请求参数与商品同步相同。
库存同步
POST /api/v1/connectors/{connector_id}/sync/inventory
触发库存数据的即时同步。
获取同步任务状态
GET /api/v1/connectors/{connector_id}/sync/tasks/
成功响应（200）：
json
{
"code": 200,
"message": "success",
"data": {
"task_id": "uuid-string",
"connector_id": "uuid-string",
"sync_type": "products",
"mode": "incremental",
"status": "completed",
"progress": {
"total": 1250,
"synced": 1250,
"failed": 0,
"skipped": 3
},
"started_at": "2026-03-14T10:30:05Z",
"completed_at": "2026-03-14T10:30:50Z",
"duration_seconds": 45
}
}任务状态：
| 状态 | 说明 |
|---|---|
queued | 排队中 |
running | 同步进行中 |
completed | 同步完成 |
failed | 同步失败 |
cancelled | 已取消 |
连接器类型
GET /api/v1/connectors/types
获取系统支持的连接器类型列表。
成功响应（200）：
json
{
"code": 200,
"message": "success",
"data": [
{
"platform": "tmall",
"display_name": "天猫",
"icon_url": "/icons/tmall.svg",
"supported_sync_types": ["products", "orders", "inventory", "reviews"],
"auth_type": "oauth2",
"min_sync_interval_minutes": 5,
"config_schema": {
"app_key": {"type": "string", "required": true},
"app_secret": {"type": "string", "required": true, "sensitive": true},
"shop_id": {"type": "string", "required": true}
}
},
{
"platform": "douyin",
"display_name": "抖音电商",
"icon_url": "/icons/douyin.svg",
"supported_sync_types": ["products", "orders", "livestream"],
"auth_type": "oauth2",
"min_sync_interval_minutes": 15,
"config_schema": {
"app_id": {"type": "string", "required": true},
"app_secret": {"type": "string", "required": true, "sensitive": true}
}
}
]
}Webhook 回调
连接器支持 Webhook 回调，在以下事件发生时通知您的系统：
| 事件 | 说明 |
|---|---|
sync.completed | 同步任务完成 |
sync.failed | 同步任务失败 |
connector.disconnected | 连接器断开（授权过期等） |
connector.error | 连接器出错 |
配置 Webhook
bash
POST /api/v1/connectors/{connector_id}/webhooks
Content-Type: application/json
{
"url": "https://your-system.com/webhook/nolux",
"events": ["sync.completed", "sync.failed"],
"secret": "your_webhook_secret"
}Webhook 请求会包含 X-Nolux-Signature 头，使用 HMAC-SHA256 签名验证请求真实性。