开发者中心

1. 认证方式

方式一：开放平台应用凭证（第三方系统对接，推荐）

后台「系统 → 开放平台」创建应用，获取 X-App-Id 与 X-App-Secret（密钥仅创建/重置时显示一次），调用 /api/openapi/* 开放接口，无需用户登录态：

X-App-Id: ap_xxxxxxxxxxxxxxxx
X-App-Secret: tks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

按应用独立限流：QPS（默认 10/秒）+ 日配额（默认 10000/日），后台可调。凭证错误返回 401、应用/企业停用 403、超限 429。

方式二：JWT 登录态（后台管理接口）

管理员/坐席登录后调用管理接口，Token 有效期 12 小时：

Authorization: Bearer <access_token>

POST /api/login
{"username": "admin", "password": "******"}

角色：superadmin（平台）、admin（租户管理）、agent（坐席）。所有接口 HTTPS 传输、JSON 响应、多租户数据隔离。

2. 智能问答接口

{
  "source": "app",            // 渠道标识：web/wechat/wecom/douyin/app...
  "user_id": "u_10001",       // 可选，业务侧用户ID
  "bot_id": 3,                // 可选，指定机器人
  "client_id": "c_m7x2k9ab",  // 可选，访客端持久化标识（localStorage），刷新后恢复同一会话
  "session_id": "a1b2c3d4e5f60708"  // 可选，上次会话 ID，命中且归属匹配则复用并恢复历史
}

// 发送
{"type": "message", "content": "你们发货用什么快递？"}
{"type": "transfer"}                      // 转人工
{"type": "rate", "star": 5, "note": "满意"}

// 接收
{"type": "message", "sender": "ai", "content": "我们默认使用顺丰发货"}
{"type": "transfer_result", "status": "waiting"}
{"type": "agent_joined", "agent": "客服小美"}

3. 知识库接口

{
  "question": "多久发货？\n几天能发出来？",
  "answer": "现货 24-48 小时内发货。",
  "category": "物流",
  "active": true
}

4. 运营数据接口

5. 工单接口

6. 订单系统对接

客户报「订单号 / 手机号」，客服与 AI 一键查询订单状态 / 物流 / 退款进度，统一订单模型屏蔽平台差异。platform 支持：mock（演示）/ taobao / jd / pdd / douyin。

POST /api/orders/mock/query
Authorization: Bearer <token>
{"order_no": "TK202608260001"}

{"event": "order_status", "order_no": "TK202608260001", "payload": {}}

真实平台接入：在平台开放门户（open.taobao.com / open.jd.com / open.pinduoduo.com / openapi-fxg.jinritemai.com）创建应用并完成商家授权，将凭证配置到系统环境变量（TAOBAO_* / JD_* / PDD_* / DOUYIN_*）后自动切换真实数据；未配置密钥时使用 mock 演示数据。生产环境务必服务端保存密钥、启用 HTTPS、接口加 IP 白名单。

7. 开放平台应用接口

以 X-App-Id / X-App-Secret 调用（无需登录态，按应用限流）：

curl -X POST /api/openapi/orders/query \
  -H "X-App-Id: ap_xxxxxxxx" \
  -H "X-App-Secret: tks_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"order_no": "O202608260001", "platform": "taobao"}'

8. 流程运行与人工审批

{"decision": "approve", "note": "同意放行"}

9. 操作审计日志

系统对后台写操作（POST/PUT/DELETE/PATCH）自动留痕：操作者、角色、模块、动作、路径、来源 IP。日志仅追加、不可删除，不记录请求 Body（避免误存敏感信息），满足 GB/T 47746-2026 合规审计要求。

10. Webhook 事件订阅

在后台配置回调 URL 并订阅事件（POST /api/webhooks 创建，POST /api/webhooks/{id}/test 测试推送，GET /api/webhooks/logs 查看投递日志），系统实时推送（带签名验证）：

回调签名验证：请求头 X-TianKey-Signature = HMAC-SHA256(Webhook Secret, 原始 Body)，请验签后处理，防止伪造。

11. 快速开始示例

Python 示例：开放平台凭证查询订单

import requests

API = "https://<你的域名>/api"

resp = requests.post(f"{API}/openapi/orders/query",
    headers={"X-App-Id": "ap_xxx", "X-App-Secret": "tks_xxx"},
    json={"order_no": "TK202608260001", "platform": "mock"})

print(resp.json()["count"])   # 命中订单数
print(resp.json()["items"])   # 订单列表

JavaScript 示例：Webhook 验签

const crypto = require("crypto");
// 收到回调后验签
const sig = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
if (req.headers["x-tiankey-signature"] !== sig) return res.status(401).end();
// 处理事件…

12. 网页嵌入接入（widget.js / iframe）

除后端 API 外，网页端提供两种接入形态：悬浮窗组件（右下角悬浮球 + 弹窗，移动端自动全屏）与 iframe 内嵌（把整页聊天窗口嵌入页面任意区域）。代码可在后台一键生成：「渠道管理 → Web 渠道 → 嵌入代码」（可带来源渠道标识）或「系统设置 → 客服窗口设置 → 复制嵌入代码」。

方式一：悬浮窗组件（推荐）

粘贴到网站 <body> 末尾（域名与租户 ID 由后台自动生成）：

<script src="https://<你的域名>/widget.js"></script>
<script>
  window.TKC_CONFIG = {
    chatUrl: "https://<你的域名>/chat?company=1",
    companyId: 1,   // 租户 ID，缺省按 chatUrl 上的 company 参数
    // 可选覆盖项（不填则跟随后台「系统设置 - 客服窗口设置」）；下方各项已带逗号，取消注释即生效：
    // accentColor: "#2563eb",          // 悬浮按钮主题色
    // bgColor:     "#ffffff",          // 窗口背景色，"transparent" 透出页面底色
    // position:    "bottom-right",     // bottom-right | bottom-left | top-right | top-left
    // offsetX: 24, offsetY: 24,        // 距边缘的水平 / 垂直边距 px（0-200）
    // logo: "🤖",                       // 悬浮图标：emoji/文字 或 图片 URL
    // bubbleText: "在线客服",           // 悬浮图标悬停提示文案
    // autoOpen: 0                      // 自动弹窗延迟毫秒，0 = 不自动打开
  };
</script>

配置优先级：代码中的显式配置 > 后台「客服窗口设置」下发的配置。因此若希望主题色、图标、位置完全由后台控制，请保持这些项处于注释状态；一旦写上具体值，后台改动将不再生效。

方式二：iframe 内嵌

<iframe
  src="https://<你的域名>/chat?source=官网&company=1&embed=1&transparent=1"
  title="在线客服"
  allow="microphone; camera; autoplay; fullscreen"
  allowtransparency="true"
  style="width:100%;height:600px;min-height:320px;border:0;"></iframe>

allow 中的 microphone; camera 不可省略：跨源 iframe 默认没有媒体权限，缺失会导致窗口内语音发送与拍照上传失败。embed=1 让聊天卡片铺满 iframe（去掉留白与圆角），transparent=1 使卡片四周透出宿主页面底色；高度可按布局调整（建议不低于 320px，容器宽度不小于 360px）。

/chat 页面 URL 参数

以下参数拼在 chatUrl 或 iframe 的 src 之后（首个参数用 ?，后续用 &），中文与 # 需 URL 编码（# 写作 %23）：

接入排错

• 会话归属到别的租户（多租户必看）：确认 companyId 或 chatUrl 上的 company 参数已正确填写，二者都没有时会落到默认租户。
• 嵌入页内语音 / 拍照不可用：iframe 缺少 allow="microphone; camera"。悬浮窗方式由 widget.js 自行处理，无需配置。
• 后台改了主题色但不生效：检查代码里是否写了 accentColor，显式配置会覆盖后台设置，删除该行即可恢复由后台控制。
• 悬浮球被页面元素遮挡：组件默认层级较高，若仍被遮挡，请检查宿主页面是否存在更高 z-index 的元素或 overflow: hidden 容器；也可调 position 与 offsetX/offsetY 避让。