接口
站点数据接口
用站点级 API 密钥在你自己的系统里读写网站后台的业务数据(产品、案例、询盘等),并上传图片和文件。
更新于 2026-11-15站点数据接口让你在自己的系统里读写网站后台的业务数据。常见用法:从 ERP 同步产品到官网,把询盘导入 CRM,定时更新价格。
接口只能碰网站后台里你自己的业务表——就是在「运营」里能看到的那些表。会员账号、支付流水、通知记录这类平台数据不在里面,要用工作台里对应的功能管理。
第一步:建密钥
- 打开网站的「设置 · 开放能力 · API 密钥」,点「新建密钥」。
- 选环境:
- 正式环境:线上网站的数据。网站正式发布后才能选。
- 预览环境:还没发布的数据,适合联调。
- 选权限:只读,或读写(可以新建、修改、删除记录和上传文件)。
- 复制密钥。密钥只显示这一次,关掉就看不到了;丢了就撤销,再建一把。
密钥只能放在服务器上(比如环境变量),不要写进网页或小程序代码。接口不允许跨域,浏览器里也调不通。
第二步:调用
接口地址:https://aida.xinnet.com/api/v1/sites/<网站编号>。网站编号和完整地址在「API 密钥」页的「本站接口说明」里。
每个请求带上请求头:
Authorization: Bearer <密钥>推荐用官方 SDK(Node 18 以上):
npm install https://aida.xinnet.com/docs/downloads/aida-sdk.tgzimport { 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
{
"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
{
"select": ["id", "model", "price"],
"filters": [{ "key": "price", "op": "gte", "value": 10 }],
"order": [{ "key": "model", "dir": "asc" }],
"offset": 0,
"limit": 20
}- 每个参数都可以省略。不写
select返回全部字段。 op可用:eqneqgtgteltltelikeilikeisisnotin。in的value是数组。- 每页最多 100 条,
offset + limit不超过 10000。要读更深,按时间或编号筛选后分段读。
返回 { "records": [...], "total": 128, "offset": 0, "limit": 20 }。
新建
POST/tables/<表名>/records
{ "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> 也一样。
上传分三步,文件直接传到存储,不经过工作台:
- 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。 - 把文件按
part_size切片,用PUT把每片发到对应的upload_url,带上required_headers。不要带你的密钥。 分片多的话第一次只给前 100 片的地址,其余用 GET/uploads/<upload_id>?sign=101,102,…&content_type=image/png取。 - 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> 放弃这次上传。
错误
错误统一是这个格式:
{ "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 密钥」页撤销后,用这把密钥的请求立即失败。已撤销的密钥可以删除。
- 「更换」会生成一把新密钥(只显示一次),旧的立即失效,名称、环境和权限不变——泄露或定期轮换时用它,不必重配。
- 网站删除、转交给别的账号后,它的密钥立即失效。
- 每把密钥的最近使用时间显示在列表里;写入、删除操作都会记录是哪把密钥做的。