星语智服XINGYU AI
OPEN API · V1

用一把 API Key,把商家自己的 AI 客服接进你的产品。

接口会使用该商家的知识库与话术规则作答,答案限定在商家业务范围内;每次调用按平台配置扣除商家积分,调用量与消耗可在商家端与总后台查询。

限定知识范围

只答商家资料里的内容,超出范围会坦诚说明

多语言

zh / en / ja / ko,回复语言随 locale

按次计费

每次 /v1/chat 扣固定积分,余额不足直接拒绝

快速开始

三步拿到第一次回复,密钥只在创建时明文展示一次。

  1. 1登录 商家端,进入「API 接入」创建密钥。
  2. 2复制形如 xy_live_... 的密钥,保存到你的服务端环境变量。
  3. 3带上 X-Api-Key 请求头调用接口。
# 自测(把 BASE 换成你的部署域名)
curl -X POST "https://你的域名/api/v1/chat" \
  -H "X-Api-Key: xy_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message":"你们有什么招牌茶?多少钱","locale":"zh"}'

鉴权

所有请求都要带商家密钥;密钥代表商家账户,请只放在服务端。

Header说明
X-Api-Key商家端创建的密钥,缺失或无效返回 401
Content-Typeapplication/json

对话接口

单轮问答;需要多轮上下文时,把最近几轮对话放进 history 一起传。

POST/api/v1/chat

请求参数

messagestring必填,用户问题,≤2000 字
localestring可选,zh / en / ja / ko,默认 zh
historyarray可选,[{role:'user'|'assistant', content}],最多 6 轮
contextobject可选,{ orderId, userToken };orderId 用于订单查询,userToken 会原样转发给你的 webhook

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "reply": "卖得最好的是明前龙井……",
    "locale": "zh",
    "points": 3,
    "balance": 11997,
    "refs": 6,
    "usedAi": true
  }
}
// 多轮对话:把上一轮结果带上
{
  "message": "那大杯呢?",
  "locale": "zh",
  "history": [
    { "role": "user", "content": "明前龙井多少钱" },
    { "role": "assistant", "content": "中杯 22 元,大杯 26 元" }
  ]
}

商家信息接口

用同一把密钥获取商家公开信息与当前每次调用的积分价格。

GET/api/v1/merchant
{
  "code": 200,
  "data": {
    "code": "YUNQI",
    "name": "云栖茶业",
    "brandColor": "#2f7d5d",
    "languages": "zh,en,ja,ko",
    "defaultLocale": "zh",
    "balance": 11997,
    "apiCallPoints": 3
  }
}

订单 / 物流接入

客户问「我的订单到哪了」时,AI 需要商家的实时数据。这里给了三种接入方式,按你的技术条件选一种即可。

共同规则:AI 只转述你返回的字段,不会编造进度;查不到时明确说「看不到订单状态」,不会承诺转人工、回电或“让同事跟进”。订单数据默认不落我们的库,只记录调用元数据(时间、工具、耗时、是否成功)。

方式一:Webhook 实时查询(有开发能力)

在商家端「订单接入」页填写你的接口地址并生成签名密钥。我们识别到订单意图后,会 POST 到你的地址,3 秒超时。

POST https://your-shop.com/api/xingyu/orders
X-Xingyu-Tool: order.logistics
X-Xingyu-Signature: t=1735689600,v1=<hex hmac-sha256>

{
  "tool": "order.logistics",
  "args": { "orderNo": "AB12345678" },
  "userToken": "user-session-token-or-null",
  "merchantCode": "YUNQI",
  "ts": 1735689600000
}

返回结构固定为 { ok: true, data: {...} };ok:false 或 HTTP 非 2xx 时,AI 会告知用户暂时查不到:

{
  "ok": true,
  "data": {
    "orderNo": "AB12345678",
    "status": "已发货,运输中",
    "carrier": "顺丰速运",
    "trackingNo": "SF1234567890123",
    "eta": "预计 11 月 19 日送达"
  }
}

// 查不到
{ "ok": false, "error": "order_not_found" }

服务端校验签名(Node.js 示例):

const crypto = require('crypto');
const body = rawBody;                    // 原始请求体字符串
const [t, v1] = req.headers['x-xingyu-signature']
  .replace('t=', '').split(',v1=');
const expect = crypto.createHmac('sha256', process.env.XINGYU_SECRET)
  .update(t + '.' + body).digest('hex');
if (expect !== v1) return res.status(401).end();
// 建议再校验时间戳:Math.abs(Date.now()/1000 - Number(t)) < 300

支持的工具:order.status、order.logistics、order.refund;只做只读查询,写操作(改地址、退款)不会被调用。

方式二:订单快照导入(不懂技术也能用)

从商城后台导出订单表,另存为 CSV,在「订单接入 → 订单快照」直接上传。表头中英文都可以,推荐:

order_no,status,carrier,tracking_no
AB12345678,已发货 运输中,顺丰速运,SF1234567890123
CD98765432,待发货,,
// 也支持中文表头:订单号,状态,承运商,运单号

导入后,客户问「订单 AB12345678 到哪了」就能答出状态。重复订单号会覆盖更新;建议每天或每次发货后重新导入一次。手机号、地址等字段不会被读取。

方式三:订单页链接(零接入)

在商家端填一个订单查询页模板,例如 https://your-shop.com/orders/{orderNo}。AI 查不到进度时,会把用户的问题里的订单号填进链接,引导用户自己去看;没有订单号时,引导到「我的订单」。

调用示例(带订单号)

curl -X POST "https://your-domain/api/v1/chat"   -H "X-Api-Key: xy_live_xxxxxxxx"   -H "Content-Type: application/json"   -d '{
    "message": "我的订单到哪了",
    "locale": "zh",
    "context": { "orderId": "AB12345678", "userToken": "session-xxx" }
  }'

响应新增 orderTool(实际调用的工具)与 orderResolved(是否取到实时数据),便于你排查对接问题。

错误码

HTTP 状态码之外,业务码在响应体 code 字段里;失败时 data 为 null。

code场景处理建议
200成功读取 data.reply
400message 为空或过长检查请求体
401密钥缺失 / 无效 / 已停用检查 X-Api-Key,或在商家端重新创建
402商家积分不足提示商家充值,本次不扣费
403商家已停用联系平台运营

计费与额度

开放接口按次计费,与页面会话的 token/字符计费相互独立。

  • · 每次成功调用扣除「开放 API 单次积分」,具体数值由平台在总后台配置,可用 GET /api/v1/merchant 查询。
  • · 余额不足返回 402,不产生扣费、不返回答案。
  • · 每次调用的积分、调用量都会记入商家的 API 用量,可在商家端「API 接入」与总后台「API 用量」查看。
  • · 密钥可创建多把(按业务线区分),可随时停用或删除,删除后立即失效。

接入建议

几条能省掉线上事故的实践。

密钥只放服务端

浏览器、App 内不要直连本接口,由你的后端转发。

做好超时与降级

模型回复通常 1–4 秒,建议客户端超时 ≥20 秒并准备兜底文案。

把 history 控制在 6 轮内

太长会稀释知识命中,也会增加成本。

按业务线拆密钥

每条业务线一把,出问题可单独停用,用量也更好归因。

想先试一下?用演示商家登录商家端(yunqi / merchant123),在「API 接入」创建密钥,即可按上面的 curl 直接调用。