用一把 API Key,
把商家自己的 AI 客服接进你的产品。
接口会使用该商家的知识库与话术规则作答,答案限定在商家业务范围内;每次调用按平台配置扣除商家积分,调用量与消耗可在商家端与总后台查询。
限定知识范围
只答商家资料里的内容,超出范围会坦诚说明
多语言
zh / en / ja / ko,回复语言随 locale
按次计费
每次 /v1/chat 扣固定积分,余额不足直接拒绝
快速开始
三步拿到第一次回复,密钥只在创建时明文展示一次。
- 1登录 商家端,进入「API 接入」创建密钥。
- 2复制形如
xy_live_...的密钥,保存到你的服务端环境变量。 - 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-Type | application/json |
对话接口
单轮问答;需要多轮上下文时,把最近几轮对话放进 history 一起传。
/api/v1/chat请求参数
message | string | 必填,用户问题,≤2000 字 |
locale | string | 可选,zh / en / ja / ko,默认 zh |
history | array | 可选,[{role:'user'|'assistant', content}],最多 6 轮 |
context | object | 可选,{ 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 元" }
]
}商家信息接口
用同一把密钥获取商家公开信息与当前每次调用的积分价格。
/api/v1/merchant{
"code": 200,
"data": {
"code": "YUNQI",
"name": "云栖茶业",
"brandColor": "#2f7d5d",
"languages": "zh,en,ja,ko",
"defaultLocale": "zh",
"balance": 11997,
"apiCallPoints": 3
}
}订单 / 物流接入
客户问「我的订单到哪了」时,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 |
400 | message 为空或过长 | 检查请求体 |
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 直接调用。