---
topic: RESTful API 接入速查
sources:
  - raw/接入指南/restful-api-使用指南.md
  - raw/接入前准备工作/数据规则.md
  - raw/接入前准备工作/用户识别规则.md
generated: 2026-04-15
---

# RESTful API 接入速查

AE RESTful API 允许在不集成 SDK 或传输工具的情况下，通过 HTTP POST 直接向 AE 上报数据。适用于脚本对接、第三方系统集成、快速验证等场景 [[raw/接入指南/restful-api-使用指南.md]]。

## 接入前提

上报数据必须遵循 AE 数据格式，详见 [[raw/接入前准备工作/数据规则.md]]。用户 ID 需同时包含 `#account_id`（登录后）或 `#distinct_id`（未登录），详见 [[raw/接入前准备工作/用户识别规则.md]]。

## 接口地址

| 部署类型 | form-data 接口 | raw JSON 接口 |
|---|---|---|
| 云服务 | `https://global-receiver-ta.thinkingdata.cn/sync_data` | `https://global-receiver-ta.thinkingdata.cn/sync_json` |
| 私有化部署 | `http://数据采集地址/sync_data` | `http://数据采集地址/sync_json` |

## 方式一：form-data 上报（`/sync_data`）

### 单条数据

```bash
# 原始 JSON
{
  "#account_id": "testing",
  "#time": "2019-01-01 10:00:00.000",
  "#type": "track",
  "#event_name": "testing",
  "properties": { "test": "test" }
}

# urlencode 后
curl "http://receiver:9080/sync_data" \
  --data "appid=YOUR_APP_ID&data=%7b%22%23account_id%22%3a%22testing%22...%7d"
```

### 多条数据

```bash
curl "http://receiver:9080/sync_data" \
  --data "appid=YOUR_APP_ID&data_list=URLENCODed_JSON_ARRAY"
```

### 请求参数

| 参数 | 说明 | 必填 |
|---|---|---|
| `appid` | 项目 APP ID | 是 |
| `data` | 单条 JSON，UTF-8 + urlencode | 二选一 |
| `data_list` | JSONArray 格式多条数据，UTF-8 + urlencode | 二选一 |
| `client` | 0（默认）/ 1（强制用上报端 IP 替换 `#ip`） | 否 |
| `debug` | 0（关闭）/ 1（开启调试，返回详细错误） | 否 |

**注意**：Python3 requests 库、Postman 等工具会自动 urlencode，无需手动编码。

## 方式二：raw JSON 上报（`/sync_json`）

### 单条数据

```bash
curl -X POST "https://global-receiver-ta.thinkingdata.cn/sync_json" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "YOUR_APP_ID",
    "debug": 0,
    "data": {
      "#type": "track",
      "#event_name": "test",
      "#time": "2019-11-15 11:35:53.648",
      "#distinct_id": "visitor-001",
      "properties": { "a": "123", "b": 2 }
    }
  }'
```

### 多条数据

```bash
curl -X POST "https://global-receiver-ta.thinkingdata.cn/sync_json" \
  -H "Content-Type: application/json" \
  -d '[
    { "appid": "YOUR_APP_ID", "data": { "#type": "track", ... } },
    { "appid": "YOUR_APP_ID", "data": { "#type": "track", ... } }
  ]'
```

## 返回码

| code | 含义 |
|---|---|
| `0` | 上报成功 |
| `-1` | 数据格式错误（开启 debug 模式时返回详细原因） |

Debug 示例错误响应：
```json
{"code":-1,"msg":"#time字段格式不对,需传递[yyyy-MM-dd HH:mm:ss]或者[yyyy-MM-dd HH:mm:ss.SSS]格式"}
```

## 数据结构速查

[[raw/接入前准备工作/数据规则.md]]

```json
{
  "#account_id": "ABCDEFG-123",        // 登录 ID（与 #distinct_id 至少一个必填）
  "#distinct_id": "UUID-xxx",          // 访客 ID
  "#type": "track",                    // 数据类型
  "#time": "2026-01-01 10:00:00.000", // 时间，精确到秒或毫秒
  "#event_name": "event_name",         // 事件名（type=track 时必填）
  "#ip": "1.2.3.4",                    // 可选，用于地理信息
  "#uuid": "unique-uuid",              // 可选，用于去重
  "properties": {
    "key": "value"                     // 自定义属性
  }
}
```

`#type` 枚举值：

| 值 | 含义 |
|---|---|
| `track` | 普通事件 |
| `track_update` | 可更新事件 |
| `track_overwrite` | 可覆盖事件 |
| `user_set` | 设置用户属性（覆盖） |
| `user_setOnce` | 首次设置用户属性 |
| `user_add` | 用户属性数值累加 |
| `user_unset` | 清空用户属性 |
| `user_append` | 用户属性数组追加 |
| `user_del` | 删除用户 |

## Debug 模式建议

- `debug=1` 时每条数据都会校验并立即入库，**仅用于测试少量数据**
- **禁止在生产环境开启 debug 模式**，会严重影响上报性能
