# SyncBridge 合作伙伴集成 API 规范

**版本**：2.4.0  
**最后更新**：2026-04-10  
**作者**：台湾集成团队 — Wei-Lin Chen、Mei-Hua Tsai  
**状态**：最终审查

---

## 1. 概述

SyncBridge 是一个企业级数据同步平台（enterprise-grade data synchronization platform），可在合作伙伴系统之间实现实时双向数据流转。本文档规定了集成合作伙伴必须实现的 REST API，以便将其服务接入 SyncBridge 生态系统。

本 API 遵循 RESTful 规范，所有请求与响应的载荷（Payload）均采用 JSON 格式。身份验证（Authentication）通过 OAuth 2.0 客户端凭证流程结合 JWT 持有者令牌（Bearer Token）来完成。所有端点均强制执行速率限制（Rate Limiting），且传输层安全性要求使用 TLS 1.2 或更高版本。

### 1.1 目标读者

本规范面向正在构建其平台与 SyncBridge 连接器的后端工程师及集成架构师。读者应具备 REST API、OAuth 2.0 以及基于 Webhook 的事件系统的相关知识。

### 1.2 基础 URL

所有 API 端点均相对于合作伙伴已注册的基础 URL：

```
https://{partner-domain}/api/v2/syncbridge
```

基础 URL 在合作伙伴接入（Onboarding）期间完成配置，并存储于 SyncBridge API 网关（API Gateway）的配置中。合作伙伴可以为预发布环境和生产环境分别注册不同的基础 URL。

### 1.3 版本控制

本 API 采用基于 URL 的版本控制方式（`/v2/`）。重大变更（Breaking Changes）将递增主版本号；非重大的新增内容（如新增可选字段、新增端点）则在当前版本内直接添加。合作伙伴应在处理响应载荷时对未知字段实现容错处理。

---

## 2. 身份验证与授权

### 2.1 OAuth 2.0 流程

SyncBridge 采用 OAuth 2.0 客户端凭证（Client Credentials）流程进行服务端到服务端的身份验证。合作伙伴在接入时会获得 `client_id` 和 `client_secret`。

**令牌端点**：
```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}
&scope=syncbridge.read syncbridge.write syncbridge.admin
```

**响应**：
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "syncbridge.read syncbridge.write syncbridge.admin"
}
```

访问令牌（Access Token）是一个已签名的 JWT，其中包含合作伙伴的身份标识、已授权的权限范围（Scope）以及过期时间戳。后续所有 API 请求均必须在 `Authorization` 请求头中携带该令牌。

### 2.2 令牌验证

合作伙伴必须使用以下地址发布的公钥，对来自 SyncBridge 的入站令牌进行验证：

```
GET /oauth/.well-known/jwks.json
```

验证步骤：
1. 使用已发布的公钥验证 JWT 签名（Signature）
2. 检查 `exp` 声明（Claim）是否已过期
3. 验证 `iss` 声明是否匹配 `https://auth.syncbridge.io`
4. 验证 `aud` 声明是否包含合作伙伴已注册的 Client ID
5. 检查 `scope` 声明中是否存在所需的权限范围

### 2.3 凭证轮换

合作伙伴应至少每 90 天轮换一次 Client Secret。凭证轮换（Credential Rotation）端点支持零停机轮换：在可配置的宽限期（Grace Period，默认 24 小时）内，允许同时存在两个有效的 Secret。

```
POST /admin/credentials/rotate
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "grace_period_hours": 24
}
```

**响应**：
```json
{
  "new_client_secret": "sb_secret_v2_...",
  "old_secret_valid_until": "2026-04-11T14:30:00Z",
  "rotation_id": "rot_8f3a2b1c"
}
```

---

## 3. 核心数据端点

### 3.1 实体同步

实体同步（Entity Sync）端点是 SyncBridge 与合作伙伴系统之间交换数据的主要机制，支持推送（Push，SyncBridge → Partner）和拉取（Pull，Partner → SyncBridge）两种操作模式。

#### 3.1.1 接收实体（推送模式）

当源系统发生变更时，SyncBridge 会将实体（Entity）更新推送至合作伙伴的端点。

```
POST /entities/sync
Authorization: Bearer {access_token}
Content-Type: application/json
X-SyncBridge-Idempotency-Key: {uuid}
X-SyncBridge-Batch-Id: {batch_uuid}

{
  "batch_id": "batch_a1b2c3d4",
  "source_system": "crm",
  "entities": [
    {
      "entity_id": "ent_001",
      "entity_type": "contact",
      "operation": "upsert",
      "timestamp": "2026-04-10T08:15:30Z",
      "data": {
        "name": "Alice Wang",
        "email": "alice@example.com",
        "phone": "+886-2-1234-5678",
        "tags": ["enterprise", "priority"],
        "metadata": {
          "source_region": "APAC",
          "last_activity": "2026-04-09T16:42:00Z"
        }
      },
      "schema_version": "2.1"
    }
  ],
  "pagination": {
    "page": 1,
    "total_pages": 3,
    "total_entities": 250
  }
}
```

**必须在 30 秒内返回的响应**：

```json
{
  "batch_id": "batch_a1b2c3d4",
  "status": "accepted",
  "results": [
    {
      "entity_id": "ent_001",
      "status": "success",
      "partner_id": "p_contact_12345"
    }
  ],
  "processing_time_ms": 142
}
```

**错误响应**：

```json
{
  "batch_id": "batch_a1b2c3d4",
  "status": "partial_failure",
  "results": [
    {
      "entity_id": "ent_001",
      "status": "error",
      "error": {
        "code": "VALIDATION_FAILED",
        "message": "Field 'email' failed format validation",
        "field": "data.email",
        "retry_eligible": true
      }
    }
  ]
}
```

#### 3.1.2 提供实体（拉取模式）

SyncBridge 会定期从合作伙伴系统拉取实体数据。合作伙伴必须实现此端点，返回自指定游标（Cursor）时间戳以来发生变更的实体。

```
GET /entities?since={iso_timestamp}&limit={n}&cursor={opaque_cursor}
Authorization: Bearer {access_token}
Accept: application/json
```

**查询参数**：

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `since` | ISO 8601 | 是（首次请求） | — | 返回该时间戳之后发生变更的实体 |
| `limit` | integer | 否 | 100 | 每页返回的最大实体数量（上限 500） |
| `cursor` | string | 否 | — | 上次响应中返回的不透明分页游标 |
| `entity_type` | string | 否 | all | 按实体类型筛选 |
| `include_deleted` | boolean | 否 | false | 是否包含软删除的实体 |

**响应**：

```json
{
  "entities": [
    {
      "entity_id": "p_contact_12345",
      "entity_type": "contact",
      "operation": "upsert",
      "timestamp": "2026-04-10T09:00:00Z",
      "data": {
        "name": "Bob Lin",
        "email": "bob@partner.tw",
        "department": "Engineering"
      },
      "schema_version": "2.1"
    }
  ],
  "pagination": {
    "cursor": "eyJsYXN0X2lkIjoiMTIzNDUifQ==",
    "has_more": true,
    "total_estimate": 1500
  }
}
```

### 3.2 Schema 注册中心

合作伙伴必须将其实体 Schema 注册到 SyncBridge，以便在同步时对字段映射（Field Mapping）进行验证。Schema 注册中心（Schema Registry）提供了一组用于管理这些 Schema 的端点。

#### 3.2.1 注册 Schema

```
PUT /schemas/{entity_type}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "entity_type": "contact",
  "version": "2.1",
  "fields": [
    {
      "name": "name",
      "type": "string",
      "required": true,
      "max_length": 255,
      "description": "Full name of the contact"
    },
    {
      "name": "email",
      "type": "string",
      "required": true,
      "format": "email",
      "description": "Primary email address"
    },
    {
      "name": "phone",
      "type": "string",
      "required": false,
      "format": "e164",
      "description": "Phone number in E.164 format"
    },
    {
      "name": "tags",
      "type": "array",
      "items_type": "string",
      "required": false,
      "description": "Classification tags"
    },
    {
      "name": "metadata",
      "type": "object",
      "required": false,
      "description": "Extensible metadata key-value pairs"
    }
  ],
  "indexes": ["email", "phone"],
  "primary_key": "entity_id"
}
```

#### 3.2.2 验证 Schema 兼容性

在部署新 Schema 版本之前，合作伙伴可以验证其与 SyncBridge 中已注册的前一版本是否向后兼容。

```
POST /schemas/{entity_type}/validate
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "proposed_version": "2.2",
  "fields": [ ... ]
}
```

**响应**：

```json
{
  "compatible": true,
  "warnings": [
    {
      "type": "NEW_OPTIONAL_FIELD",
      "field": "linkedin_url",
      "message": "New optional field added — existing integrations will not be affected"
    }
  ],
  "breaking_changes": []
}
```