KDIP 3.0 接入说明¶
KDIP接入注意事项¶
KDIP交互流程示意图
需要注意：为保证各个项目接入一致性&稳定性，接入时应遵从以下规范
- 游戏HTTP进程在收到KDIP指令时完成参数、签名合法校验并确认已发送给游戏服后，应返回成功给KDIP服务，游戏需要在和中台约定的时间内返回结果，否则会超时。
- 游戏接入KDIP时需和中台产品、技术约定KDIP的超时时间(默认 链接建立超时: 3秒 等待请求处理超时: 5秒 支持接口维度配置)，重试次数(默认不重试，超时场景下支持游戏维度重试次数配置)。
- 游戏服需要对KDIP的请求根据seqid进行幂等处理,同一seqid多次调用返回结果一致，且内部逻辑仅处理一次。
- 当游戏服进行幂等校验时，发现已处理，应返回成功给KDIP （code 0），而非游戏报错。
- 游戏服需要进行签名校验，验证请求合法性 ，KDIP3.0 签名校验
KDIP接口的成功/失败，仅代表游戏服是否收到请求
KDIP的处理结果可通过以下方式进行进一步的确认，而不在请求返回中反馈。
- 通过游戏服的程序日志报警， 执行失败的角色通过报警日志报警到KIM群，@项目组程序排查问题
- 通过服务器埋点日志上报， 中台提供工具或搭建看板查询结果
seqid流水号用途:
流水号用于标志KDIP操作的唯一性，所有增删改指令都需要对应一个唯一的流水号，用于追溯服务执行结果、以及增强接口的可靠性。
KDIP地址策略¶
| KDIP接口 | path标识 | 地址策略 |
|---|---|---|
| 服务器信息查询 | /kdip/query/server-player-count | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[区服管理2.0地址] |
| 服务器信息同步 | /kdip/sync/server-info | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[区服管理2.0地址] |
| 手机号白名单同步 | /kdip/sync/phone-allowlist | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[区服管理2.0地址] |
| 服务器列表维度白名单同步 | /kdip/sync/zone-dim-allowlist | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[区服管理2.0地址] |
| 查询角色列表 | /kdip/query/role-list | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 查询角色数据 | /kdip/query/role-info | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色封停 | /kdip/ctrl/role-ban-play | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色解封 | /kdip/ctrl/role-unban-play | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色功能禁用 | /kdip/ctrl/role-ban-func | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色功能解禁 | /kdip/ctrl/role-unban-func | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色物品冻结 | /kdip/ctrl/role-ban-item | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色物品解冻 | /kdip/ctrl/role-unban-item | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色物品修改 | /kdip/ctrl/role-item-change | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色属性修改 | /kdip/ctrl/role-data-change | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 角色踢线 | /kdip/ctrl/role-offline | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 服务器踢线 | /kdip/ctrl/server-offline | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[玩家管理2.0地址] |
| 自定义指令-GM 工具平台专用 | /kdip/oper/extend-cmd | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 自定义指令-GM OPEN-API B端场景 | /kdip/open/extend-cmd | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 自定义指令-GM OPEN-API C端场景 | /kdip/open-c/extend-cmd | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 邮件发送 | /kdip/oper/mail-send | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 邮件撤回 | /kdip/oper/mail-retract | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 跑马灯发送 | /kdip/oper/marquee-send | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 礼包发送 | /kdip/oper/gift-send | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 公会查询 | /kdip/query/guild-list | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 修改公会信息 | /kdip/oper/guild-change | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
| 公会解散 | /kdip/oper/guild-ban | 服务器配置[KDIP地址]，则服务器[KDIP地址]；服务器未配置，兜底服务器列表配置[运营管理2.0地址] |
公共参数说明¶
Request Header：
| 参数 | 格式 | 释义 |
|---|---|---|
| cid | string | 中台分配给服务调用方的唯一id，目前仅为预留，游戏接收后无需处理 |
| seqid | string | 流水号，注意：游戏server需要保证接口幂等，同一seqid多次调用返回结果一致，且游戏server内部逻辑仅处理一次，返回接口有此参数必须处理 |
| ts | long | 服务器当前时间戳（毫秒数），用于校验请求时间，检验规则见下方签名校验，必传 |
| version | string | KDIP服务的版本，不指定时默认为最新版本，目前仅为预留，游戏接收后无需处理 |
| access-token | string | 敏感服务的访问令牌，目前仅为预留，游戏接收后无需处理 |
| sign | string | 签名，计算规则见下方sign签名计算规则 |
| username | string | 任务指令发起者。没有用户信息时默认：unknown。GM-20250624版本新增 |
Response：
| 参数 | 格式 | 释义 |
|---|---|---|
| result | int | 0：指令执行完毕，不代表业务结果；非0，参见KDIP通用错误码 |
| msg | string | 错误信息 |
| data | json | 返回接口定义的数据 |
KDIP游戏错误码¶
| code | 描述 | 返回场景 |
|---|---|---|
| 0 | 请求接收成功并初步处理完成 | 游戏服接收到请求、校验通过、转发到GS(真正处理流量服务)成功(特殊：收到重试的幂等请求 CODE：0) |
| 120000 | 签名错误 请求拒绝 | 请求未携带签名 或 游戏服生成签名与请求携带签名不一致 |
| 120001 | 请求参数错误(msg中必须说明具体参数字段) | 请求body中必须参数未传值 如: cmd_param参数值为空 |
| 120002 | 游戏服系统内部错误 | 游戏服系统内部抛异常导致请求处理中断 |
| 120010-120020 | 预留给游戏服code码 | 游戏侧可自定义该code含义和场景，使用code时必须返回对应详细msg说明 |
KDIP内置错误码¶
| code | 描述 | 返回场景 |
|---|---|---|
| 120005 | KDIP服务器请求游戏服建立链接超时 | 网络原因 或 游戏服拒绝请求链接建立 |
| 120006 | KDIP服务器等待游戏服处理结果超时 | 网络原因未及时返回结果 或 游戏服处理耗时过长 |
| 120007 | 游戏服接口结果未按KDIP协议规定返回 | 游戏服接口结果未按KDIP协议规定返回 |
| 120008 | KDIP服务器请求游戏服HTTP状态码异常 | 如404 502等 |