AIVA 小程序对接 / SERES-APIS赛力斯提供的接口
四个接口与网关签名的原文整理;作品数据推送逐个参数与 AgentOS 对齐,并列出待确认问题。
整理日期:2026-10-13。原文在仓库 docs/api/AIVA/:《aiva-services-api.txt》(4 个接口)与《参数验签方案.docx》(网关签名)。本文先照录赛力斯原文的参数,再写 AgentOS 实际怎么填、怎么用;作品数据推送逐个参数标出与 AgentOS 作品数据是否对齐,拿不准的列在文末“待与赛力斯确认”。
“AgentOS 怎么填”一栏以当前代码为准(project/agentos/src/core/card/print.js、src/core/aiva/gateway.js、src/core/aiva/push.js),不是赛力斯的要求。
一、四个接口与联调现状
方向都是 AgentOS 调用赛力斯,经同一个网关、用同一套 accessKey/secretKey 签名。
10-13 上午这三个接口都被赛力斯服务拦在“令牌”这一步;下午复测,两个推送接口已放行,只剩二维码扫码识别仍返回“令牌不能为空”,需要赛力斯放行,或说明令牌怎么取、放在哪个请求头。
二、通用:网关地址与签名
网关地址:测试环境 https://sds-op-gw-test.seres.cn/api,接口完整地址 = 网关地址 + 接口路径,例如 https://sds-op-gw-test.seres.cn/api/uc/v1/identity/suncodes。在后台“用户与来宾卡 → 身份服务设置 → 太阳码接口”登记(登记的是太阳码完整地址,其他三个接口按同一网关推算)。
各环境网关地址(2026-10-16 赛力斯提供 UAT、生产地址;“赛力斯给的地址”末尾的 /uc 是接口路径的开头,所以网关地址到 /openapi 为止):
- UAT 和生产两个域名都先经过阿里云 WAF(
yundunwaf4/5.com),再到火山云 ALB,和 AgentOS 的域名一样。
- 签名用的路径是完整请求路径,包含网关前缀(测试为
/api/uc/…,UAT/生产为 /openapi/uc/…),与现在测试环境的做法一致。如果新环境报签名错误,需要赛力斯确认参与签名的路径是否包含 /openapi。
- 待赛力斯提供或确认:UAT、生产各自的 accessKey/secretKey、sysCode、sourceApp/scanSourceApp 是否与测试环境相同。凭证只在后台录入,不写进文档。
请求头(《参数验签方案》1.5.1)
签名规则:sign = SHA-256(请求路径 & 请求体原文 & 按字母排序的 URL 参数与 timestamp & secretKey),UTF-8,十六进制小写。四个接口都没有 URL 参数,所以实际是 请求路径 & 请求体 & timestamp=… & secretKey。
- 请求路径要带网关前缀
/api:实测只有用 /api/uc/v1/identity/suncodes 计算的签名能通过,去掉 /api 的都报“签名校验失败”。
- 已用验签方案流程图里的样例核对,算法一致。
三、M01 太阳码生成
原文参数
返回:{status, errorCode, errorMsg, data, time, traceId},data 为太阳码图片地址(TOS),AgentOS 再下载该图片。
实测补充:path 为空会报“太阳码跳转路径为空!”;赛力斯不检查路径是否存在,填错也能生成,只是扫码会进错页面。一次生成约 1.4—1.6 秒、下载 0.3—0.5 秒,后台单次超时已登记为 5000 毫秒。
四、二维码扫码识别
2026-10-15 变更:接口地址改为 /uc/v1/user/identityCode/scan/oneid(AgentOS 不再调用 /scan)。请求参数不变;返回的 data 只有 oneId,不再有昵称、手机号、头像。用户确认扫码不再更新这三项,此前已保存的保留。下面“原文参数”仍适用,返回字段以本段为准。
原文参数
赛力斯说明:门店应用扫码后通过 Token 映射用户,返回脱敏用户信息,Token 一次性使用。
返回的 data 与 AgentOS 用途
五、绑定结果推送
原文参数与 AgentOS 填法
推送时机:会员第一次在点位扫会员码、AgentOS 新建账户并关联 ONEID 后推一次。会员扫卡背面太阳码绑卡(赛力斯调 AgentOS 的 B03)不推(用户 10-13 确认 Q4)。
六、作品数据推送(参数对齐)
赛力斯说明:活动结束推送活动记录与作品;eventId 防重复,重复推送直接跳过。
AgentOS 的做法(用户 10-13 确认):作品保存并审核通过后,每个作品单独推一次(works 里固定 1 个作品);只推已关联 ONEID 的账户的作品,只用来宾卡还没绑定的,等绑卡成功后补推;只推功能上线后生成的作品。推送范围:AIVA面基助手形象图、AI音乐歌曲(带封面地址与歌词)、AI图片生成最终旅程图、AI车衣共创最终成片图(2026-10-15 起 AI 共创与 DIY 都推纸膜打印图,不推生成过程中的花纹图与 UV 贴图)。
逐个参数对齐(“对齐”:✅ 双方理解一致;⚠️ 拿不准,见第七节对应编号)
七、已确认与仍待确认
用户 2026-10-13 确认(按 AgentOS 规则,已按此实现)
- 门店编号:用 AgentOS 的门店编号。
- 活动名称:用点位详情里填写的点位名称(没填时为空)。
- 时间:按北京时间,ISO 格式带
+08:00。
- ONEID 为空:按 AgentOS 规则——没有 ONEID 先不推,用户绑定后由 AgentOS 补推。
- 作品宽高、时长、文件大小:推送接口没有对应字段,不推送。
- 推送编号 eventId:是单次推送任务的编号,按“推送时间 + 随机码”生成(北京时间 yyyyMMddHHmmssSSS + 16 位随机十六进制,共 33 位);一条推送记录一个编号,失败重推沿用同一编号,赛力斯据此不重复处理。与赛力斯原文“UUID+时间戳”格式不同,以本条为准。
10-13 14:26 已成功推送的那 1 条(作品
asset_c4c6cd9e…)是按旧格式(UTC 时间、旧编号)发出的,赛力斯已接收,不再重发。
仍待确认
- agentosId 用哪个账户:一个 ONEID 可以有多个 AgentOS 账户(每张卡一个),AgentOS 填作品实际所属的账户。赛力斯要的是这个,还是 ONEID 的主账户?
- 图片作品要不要缩略图:coverUrl 只给 AI音乐填封面,图片作品为空。
- 二维码扫码识别的令牌:10-13 15:00 复测仍返回
E68_10001 令牌不能为空(两个推送接口已放行),请赛力斯放行或告知令牌获取方式。