Shopify 官方对接 + 自研商城 OpenAPI

会查订单的AI 客服

本页是完整接入说明：两种方式怎么选、每个能力怎么工作、安全边界在哪 —— 全部基于真实实现整理，不含营销话术。

✦ 无论你的商城用什么技术栈，都能接 —— 语言不限，主流系统开箱适配

Python Node.js PHP Java Go WordPress（WooCommerce） CRMEB Shopify 自研框架均可
为什么需要

不止能聊天，更能查数据

同样是"智能客服"，能不能查真实数据，访客体验天差地别

我的订单 ORD20260725001 到哪了？
抱歉，请您提供一下订单信息，我帮您转接人工查询 传统机器人 · 只能背话术
我的订单 ORD20260725001 到哪了？
您好张三！您的订单 已发货（顺丰速运 SF1234567890），最新轨迹：今日 14:30 派送中，预计明天送达。还有其他需要帮您的吗？本平台 · AI 实时查询商城真实数据
AI 实时查订单
AI 已查到订单 · 物流实时同步
01

AI 实时查订单 / 物流 / 退款 / 活动

从"话术机器人"到"能动手的业务员"

访客提供订单号（或手机尾号验证身份），AI 实时调用你商城的接口查询订单状态、物流轨迹、退款进度，并用自然语言回复。访客问"有什么优惠"，AI 查询进行中的活动与优惠券主动介绍。

  • 订单：状态/金额/明细实时查询
  • 物流：快递公司/运单号/轨迹
  • 退款：AI 发起，默认人工审批
  • 活动：折扣与优惠券主动触达
会员昵称直显 · 商品上下文自动携带
02

会员昵称 + 商品卡片

客服开口就是"张三您好"

匿名访客在工作台是"网站访客-a3b7c9d2"，无法个性化沟通。对接后：登录会员咨询，工作台直接显示昵称，重复咨询保持；商品详情页咨询自动携带"正在咨询的商品"条，客服一眼知道对方在看什么、多少钱。

  • 昵称直显，重复进入保持
  • 商品卡片一键发送
  • 未登录仍匿名，互不影响
  • web-view 场景 URL 传昵称
方式一

Shopify 店铺官方对接

应用级授权，无需手动维护访问令牌 —— 系统自动换取并每 24 小时续期

四步 · 全程约 10 分钟
03

四步完成接入

令牌自动续期，零维护

① 创建应用：Shopify 开发者后台创建，确保与店铺同一组织；② 配置权限：勾选 read_orders / write_orders / read_fulfillments / read_price_rules；③ 复制凭据：客户端 ID + 密钥（shpss_ 开头）+ 店铺域名；④ 填写并测试：管理后台填入 → 测试连接 → 启用。

  • 应用级授权，无需手动令牌
  • 令牌 24h 自动续期
  • 商品卡片 + 昵称支持
  • 文档含可复制 Liquid 代码
边界如实标注 · 不夸大宣传
04

对接能力与边界（如实说明）

我们也会告诉你"做不到什么"

订单：状态/金额/明细/时间/收件人脱敏，支持电话尾号验证。物流：运单号 + 配送状态 —— Shopify 渠道不提供详细轨迹（API 边界，如实告知）。退款：金额由 Shopify 自动计算（含运费），发起后进入审批流。活动：支持 Price Rules 查询。边界在管理后台接入指引中均有标注。

  • 订单字段完整 + 尾号验证
  • 物流边界如实标注
  • 退款金额自动计算
  • 活动 Price Rules
方式二

自研商城OpenAPI 接入

为已运营的商城设计：不改业务逻辑、不加表不改字段，前端贴 3 行代码，后端新增 4 个以只读为主的接口，整体约 1 人日

HTML / Vue / React / 小程序 web-view
05

前端：3 行代码完成

不改商城任何现有代码

公共布局贴2 行配置 + 1 个 async 脚本完成挂件接入（iframe 隔离，零样式冲突）；登录后一行 setUser 会员昵称直显工作台；商品详情页一行 setProduct 开启商品卡片。支持 HTML / Vue / React / 小程序 web-view 全环境。

  • 挂件 iframe 隔离零冲突
  • setUser 会员昵称
  • setProduct 商品卡片
  • 全环境支持
统一信封 {code, msg, data}
06

后端：4 个以只读为主的接口

数据都是现成的，只是换个格式暴露

订单查询 / 物流查询 / 活动查询（只读）+ 退款发起（POST），响应统一信封格式（code/msg/data）。读取的都是商城现成的订单/物流表 —— 不改业务逻辑、不加表、不改字段。管理后台提供 Python / Node.js / PHP / Java / Go 五语言完整可运行示例，一键复制 —— 接口是标准 HTTP + JSON，语言不限，包括但不限于以上五种；WordPress（WooCommerce）、CRMEB 等主流商城系统均可按示例快速对接。

  • 4 个新增路由，3 读 1 写
  • 五语言示例一键复制
  • 不加表不改字段
  • 退款幂等约定
3 秒硬超时 · 不拖垮商城
07

安全机制：Token + HMAC 签名

防篡改、防重放、可熔断

每请求携带 Bearer Token（可随时更换）+ HMAC-SHA256 签名：对"方法+路径+时间戳+随机数+请求体哈希"整体签名，篡改即失败。签名带 ±5 分钟时间窗与 nonce 防重放。平台侧 3 秒硬超时（可配 1-10s）：商城变慢只让 AI 回复变慢，绝不拖垮商城；退款 POST 不自动重试，由商城幂等兜底。

  • HMAC 全参数签名
  • ±5min 时间窗 + nonce
  • 3s 超时可配
  • POST 不重试防重复退款
分步接入
第 1 步 10 分钟即见效
08

渐进式接入路线

先见效，再深入

第 1 步（10 分钟）：只挂挂件 —— 立刻拥有 AI + 人工客服，覆盖 90% 价值；第 2 步：订单/物流查询 —— AI 能回答"我的订单到哪了"；第 3 步（可选）：会员昵称、商品卡片、活动、退款。每步独立生效、随时可停，客服故障不影响商城运行。

  • 先挂件即见效
  • 按需逐步深入
  • 随时停用
  • 商城零影响
商城页面接入（完整版见管理后台 · 商城对接 · 可一键复制）
<script>
  window.KefuConfig = { tenantCode: '你的租户短码', serverUrl: 'https://www.clykf.com' };
</script>
<script src="https://www.clykf.com/visitor/kefu-sdk-loader.js" async></script>
<script>
  window.KefuWidget && window.KefuWidget.setUser({ name: '会员昵称' });
  window.KefuWidget && window.KefuWidget.setProduct({ title: '商品名', price: '99.90', image: '...', url: '...' });
</script>

✦ 管理后台「商城对接」提供 Python / Node.js / PHP / Java / Go 五语言后端示例（含 Token + HMAC-SHA256 签名校验完整实现），均可一键复制、按语言直接运行。

接入前

常见疑问，如实回答

我们相信"如实说明边界"比"夸大宣传"更能建立长期信任

只读为主 · 可审计可停用
09

会读到商城敏感数据吗？

安全边界如实说

读取范围仅限你勾选启用的工具（订单/物流/活动为只读查询；退款默认人工审批，AI 只提交申请、钱不经手）。全部请求带签名与租户标识，商城侧可审计可限流，后台一键停用，停用后商城零改动。

  • 只读为主
  • 退款人工审批
  • 可审计可限流
  • 一键停用零回滚
实测：商城宕机 0 秒级降级
10

API 会拖垮商城吗？

不会，且有实测

平台调用 3 秒硬超时（可配 1-10 秒）+ 仅 GET 自动重试 + AI 按需查询（访客问到才查，非轮询）。实测商城宕机场景：平台秒级失败并优雅降级，AI 回复"暂时查不到"而不是卡死。收货人信息脱敏显示（138****5678），且收货人 ≠ 登录会员 —— 会员昵称由登录态独立下发。

  • 3s 超时可配
  • GET 才重试
  • 按需查询非轮询
  • 收件人脱敏