快速接入

状态

本文说明当前代码实现的接入规则，不代表各环境已发布或可用。实际接入前请确认目标环境的发布状态与配置；文档站可访问不等于 API / MCP 服务已就绪。

选择接入方式

你是	用什么	去哪
当前租户超级管理员，想在 AI 客户端里用 Risemap	确认有效 MCP 权益后 OAuth 授权	MCP 客户端接入
集成商，服务器程序调用开放接口	AppKey	本页往下

MCP 要求租户启用、主套餐 ACTIVE 和同租户有效 MCP 订阅权益（主套餐明确包含，或另行购买）；客户端需兼容完整 OAuth 流程。以下 AppKey 示例仅用于 REST，不作为 MCP 接入配置。

AppKey 接入四步

1. 创建 AppKey

由租户超级管理员在 Risemap 控制台创建：填写用途名称、勾选授权范围（{业务域}:{read|write} 词汇，与 OAuth 同一套）。AppKey 绑定创建人身份，调用时的数据可见性不超过该员工本人——长期集成可用符合超级管理员资格的专用账号，但身份或租户状态变化后仍会重新校验，并非永久有效。

2. 保存 Secret

Secret 明文仅创建时显示一次，平台只存哈希、不可再查。丢失即吊销重建。

3. 调用统一直通入口

开放接口按**接口编码（apiCode）**调用，不做路径镜像。凭证经请求头传递：

curl -X POST https://open.risemap.cn/v1/api/invoke \
  -H "X-App-Key: oak_xxx" \
  -H "X-App-Secret: oas_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "apiCode": "sales.order.page",
    "query": { "pageNum": 1, "pageSize": 10 }
  }'

以上为 Bash / 类 Unix shell 示例。请先替换为已确认可用的环境域名和自己的凭证，不要把真实 Secret 写进文档或提交到代码库。 sales.order.page 是 GET 查询接口，分页参数放在 query 是正确的；外层 /v1/api/invoke 使用 POST，不代表所有目标接口都接收 body。

请求体字段：

字段	必填	说明
apiCode	是	接口编码，见开放接口清单与接口参考
query	否	查询参数（键值对，拼到目标地址 query string）
body	否	POST 接口的 JSON 请求体

响应为统一格式：code=200 时 data 即下游业务数据。

4. 处理错误

场景	表现
凭证缺失/错误/已吊销	HTTP 401 + {"error":"invalid_token",...}
接口未登记或已停用	code=92201
超出凭证授权范围	code=92202
上游服务调用失败	code=92203；读操作可退避重试，写操作须先查询处理结果，禁止盲目重试

完整清单见错误码，频率限制见限流与配额。

连通性探测

不需要凭证，仅用于确认健康探测路由可达；不能证明凭证有效、MCP 权益有效或业务接口可调用。将域名换为要接入的环境：

curl https://open-dev.risemap.cn/v1/health/ping