黔前智算 Ai客服 签发密钥

Open API REST v1

给业务系统一套REST 调用面。

基址 /api/open/v1/。Bearer 鉴权，覆盖问答、知识库、工单、客户与售后。不要把管理后台 Cookie 或 /api/admin 开放给三方。CodeNeo 代码编排工具请用独立的 MCP 接入。

在浏览器试调用 去签发密钥 OpenAPI JSON

本页不展示、不生成生产密钥。粘贴试调用只发往本站接口，不写入浏览器存储。

01

接入三步

密钥在系统设置签发，站点要单独打开开放渠道。访客挂件和管理后台路径不变。Agent 接入见 MCP 接入。

STEP 01 打开渠道

运营后台「接入站点」勾选「开放 API / MCP」。默认关，未开时问答返回 channel_disabled。

STEP 02 签发应用

系统设置 → 开放应用。runtime 问答、ops 同步工单、agent 给 MCP。明文只显示一次。

STEP 03 带 Bearer 调用

服务端不要带 Origin。多站密钥每次传 site。写操作加 Idempotency-Key。

应用类型默认范围：

类型场景默认 scopes
runtime对方后端代访客问答chat live.write kb.read
opsERP / 电商同步crm.* work.* ticket.read
agentCodeNeo 代码编排工具 / 内部 Agent，见 MCP 接入chat kb.read ticket.read crm.read

02

鉴权

密钥格式 aics_<live|test>_<12位hex>.<secret>。也可用头 X-AICS-Token。

HTTP
Authorization: Bearer aics_live_REPLACE.REPLACE
Content-Type: application/json
Idempotency-Key: erp-order-20260907-001

成功响应统一带 request_id，对账排错带上它：

JSON
{
  "code": 200,
  "success": true,
  "message": "success",
  "request_id": "req_…",
  "data": {}
}

限流按密钥每分钟计数（默认 60），与挂件访客限流分开。响应不会包含渠道密钥、模型 Key、ticket_token 或内部备注。

03

REST 调用

基址 。把示例里的 YOUR_SITE 换成站点 ID。成功时外层仍是 code / success / request_id / data，下面每条给出完整响应。

方法路径scope做什么
GET/meta任意密钥站点、渠道开关、当前 scopes
POST/chatchat同步问答
GET/chat/sessions/{id}chat会话摘要
GET/kb/searchkb.readq top_k
GET / POST/kb/faqkb.read / kb.write列表 / 新增 FAQ
GET/ticketsticket.readstatus limit include=last_message
GET/tickets/{id}ticket.read公开消息，无内部备注
POST/ticketslive.write排队或留言 offline:true
POST/tickets/{id}/messageslive.write访客追问
POST/tickets/{id}/replyagent.reply机器人回复（访客可见）
POST/tickets/{id}/closeticket.write关单，可带 note
GET / POST/contactscrm.read / crm.write列表 / 按手机 upsert
GET / PATCH/contacts/{id}同上；完整手机要 crm.pii详情 / 改状态
POST/contacts/{id}/followscrm.writekind=phone|chat|note
GET / POST/workwork.read / work.write售后列表 / 新建
GET / POST/work/{id}同上详情 / 改 status
POST/work/{id}/followswork.write售后跟进
GET / POST/webhookshooks.write签名密钥只返回一次
GET/analytics/overviewanalytics.read排队计数
GET/logs/chatslogs.read对话日志分页
GET/openapi.json无需密钥路径清单

Webhook 投递头 X-AICS-Signature: sha256=<HMAC-SHA256(原始 body, secret)>，另有 X-AICS-Event。须 5 秒内 2xx。售后 status：open | pending | waiting | resolved | closed；客户 status：new | following | done。

04

试调用

粘贴你在「开放应用」复制过的密钥。本页不签发、不回显、不写入 localStorage。写操作会真实改数据，请用测试密钥。

站点须已打开开放 API 渠道，否则 chat / 建单为 403。密钥范围不够会 403 forbidden_scope。

结果会出现在这里。

05

错误码与边界

HTTPerror含义
400bad_request缺参数
401unauthorized缺密钥、格式错、已吊销
403forbidden_scope缺范围
403wrong_site密钥未绑定该站
403channel_disabled站点未开 api 渠道
403forbidden_ip不在 IP 白名单
404not_found不存在或跨站
429rate_limited该密钥每分钟超限
409conflictFAQ / 文档 ID 已存在

不开放：模型 Key、成员与 TOTP、渠道 AppSecret、短信/语音、原始数据库。A 站密钥读 B 站工单为 404/403。客户手机默认掩码。

签发密钥 打开渠道开关 下载路径清单 MCP 接入