新网AI建站文档 返回工作台

接口

站点数据接口

用站点级 API 密钥在你自己的系统里读写网站后台的业务数据(产品、案例、询盘等),并上传图片和文件。

更新于 2026-11-15

站点数据接口让你在自己的系统里读写网站后台的业务数据。常见用法:从 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": "…" } }
状态码错误码说明
401INVALID_KEY密钥无效或已撤销
403READ_ONLY只读密钥不能写
403TABLE_READ_ONLY这张表由平台写入,只能读
403SITE_MISMATCH密钥只能访问它绑定的网站
403SITE_UNAVAILABLE网站已删除、已转交或正在处理中
404TABLE_NOT_FOUND / RECORD_NOT_FOUND没有这张表 / 这条记录
409RECORD_CONFLICT这个编号已经有一条内容不同的记录
409ENVIRONMENT_NOT_READY正式环境还没就绪(网站没发布过)
422FIELD_UNKNOWN / VALUE_INVALID / IMAGE_NOT_SITE_FILE字段不存在、值不合要求、图片不是本站文件
429RATE_LIMITED请求太频繁
503UNAVAILABLE服务暂时不可用,稍后重试

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

限流

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

撤销与失效

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