ONEID 会员对外接口文档 / 开始对接
文档说明
本文档单独列出 与 AIVA 官方 ONEID 会员相关、需要外部系统对接的接口,主要对象是 AIVA 小程序服务端。门店点位客户端(互动网页、播控)请看《互动应用开发接入文档》,不调用本文接口,也不得持有本文凭证。
业务流程见文档中心《用户身份流程》与《身份绑定通信泳道》:http://aiva.docs.vavedigital.com/identity/index.html#identity
ONEID 会员对外接口文档 / 开始对接
接口一览
ONEID 会员对外接口文档 / 开始对接
鉴权与凭证
- 身份服务凭证不能读用户数据,只读数据凭证不能写身份,点位设备凭证也不能调用本文接口;用错凭证一律返回 401。
- 租户由凭证决定,门店由卡决定;请求里不能指定租户或门店。
- 凭证只在服务端保存,不要放进小程序前端、日志或二维码。
ONEID 会员对外接口文档 / 开始对接
调用流程
扫卡绑定
- 会员用微信扫门店卡背面太阳码,进入 AIVA 小程序,小程序拿到
bindScene。
- 会员在小程序注册或登录,AIVA 得到 ONEID。
- AIVA 服务端调用 B02,用
bindScene 换取本卡 AgentOSID。
- AIVA 服务端生成一个请求号,调用 B03 绑定。
- 如果 B03 超时或回复没收到:不要换请求号,先调用 B04 查原请求结果;查不到就用同一个请求号再发一次 B03。
- 需要展示会员名下的卡或数据时,调用 B05、B06。
会员到店点位登录(2026-10-13 起)
扫码器兼容设置(2026-10-14):AgentOS“用户与来宾卡 → 身份服务设置 → 扫码器设置”可配置来宾卡大小写兼容、连续同码合并与无回车静默识别;互动客户端读取GET /api/identity/scan-settings。仅对来宾卡按当前格式规范化,不转换会员token大小写,不改变32位会员码协议或一次性使用规则。
- 会员在 AIVA 小程序打开“会员码”,小程序显示 AIVA 会员码(AgentOS 不参与生成)。会员码内容为 32 位小写十六进制的临时 token(2026-10-13 AIVA 确认),AgentOS 据此与来宾卡码区分。
- 点位扫码后,由点位客户端调用
POST /api/identity/point-login(见《互动应用开发接入文档》),把二维码内容原样传给 AgentOS。AgentOS 按码的格式识别(2026-10-13):…/c/14位短码 链接或 14 位短码 = 来宾卡;32 位小写十六进制 = AIVA 会员码;两种都不是的直接返回 400 CODE_INVALID、不调用 AIVA。
- AgentOS 调用 AIVA 的 二维码扫码识别,用二维码内容换出 ONEID(会员码只能用一次)。
- 该 ONEID 已有账户的,登录到会员主账户;首次来访的,AgentOS 自动建账户并关联 ONEID,再调用 绑定结果推送 告诉 AIVA。
原“AIVA 服务端申请一次性会员凭据 memberTicket、放进会员码”的方式已于 2026-10-13 删除。
作品同步到 AIVA
- 会员在点位生成作品,作品审核通过后,AgentOS 调用 作品数据推送,每个作品推一次(账户须已关联 ONEID;只用来宾卡的用户在绑卡后补推)。
- 会员在小程序删除作品时,AIVA 调用 会员作品删除;ONEID 后台运营删除时调用 批量删除作品。
ONEID 会员对外接口文档 / 身份绑定(AIVA → AgentOS)
B02 解析绑定参数
会员扫卡背面太阳码进入小程序后,AIVA 服务端先用扫码参数查出这张卡对应的 AgentOSID,再去绑定。
功能描述
用卡背面太阳码携带的 bindScene 查出本卡的 AgentOSID、印刷卡号与卡状态。只查询,不写任何数据。卡已作废或参数不存在时返回 404。
请求示例
curl -X POST "$BASE/openapi/v1/identity/card-binding-context" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"bindScene":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx"}'
返回示例HTTP 200
{ "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f", "cardNo": "CQ0001023", "status": "activated" }
ONEID 会员对外接口文档 / 身份绑定(AIVA → AgentOS)
B03 绑定 AgentOSID 与 ONEID
会员在小程序完成注册或登录后,AIVA 服务端把这张卡绑定到会员的 ONEID。一个会员可以绑定多张卡。
功能描述
把本卡 AgentOSID 绑定到已认证会员的 ONEID。每次绑定都是追加:同一个 ONEID 可以绑定多张卡,原来的卡和历史记录保留。绑定成功后,会员的 Token 在同一次操作中归集到该 ONEID 下最早创建的账户(主账户),并留下转出、转入两条流水;注册赠送每个账户只发一次。
同一个请求号原样再发一次,不会重复绑定,直接返回第一次的结果(响应带 idempotentHit: true);同一个请求号改了内容再发,返回 409。调用超时时不要换请求号,先用 B04 查结果。
请求示例
curl -X POST "$BASE/openapi/v1/identity/bindings" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"AgentOSID":"au_3f9c0d1e2a4b5c6d7e8f","ONEID":"oneid_example","bindScene":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx","requestId":"aiva-20261008-0001"}'
返回示例HTTP 200
{
"status": "success",
"AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
"ONEID": "oneid_example",
"primaryAgentOSID": "au_1a2b3c4d5e6f7a8b9c0d",
"linkId": "link_7c2e…"
}
ONEID 会员对外接口文档 / 身份绑定(AIVA → AgentOS)
B04 查询原绑定请求结果
B03 超时或回复丢失时,用原请求号查询当时的绑定结果,避免重复绑定。
功能描述
返回该请求号保存的 B03 结果,内容与 B03 返回相同。只能查到本凭证自己提交过的请求。请求没有完成、或因参数错误整体失败时不保存结果,返回 404,此时可以用同一个请求号重新提交 B03。
请求示例
curl "$BASE/openapi/v1/identity/binding-requests/aiva-20261008-0001" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
返回示例HTTP 200
{ "status": "success", "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f", "ONEID": "oneid_example", "primaryAgentOSID": "au_1a2b3c4d5e6f7a8b9c0d", "linkId": "link_7c2e…" }
ONEID 会员对外接口文档 / 身份绑定(AIVA → AgentOS)
B05 查询 ONEID 绑定的全部卡
查询一个会员名下已绑定的全部卡与账户,用于小程序展示“我的门店卡”。
功能描述
分页列出该 ONEID 在本租户关联的全部 AgentOSID,包括卡号、卡状态、来源门店、绑定时间和主账户。按记录编号从小到大排序。
请求示例
curl "$BASE/openapi/v1/identity/oneids/oneid_example/bindings?limit=100" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
返回示例HTTP 200
{
"items": [
{ "id": "841", "AgentOSID": "au_1a2b…", "origin": "card_preset", "origin_store_id": "CQ-GUANGHUAN", "created_at": "2026-10-01T02:00:00.000Z", "linked_at": "2026-10-06T08:00:00.000Z", "card_no": "CQ0000512", "card_status": "linked", "primaryAgentOSID": "au_1a2b…" }
],
"hasMore": false,
"nextAfter": null
}
ONEID 会员对外接口文档 / 身份绑定(AIVA → AgentOS)
B06 按 ONEID 汇总数据
按会员汇总读取他在各门店、各张卡上的数据。使用与身份服务不同的“只读用户数据应用凭证”。
功能描述
按数据类别分页汇总该 ONEID 下全部关联账户的数据,每条记录保留它原来属于哪个账户(agentos_uid)和哪个门店(store_id)。只读,不改任何数据;可读的类别由后台给该应用授权的范围决定。
请求示例
curl "$BASE/openapi/v1/identity/oneids/oneid_example/data/tags?limit=50" \
-H "Authorization: Bearer $USER_DATA_APP_CREDENTIAL"
返回示例HTTP 200
{
"schemaVersion": 1,
"items": [ { "id": "1024", "agentos_uid": "au_3f9c…", "tag_key": "style_tech", "store_id": "CQ-GUANGHUAN", "point_id": "P02", "created_at": "2026-10-06T08:00:00.000Z" } ],
"hasMore": false,
"nextCursor": null,
"consistency": "live-keyset-bounded",
"asOf": "2026-10-08T02:00:00.000Z",
"complete": true
}
ONEID 会员对外接口文档 / 会员作品(AIVA → AgentOS)
会员作品删除
会员在 AIVA 小程序删除自己的作品后,AIVA 服务端调用本接口,让 AgentOS 同步删除。删除后作品文件立即从存储中删除,作品在小程序、点位、后台作品列表和展示上墙中都不再可见;AgentOS 只保留一条不含作品内容的“已删除”记录,用于 Token 计费对账和审计。
功能描述
删除一个属于该会员的作品(2026-10-09 用户确认):
- 删除范围:作品文件本身(图片、音乐音频)立即从存储删除;AI音乐的作品会连同它的封面一起删除。互动作答、画像标签、AI车衣共创的设计数据不删除。
- 归属核对:作品必须属于该 ONEID 关联的任一账户(任一张已绑定的卡,或会员首次到店自动建的账户)。不属于该会员或不存在的作品,一律返回 404,不透露作品是否存在。
- 审核中、展示中的作品:照样删除,并同时撤下上墙展示。
- 保留的记录:作品编号、归属账户、生成任务、删除时间、删除来源(哪个 AIVA 应用)和删除原因;不保留文件,也没有外链。
- 重复删除:已经删除的作品再次删除,返回
already_deleted,不报错。
- 删除失败:存储里的文件没删掉时整次报错,记录不改,可以用相同参数直接重试。
作品编号 assetId 来自 B06 按 ONEID 汇总数据(数据类别 assets)返回的 asset_id。作品名称见同一数据中的 work_name({点位名称}_{生成完成时间 yyyyMMddHHmmss 北京时间})。
请求示例
curl -X DELETE "$BASE/openapi/v1/identity/oneids/oneid_example/works/ast_8d1f0c2b" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
-H "Content-Type: application/json" \
--data '{"reason":"用户在小程序删除"}'
返回示例HTTP 200
{
"status": "deleted",
"assetId": "ast_8d1f0c2b",
"deletedAssetIds": ["ast_8d1f0c2b", "ast_cover_51a9"],
"deletedAt": "2026-10-09T02:00:00.000Z"
}
ONEID 会员对外接口文档 / 会员作品(AIVA → AgentOS)
ONEID 后台批量删除作品
供 AIVA ONEID 后台系统调用:运营在 ONEID 后台删除某个会员(或某张卡账户)的一个或多个作品时,同步删除 AgentOS 中的作品。删除效果与会员作品删除相同:作品文件立即从存储删除,只保留不含内容的“已删除”记录。
功能描述
按 ONEID 或 AgentOSID 删除一个或多个作品(2026-10-12 用户确认):
- 凭证:沿用 AIVA 身份服务凭证(与 B02—B05、会员作品删除相同),不需要另配。
- 作品归属:
ONEID 与 AgentOSID 必须且只能传一个。传 ONEID 时,作品须属于该 ONEID 关联的任一账户;传 AgentOSID 时,只认这一个账户的作品——即使这张卡已绑定 ONEID,同一 ONEID 下其他账户的作品也不能用这个 AgentOSID 删除(要删请传 ONEID)。
- 数量:
assetIds 1—100 个,超过直接返回 400;重复的编号只处理一次。
- 逐个处理、逐个返回:每个作品独立删除,一个删不了不影响其他作品。每个作品的结果为:
deleted 本次已删除;already_deleted 之前已删除;not_found 不存在或不属于指定的 ONEID/AgentOSID(不透露作品是否存在);failed 存储文件删除失败或存储位置与当前配置不一致,该作品记录未改动,可原样重试。
- 删除范围:与会员作品删除相同——AI音乐连同封面一起删除;互动作答、画像标签、AI车衣共创设计数据不删;审核中、展示中的作品照样删除并撤下展示。
- 删除来源:记录为 ONEID 后台(
aiva_admin:<应用编号>),与小程序删除区分,用于审计与对账。
- 整体出错:参数错误整次返回 400、不删任何作品。处理中途遇到服务端异常(5xx)时,已处理的作品保持已删除;用相同参数重试即可,已删除的作品会返回
already_deleted。
作品编号来自 B06 按 ONEID 汇总数据(数据类别 assets)返回的 asset_id。
请求示例
curl -X POST "$BASE/openapi/v1/identity/works/batch-delete" -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" -H "Content-Type: application/json" --data '{"ONEID":"oneid_example","assetIds":["ast_8d1f0c2b","ast_51a9e7d0","ast_0000dead"],"reason":"ONEID后台运营删除"}'
返回示例HTTP 200
{
"owner": { "type": "ONEID", "id": "oneid_example" },
"summary": { "deleted": 1, "already_deleted": 1, "not_found": 1, "failed": 0 },
"results": [
{ "status": "deleted", "assetId": "ast_8d1f0c2b", "deletedAssetIds": ["ast_8d1f0c2b", "ast_cover_51a9"], "deletedAt": "2026-10-12T02:00:00.000Z" },
{ "status": "already_deleted", "assetId": "ast_51a9e7d0", "deletedAssetIds": [], "deletedAt": "2026-10-09T02:00:00.000Z" },
{ "status": "not_found", "assetId": "ast_0000dead", "deletedAssetIds": [], "error": "作品不存在或不属于该会员" }
]
}
只要参数正确,HTTP 都是 200,请逐个看 results[].status;failed 的作品稍后用相同参数重试。
ONEID 会员对外接口文档 / 会员作品(AIVA → AgentOS)
作品小程序码查询
AI车衣共创互动最终结果页显示作品小程序码(2026-10-09 用户确认:扫码在小程序查看/下载本次作品;2026-10-11 改为按作品生成,与打印无关,不再有作品号码)。**AIVA 后端接口尚未就绪,本节为 AgentOS 拟定方案,收到 AIVA 接口文档后按其契约调整。**小程序码由 AgentOS 调用 M01(请求带 type:"work")生成,scene 为 AgentOS 分配的作品码参数;会员扫码进入小程序后,AIVA 服务端凭 scene 与当前会员 ONEID 调用本接口取作品编号,再按 B06 或既有作品读取方式展示。
功能描述
用小程序码参数查询对应作品。作品必须属于该 ONEID 关联的任一账户;不属于该会员、参数不存在或作品已删除,一律返回 404,不透露作品是否存在。
请求示例
curl "$BASE/openapi/v1/identity/oneids/oneid_example/work-codes/w3f9a0c1d2e3f405162738495a6b7c8d" \
-H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
返回示例HTTP 200
{ "assetId": "asset_1c9e…", "workNo": null, "workName": "车衣共创_20261009103015", "storeId": "CQ-GUANGHUAN", "mimeType": "image/png", "createdAt": "2026-10-09T02:30:10.000Z" }
ONEID 会员对外接口文档 / AgentOS → AIVA
M01 小程序太阳码生成(AgentOS 调用 AIVA)
方向与其他接口相反:由 AIVA 提供、AgentOS 调用。AgentOS 后台导出来宾卡打印图时逐张卡取背面太阳码,AI车衣共创结果页取作品小程序码。2026-10-12 起按 AIVA 提供的《aiva-services-api》M01 与《参数验签方案》对接(原文在仓库 docs/api/AIVA/)。
AIVA 网关统一登记(2026-10-13 起):AgentOS 调用 AIVA 的四个接口——M01、二维码扫码识别、绑定结果推送、作品数据推送——走同一个 AIVA 网关、同一套签名,在后台“用户与来宾卡 → 身份服务设置 → AIVA 网关”一处登记(原页签名“太阳码接口(M01)”):M01 完整接口地址(网关地址由它去掉末尾 /uc/v1/identity/suncodes 得到,其余接口按 AIVA 文档路径拼在网关地址后)、accessKey / secretKey、sysCode、单次超时、来宾卡与作品码页面路径,以及扫码识别用的 sourceApp、scanSourceApp。
功能描述
AIVA 按 path(小程序页面路径)与 param(scene)生成小程序码,上传 TOS 后返回图片地址;AgentOS 再下载该图片。来宾卡:param 为该卡的 bindScene(32 字符),扫码进入 AIVA 小程序激活页,用于后续 B02、B03 绑定。AI车衣共创作品码:param 为作品码 scene(w + 30 位十六进制),页面路径另行登记(AIVA 尚未提供,未登记时作品码直接报错)。
请求头(网关验签)
签名:sign = SHA-256(请求路径 + "&" + 请求体原文 + "×tamp=" + timestamp + "&" + secretKey),UTF-8,十六进制小写。请求路径取登记接口地址的路径部分;本接口没有 URL 查询参数,参与排序的只有 timestamp。已用《参数验签方案》流程图中的样例核对算法一致。
请求示例
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/suncodes" \
-H "Content-Type: application/json" \
-H "timestamp: 1791799000000" \
-H "accessKey: $AIVA_ACCESS_KEY" \
-H "sysCode: SD" \
-H "sign: <按上述规则计算>" \
--data '{"path":"pages/card/activate","param":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx"}'
返回示例HTTP 200
{ "status": true, "errorCode": "", "errorMsg": "", "data": "https://<TOS 域名>/…/suncode.png", "time": 1791799000123, "traceId": "…" }
data 为太阳码图片地址,AgentOS 随后 GET 下载,须为 PNG 或 JPEG(≤10MB)。
错误情况
以上情况都不生成占位码、不自动重试;运营处理后重新导出即可。仅导出正面(不调用 M01)不受影响。
ONEID 会员对外接口文档 / AgentOS → AIVA
二维码扫码识别(AgentOS 调用 AIVA)
方向与 B02—B06 相反:由 AIVA 提供、AgentOS 调用。会员在门店互动点位或作品打印台出示 AIVA 小程序会员码时,AgentOS 用二维码内容向 AIVA 换出会员 ONEID。2026-10-13 起提供,取代原 AgentOS 自己签发的一次性会员凭据(memberTicket,已删除)。2026-10-15 起 AIVA 把接口由 /uc/v1/user/identityCode/scan 换为 /uc/v1/user/identityCode/scan/oneid:请求不变,返回只有 ONEID(不再有昵称、手机号、头像);旧地址 AgentOS 不再调用。接口原文见仓库 docs/api/AIVA/aiva-services-api.txt(原文仍是 /scan 及其完整返回字段,以本节为准);与 M01、绑定结果推送、作品数据推送 共用同一个 AIVA 网关登记与签名方式。
功能描述
什么时候调用
- 互动点位调用扫码登录
POST /api/identity/point-login(见《互动应用开发接入文档》“扫码登录”),扫到的码是 AIVA 会员码格式(32 位小写十六进制)时调用本接口,token 为扫到的内容。来宾卡正面码(14 位短码或 …/c/短码 链接)不调用;两种格式都不是的,AgentOS 直接拒绝,不会调用本接口。
- 作品打印台 Pad 登录时规则相同。打印台只读登录,不建账户。
AgentOS 拿到结果后怎么做
- 把二维码内容原样作为
token 发给 AIVA,AIVA 返回 ONEID。
- 该 ONEID 在 AgentOS 已有账户:登录到该会员的主账户。
- 没有账户(会员首次到店):自动建账户并关联这个 ONEID,再调用 绑定结果推送 告诉 AIVA。
- 本接口不返回昵称、脱敏手机号、头像(2026-10-15 起)。扫码不再更新这三项:此前已保存的资料保留,仍随点位登录结果返回昵称和头像;之后首次到店的会员没有昵称和头像(返回
null)。
AIVA 的码只能用一次:AgentOS 不重试。如果 AIVA 已经认出人,但 AgentOS 这边建账户失败,登录直接报错,需要会员在小程序里刷新会员码再扫一次。
请求头:网关验签请求头与 M01 相同(timestamp、sign、accessKey、sysCode、msgId,签名规则见 M01),另加 sourceApp。
请求示例
curl -X POST "$AIVA_GATEWAY/uc/v1/user/identityCode/scan/oneid" \
-H "Content-Type: application/json" \
-H "timestamp: 1791850000000" \
-H "accessKey: $AIVA_ACCESS_KEY" \
-H "sysCode: SD" \
-H "sign: <按 M01 的签名规则计算>" \
-H "sourceApp: $AIVA_SOURCE_APP" \
--data '{"token":"<会员码二维码内容>","scanSourceApp":"<AIVA 提供>"}'
返回示例HTTP 200
{
"status": true,
"errorCode": "",
"errorMsg": "",
"data": {
"oneId": "oneid_example"
},
"time": 1791850000123,
"traceId": "…"
}
ONEID 会员对外接口文档 / AgentOS → AIVA
绑定结果推送(AgentOS 调用 AIVA)
方向:由 AIVA 提供、AgentOS 调用。会员第一次在门店点位扫 AIVA 会员码、AgentOS 新建账户并关联 ONEID 后,AgentOS 把绑定结果告诉 AIVA(AIVA 文档中的“链路二”)。2026-10-13 起提供。
功能描述
什么时候推:只在会员在互动点位扫 AIVA 会员码、AgentOS 新建账户并关联 ONEID 之后推一次。以下情况不推:
- 会员在小程序扫来宾卡背面太阳码绑卡(B03):绑定由 AIVA 发起,AIVA 已经知道结果;
- 已有账户的会员再次扫码登录;
- 作品打印台登录(打印台不建账户)。
怎么推:AgentOS 在新建账户的同一次数据库操作中先记一条“待发送”推送记录,登录完成后再发送,所以推送失败不影响登录和后续体验。AIVA 以 linkId 判断是否重复:同一个 linkId 重发多次只算一次。失败后的处理见 推送失败与后台重推。
请求头与 M01 相同(网关验签)。
请求示例
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/bindings" \
-H "Content-Type: application/json" \
-H "timestamp: 1791850000000" \
-H "accessKey: $AIVA_ACCESS_KEY" \
-H "sysCode: SD" \
-H "sign: <按 M01 的签名规则计算>" \
--data '{"oneid":"oneid_example","agentosId":"au_3f9c0d1e2a4b5c6d7e8f","linkId":"link_7c2e0a91","cardNo":null,"bindScene":null,"primaryAgentosId":"au_3f9c0d1e2a4b5c6d7e8f"}'
返回示例HTTP 200
{ "status": true, "errorCode": "", "errorMsg": "", "data": {}, "time": 1791850000123, "traceId": "…" }
HTTP 2xx、返回 JSON 且 status 为 true 时,AgentOS 把这条推送记为“已发送”。
ONEID 会员对外接口文档 / AgentOS → AIVA
作品数据推送(AgentOS 调用 AIVA)
方向:由 AIVA 提供、AgentOS 调用。会员在门店点位生成的作品,审核通过后由 AgentOS 同步一份到 AIVA 小程序后台。2026-10-13 起提供。
功能描述
什么时候推:作品保存到 AgentOS 并且审核通过之后,每个作品单独推一次。
- 2026-10-13 起,未登记内容安全或审核服务临时不可用时作品直接按通过处理,所以通常生成后马上推;内容安全判定不通过的作品不保存,也不推。
- 作品所属账户必须已关联 ONEID(AIVA 对 ONEID 为空的推送不保存)。只用来宾卡、还没在小程序绑定的用户,作品先不推;等他通过 B03 绑卡成功后,AgentOS 把这张卡之前已通过、还没推过的作品补推。后台定时任务也会定期补上漏推的作品。
- 只推本功能上线后生成的作品(上线前的作品不推)。已删除的作品不推;已推过的作品被删除时,由 AIVA 调用会员作品删除或批量删除作品同步删除。
推哪些作品
AI音乐的歌词还没写好时,这一轮先不推,下一轮再推,避免推出空歌词。
作品地址:作品原文件保存在公开读的对象存储,url / coverUrl 是公开地址,AIVA 可以直接打开(对象名为随机编号,删除作品即删除文件)。
怎么推:先记一条“待发送”推送记录再发送,推送内容在记录时固定,重推原样发送。eventId 每个作品一个,重推沿用同一个,AIVA 据此不重复处理。失败后的处理见 推送失败与后台重推。
请求头与 M01 相同(网关验签)。
请求示例
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/experience-records" \
-H "Content-Type: application/json" \
-H "timestamp: 1791850000000" \
-H "accessKey: $AIVA_ACCESS_KEY" \
-H "sysCode: SD" \
-H "sign: <按 M01 的签名规则计算>" \
--data '{"eventId":"20261013100015123a1b2c3d4e5f60718","oneId":"oneid_example","agentosId":"au_3f9c0d1e2a4b5c6d7e8f","bindScene":null,"experienceNo":"ix_6f1c0a2b","storeId":"ST0001","storeName":"重庆光环店","activityId":"P08","activityName":"AI图片生成","experienceTime":"2026-10-13T10:00:00.000+08:00","works":[{"workId":"asset_3f0a9c1e","type":"image","name":"AI图片生成_20261013100015","url":"https://<公开访问地址>/generated/ST0001/3b9d.png","coverUrl":null,"lyric":null,"createdAt":"2026-10-13T10:00:15.000+08:00"}]}'
返回示例HTTP 200
{ "status": true, "errorCode": "", "errorMsg": "", "data": {}, "time": 1791850000123, "traceId": "…" }
HTTP 2xx、返回 JSON 且 status 为 true 时,AgentOS 把这条推送记为“已发送”。
推送失败与后台重推
绑定结果推送与作品数据推送的失败处理相同(2026-10-13 用户确认):
- 先记录再发送:每条推送先记“待发送”记录,再发送。服务中途重启导致没发出去的记录,由后台定时任务接着发。
- 失败立即重发一次:用完全相同的内容(同一
linkId / eventId)再发一次,AIVA 据此不会重复处理。
- 仍失败就停下并告警:记录标为“失败”,保存 AIVA 返回的
errorCode、errorMsg(或对方原文),发出后台告警(事件 aiva.push_failed,站内信),不再自动重发。
- 后台手动重推:后台“用户与来宾卡 → 身份服务设置 → AIVA 推送记录”(需平台账号)列出全部推送,可按类型(绑定 / 作品)和状态(待发送 / 已发送 / 失败)筛选,查看推送内容、尝试次数与失败原因;失败的记录可以单条“重推”或“全部重推”(一次最多 200 条),手动重推只发一次。页签上的红点为失败条数。
推送永远不阻塞业务:登录、生成、打印照常进行。
ONEID 会员对外接口文档 / 后台操作
相关后台操作(AgentOS 内部)
以下由 AgentOS 运营在后台操作,不是对外接口,列出供对接时理解数据来源。
功能描述
为一个批次内未作废的卡生成并导出背面绑定参数 bindScene。每张卡的参数生成后固定不变(重复调用返回同一个值),与卡正面短码无关,也不能由 AgentOSID 推算。后台“卡批次 → 背面绑定参数”按钮即调用此接口;太阳码图片由 M01 生成。
请求示例
curl -X POST "$BASE/api/admin/card-batches/BATCH_20261001_01/binding-scenes" \
-H "Cookie: <后台登录会话>" \
-H "X-CSRF-Token: <登录响应中的 csrfToken>" \
-H "Content-Type: application/json" \
--data '{}'
返回示例HTTP 200
{
"items": [ { "card_code": "C000123", "card_no": "CQ0001023", "AgentOSID": "au_3f9c…", "bindScene": "Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx" } ],
"miniProgramCodeGenerated": false,
"note": "稳定的32字符绑定参数;由AIVA小程序服务生成对应太阳码,此接口不伪造太阳码图片。"
}
导出来宾卡打印图
后台“卡批次 → 导出打印图”:上传正反面卡面模板并登记码的位置,逐卡合成正面会员识别码({域名}/c/{离店短码})与背面太阳码(M01),打包下载。属于后台功能,不对外提供。
ONEID 会员对外接口文档 / 联调
联调测试工具
AgentOS 提供网页测试工具:https://aiva.dev.vavedigital.com/admin/tools/identity-test/。可以逐个调用本文接口和点位登录接口,也可以按场景一键验证:扫卡首次绑定、重复提交与冲突、无效参数、AIVA 会员码登录与退出(首次来访自动建档)、AIVA 会员码只能使用一次、门店卡登录、不同凭证互不通用、按 ONEID 汇总。其中 S5、S6 两个会员码场景需要手动填入真实的 AIVA 小程序会员码内容(在小程序打开会员码复制二维码内容,只能用一次,且所连环境须已登记 AIVA 网关及 sourceApp / scanSourceApp);原“AgentOS 会员凭据”相关场景已于 2026-10-13 删除。工具会在所连环境里写入测试用户和绑定,只用于测试环境。
单个接口调试另有 https://aiva.dev.vavedigital.com/admin/tools/oneid-test/:覆盖本文中 AIVA 调用 AgentOS 的全部 8 个接口(B02—B06、作品删除、批量删除作品、作品码查询),填写参数时实时显示完整请求(地址、请求头、请求体、curl),发送后显示状态码、耗时、响应头与响应体,并保留本页调用记录;凭证只显示末4位。B03、作品删除、批量删除作品会写入或删除所连环境数据,只用于测试环境。AgentOS 调用 AIVA 的四个接口不在工具中,推送结果请在后台“身份服务设置 → AIVA 推送记录”查看。
AgentOS 调用 AIVA 的接口另有 https://aiva.dev.vavedigital.com/admin/tools/aiva-test/(2026-10-13):需先在同一浏览器登录 AgentOS 后台(平台账号)。可直接调用二维码扫码识别(可临时填写 sourceApp / scanSourceApp,会消耗会员码)、绑定结果推送、作品数据推送与 M01 太阳码,显示 AgentOS 实际发出的请求(凭证脱敏)与 AIVA 原样返回;还列出所有用户的可同步作品,可单个“同步”,或“同步给其他用户”——先为目标用户(AgentOSID 或完整 ONEID,须已关联 ONEID)新增一条作品记录(文件另存一份、记录复制自哪个作品),再推送 AIVA。会向 AIVA 测试环境写数据,只用于测试环境。