承载协议: HTTPS POST
接口方向: 开发者服务器 -> 华为Push服务器
接口URL: https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send
数据格式: Content-Type: application/json
| 参数 | 取值描述 | 样例 |
|---|---|---|
| Authorization | 鉴权方式: JWT方式 详情参见基于服务账号生成鉴权令牌。 说明: · 调用服务动态API接口必须使用PS256算法。 · 建议JWT令牌过期时间设置为3600秒,有效期内可以复用。 · Bearer后面拼接空格,再拼接获取的鉴权信息。 | Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---**** |
| 参数 | 是否必选 | 参数类型 | 描述 |
|---|---|---|---|
| toOpenId | 是 | String | 接收者(用户)账号登录的openID。使用从端侧上报的openID,或请求华为账号服务器获取用户信息。可参考元服务账号使用规范进行华为账号登录的设计和接入。 |
| appId | 是 | String | 元服务的APP ID。长度范围[1, 64]。 说明: [appId] :登录AppGallery Connect网站,选择“APP与元服务”,在列表中选择对应的元服务,左侧导航栏选择“应用信息”,在应用信息页面下的基本信息中获取APP ID的值。 |
| sceneId | 是 | String | 场景标识,详细参见服务动态发送场景说明。长度范围[1, 32]。 |
| subSceneId | 是 | String | 子场景标识,详细参见服务动态发送场景说明。长度范围[1, 32]。 |
| code | 是 | String | · 当用户在元服务内调用华为支付收银台进行支付时,开发者可获得华为支付订单号sysTransOrderNo,可直接作为code。 · 当用户通过前端场景化button获取code时,开发者可以使用服务动态授权码Button获取code。 |
| content | 是 | TimelineStatusContent Object | 服务动态指定状态参数。 若您是外卖自取场景,请参考外卖自取结构体说明。 若您是外卖配送场景,请参考外卖配送结构体说明。 |
根据不同状态必传参数、选填参数发送请求。以外卖自取场景为例。
请求示例:制作中
// Request URL
POST "https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send"
// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
// Request Body
{
"appId": "5**********7",
"toOpenId": "A**********O",
"sceneId": "10001",
"subSceneId": "100010001",
"code": "3**********7",
"content": {
"status": 3,
"orderTime": 1716191520,
"amount": "¥ 18.00",
"productCount": 1,
"productName": "霸气芒果",
"productImg": "image_test_1",
"merchantName": "威**********店",
"pickupNumber": "1668",
"pickupTime": "16:08",
"remainOrders": "5单/共5杯",
"waitTime": "10-20分钟",
"button": {
"type": 0,
"text": "取餐码",
"data": {
"testKey": "testValue"
}
},
"clickAction": {
"type": 0,
"data": {
"testKey": "testValue"
}
},
"appendButtons": [
{
"type": 0,
"text": "取餐码",
"data": {
"testKey": "testValue"
}
}
]
}
} 请求示例:待支付
// Request URL
POST "https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send"
// Request Header
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
// Request Body
{
"appId": "6**********3",
"toOpenId": "A**********F",
"sceneId": "10001",
"subSceneId": "100010001",
"code": "1**********6",
"content": {
"status": 1,
"orderTime": 1715236319,
"amount": "¥ 5.00",
"productCount": 1,
"productName": "霸气芒果",
"productImg": "image_test_1",
"paymentEndTime": "5分钟内支付",
"merchantName": "**********园店",
"button": {
"type": 0,
"text": "立即支付",
"action": "https://***"
},
"clickAction": {
"type": 0,
"action": "https://***"
},
"appendButtons": [
{
"type": 0,
"text": "立即支付",
"action": "https://***"
}
]
}
} 响应成功示例:
{
"code": "80000000",
"msg": "Success",
"requestId": "157*******006"
} 响应失败示例:
{
"code": "82600010",
"msg": "status content missing required field",
"requestId": "157*******006"
} 错误信息
invalid parameter {errorTips}.
错误描述
参数错误。
可能原因
携带的参数不合法。
处理步骤
请按照响应消息中的提示,检查并修改请求参数。
错误信息
status content blocked.
错误描述
风控异常。
可能原因
场景参数中存在违禁参数。
处理步骤
请按照响应消息中的提示,检查场景参数是否携带违禁参数。
错误信息
send message failed{errorTips}.
错误描述
服务动态下发异常。
可能原因
接收端没有在线设备。
请求消息体超过默认大小(4096Bytes)。
处理步骤
按照响应消息中的提示,检查消息下发异常情况:
检查接收端是否有在线设备。
检查请求消息体是否超过默认大小(4096Bytes),并减小请求体后重新推送。
错误信息
invalid openId.
错误描述
openID校验异常。
可能原因
携带不正确接收者openID。
处理步骤
请使用从端侧上报的openID,或请求华为账号服务器获取用户信息中的openID。
错误信息
invalid sceneId or subSceneId.
错误描述
场景及子场景标识错误。
可能原因
场景及子场景未开通权益。
处理步骤
请按照已开通权益的场景及子场景标识发送。
错误信息
invalid code.
错误描述
授权码错误。
可能原因
交易订单号非法。
交易订单号超期未激活(有效期1小时)。
处理步骤
请检查交易订单号:
确保交易订单号合法。
请重新生成code进行推送。
使用华为支付订单号sysTransOrderNo作为授权码,重新推送消息。
错误信息
invalid scene status.
错误描述
场景状态错误。
可能原因
请求体参数错误。
处理步骤
请按照响应消息中的提示,请按照服务动态发送场景说明检查并修改请求体参数。
错误信息
status content missing required field {errorTips}.
错误描述
状态必填参数缺失。
可能原因
状态必填参数缺失。
处理步骤
请按照响应消息中的提示,请按照服务动态发送场景说明检查并修改请求体参数。
错误信息
status content has invalid field {errorTips}.
错误描述
状态参数格式不合法。
可能原因
状态参数格式不合法。
处理步骤
请按照响应消息中的提示,检查并修改请求体参数。
错误信息
invalid status transition.
错误描述
状态跳转非法。
可能原因
状态跳转非法。
处理步骤
若您是外卖自取场景,请按照自取场景服务动态参数要求检查并修改请求体参数。
若您是外卖配送场景,请按照配送场景服务动态参数要求检查并修改请求体参数。
错误信息
user close service.
错误描述
用户关闭服务动态推送。
可能原因
用户关闭该场景服务动态推送。
处理步骤
请检查服务动态开关是否关闭,如关闭,需打开开关后再调用接口进行测试。服务动态开关设置路径:桌面主屏从左往右滑进入负一屏,点击头像进入“我的”,点击页面右上角
,再点击“动态管理”,在“服务动态”列表找到对应的场景开关进行操作。
错误信息
invalid image id.
错误描述
非法的图片资源ID。
可能原因
资源ID对应的图片资源不存在。
处理步骤
请检查资源ID对应的图片资源是否存在,不存在则需要通过申请图片资源托管提供图片重新获取资源ID。
错误信息
status refresh frequency reached upper limit.
错误描述
状态刷新次数超过限制。
可能原因
状态刷新次数超过限制。
处理步骤
状态刷新次数超过限制,请减少无效状态刷新。
错误信息
event expired.
错误描述
服务动态超期。
可能原因
服务动态超期,超过expireTime后将禁止刷新该服务动态消息。
处理步骤
合理设置expireTime并重新推送消息。
错误信息
no authorization device.
错误描述
用户无授权设备。
可能原因
用户该场景无授权设备。
处理步骤
用户该场景无授权设备,请添加授权设备再重新推送消息。
添加路径:
方式一:桌面主屏从左往右滑进入负一屏,点击头像进入“我的”,点击页面右上角
,再点击“设置 > 服务数据同步 > 本设备开关打开”,开启设备授权。
方式二:打开任意元服务,点击页面右上角
,再点击“设置 > 服务数据同步 > 本设备开关打开”,开启设备授权。