# 站点数据接口


# 站点数据接口

站点数据接口让你在自己的系统里读写网站后台的业务数据。常见用法：从 ERP 同步产品到官网，把询盘导入 CRM，定时更新价格。

接口只能碰网站后台里**你自己的业务表**——就是在「运营」里能看到的那些表。会员账号、支付流水、通知记录这类平台数据不在里面，要用工作台里对应的功能管理。

## 第一步：建密钥

1. 打开网站的「设置 · 开放能力 · API 密钥」，点「新建密钥」。
2. 选环境：
   - **正式环境**：线上网站的数据。网站正式发布后才能选。
   - **预览环境**：还没发布的数据，适合联调。
3. 选权限：**只读**，或**读写**（可以新建、修改、删除记录和上传文件）。
4. 复制密钥。密钥只显示这一次，关掉就看不到了；丢了就撤销，再建一把。

密钥只能放在服务器上（比如环境变量），不要写进网页或小程序代码。接口不允许跨域，浏览器里也调不通。

## 第二步：调用

接口地址：`https://aida.xinnet.com/api/v1/sites/<网站编号>`。网站编号和完整地址在「API 密钥」页的「本站接口说明」里。

每个请求带上请求头：

```
Authorization: Bearer <密钥>
```

推荐用官方 SDK（Node 18 以上）：

```bash
npm install https://aida.xinnet.com/docs/downloads/aida-sdk.tgz
```

```js
import { AidaSite } from "aida-sdk";
const site = new AidaSite({ baseUrl: "https://aida.xinnet.com", site: "<网站编号>", key: process.env.AIDA_SITE_KEY });
const { records } = await site.table("products").query({ limit: 20 });
```

「本站接口说明」里还有一个「复制给 AI 编程工具」按钮：复制出来的说明里有本站的表和字段、接口用法，交给 Cursor、Claude Code 这类工具就能直接写对接代码。说明里不含密钥。

## 接口

### 列出表与字段

`GET /tables`

```json
{
  "environment": "production",
  "access": "write",
  "tables": [
    {
      "name": "products",
      "label": "产品",
      "read_only": false,
      "fields": [
        { "name": "id", "label": null, "type": "id", "required": false, "generated": true },
        { "name": "model", "label": "型号", "type": "text", "required": true, "generated": false },
        { "name": "image", "label": "图片", "type": "image", "required": false, "generated": false }
      ]
    }
  ]
}
```

字段类型：`id`、`text`、`number`、`boolean`、`date`、`datetime`、`image`、`file`、`richtext`、`json`。`generated` 为真的字段由系统生成，新建时可以不填。`read_only` 为真的表由平台写入（比如在线下单的订单），只能读。

### 查询

`POST /tables/<表名>/query`

```json
{
  "select": ["id", "model", "price"],
  "filters": [{ "key": "price", "op": "gte", "value": 10 }],
  "order": [{ "key": "model", "dir": "asc" }],
  "offset": 0,
  "limit": 20
}
```

- 每个参数都可以省略。不写 `select` 返回全部字段。
- `op` 可用：`eq` `neq` `gt` `gte` `lt` `lte` `like` `ilike` `is` `isnot` `in`。`in` 的 `value` 是数组。
- 每页最多 100 条，`offset + limit` 不超过 10000。要读更深，按时间或编号筛选后分段读。

返回 `{ "records": [...], "total": 128, "offset": 0, "limit": 20 }`。

### 新建

`POST /tables/<表名>/records`

```json
{ "id": "7f3c2a8e-…", "values": { "model": "6204", "price": 12.5 } }
```

`id` 可以不填，由系统生成。建议自己生成一个 UUID：网络断了用同一个 `id` 重试，内容一样就返回原记录（`replayed: true`），不会建出两条；内容不一样返回 409 `RECORD_CONFLICT`。

### 修改与删除

- `PATCH /tables/<表名>/records/<id>`，请求体 `{ "values": { ... } }`，只改给出的字段。
- `DELETE /tables/<表名>/records/<id>`。

只能按编号改、删一条，不支持按条件批量改删。

## 上传图片和文件

图片、文件字段只能填**本站文件地址**。填外链会返回 422 `IMAGE_NOT_SITE_FILE`。富文本里的 `<img>` 也一样。

上传分三步，文件直接传到存储，不经过工作台：

1. `POST /uploads`，请求体 `{ "request_id": "<UUID>", "file_name": "6204.png", "content_type": "image/png", "size_bytes": 102400 }`。
   返回 `upload_id`、分片大小 `part_size`、分片数 `part_count`、起始分片号 `first_part_number`，以及每片的上传地址 `parts[].upload_url` 和请求头 `parts[].required_headers`。
2. 把文件按 `part_size` 切片，用 `PUT` 把每片发到对应的 `upload_url`，带上 `required_headers`。**不要带你的密钥**。
   分片多的话第一次只给前 100 片的地址，其余用 `GET /uploads/<upload_id>?sign=101,102,…&content_type=image/png` 取。
3. `POST /uploads/<upload_id>/complete`，返回 `{ "file_id", "url" }`。把 `url` 填进图片字段。

用 SDK 一行就够：`const image = await site.upload(bytes, "6204.png", "image/png")`。

上传的文件计入网站的存储空间。`GET /uploads/<upload_id>` 能查到已经传了哪几片，用来续传；`DELETE /uploads/<upload_id>` 放弃这次上传。

## 错误

错误统一是这个格式：

```json
{ "error": { "code": "TABLE_NOT_FOUND", "message": "本站没有这张表", "request_id": "…" } }
```

| 状态码 | 错误码 | 说明 |
|---|---|---|
| 401 | `INVALID_KEY` | 密钥无效或已撤销 |
| 403 | `READ_ONLY` | 只读密钥不能写 |
| 403 | `TABLE_READ_ONLY` | 这张表由平台写入，只能读 |
| 403 | `SITE_MISMATCH` | 密钥只能访问它绑定的网站 |
| 403 | `SITE_UNAVAILABLE` | 网站已删除、已转交或正在处理中 |
| 404 | `TABLE_NOT_FOUND` / `RECORD_NOT_FOUND` | 没有这张表 / 这条记录 |
| 409 | `RECORD_CONFLICT` | 这个编号已经有一条内容不同的记录 |
| 409 | `ENVIRONMENT_NOT_READY` | 正式环境还没就绪（网站没发布过） |
| 422 | `FIELD_UNKNOWN` / `VALUE_INVALID` / `IMAGE_NOT_SITE_FILE` | 字段不存在、值不合要求、图片不是本站文件 |
| 429 | `RATE_LIMITED` | 请求太频繁 |
| 503 | `UNAVAILABLE` | 服务暂时不可用，稍后重试 |

联系我们排查时请带上 `request_id`。

## 限流

默认每个账号每分钟 300 次（名下所有密钥合计），瞬时最多连发 60 次。超出返回 429，按响应头 `Retry-After` 的秒数等待后重试。每个响应都带 `X-RateLimit-Limit` 和 `X-RateLimit-Remaining`。需要更高的额度请联系我们。

## 撤销与失效

- 在「API 密钥」页撤销后，用这把密钥的请求立即失败。已撤销的密钥可以删除。
- 「更换」会生成一把新密钥（只显示一次），旧的立即失效，名称、环境和权限不变——泄露或定期轮换时用它，不必重配。
- 网站删除、转交给别的账号后，它的密钥立即失效。
- 每把密钥的最近使用时间显示在列表里；写入、删除操作都会记录是哪把密钥做的。
