目录

服务动态推送接口

功能介绍

元服务调用服务动态发送API,完成服务动态消息下发。

使用约束

请求体结构说明

[h2]接口原型

[projectId] :项目ID,登录AppGallery Connect网站,选择“开发与服务”,在项目列表中选择对应的项目,左侧导航栏选择“项目设置”,在该页面获取。

[h2]Request Header

参数 取值描述 样例
Authorization

鉴权方式:

JWT方式

详情参见基于服务账号生成鉴权令牌。

说明:

· 调用服务动态API接口必须使用PS256算法。

· 建议JWT令牌过期时间设置为3600秒,有效期内可以复用。

· Bearer后面拼接空格,再拼接获取的鉴权信息。

Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****

[h2]Request Body

参数 是否必选 参数类型 描述
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://***"
            }
        ]
    }
}

响应参数

[h2]Response Body

参数 是否必选 参数类型 描述
code 是 String 响应码。
msg 是 String 响应码描述。
requestId 是 String 请求标识。

响应示例

响应成功示例:

{
  "code": "80000000",
  "msg": "Success",
  "requestId": "157*******006"
}

响应失败示例:

{
  "code": "82600010",
  "msg": "status content missing required field",
  "requestId": "157*******006"
}

HTTP响应码

HTTP响应码 描述 解决方法
200 成功。 -
400 参数错误。 请检查业务响应码并根据业务响应码进一步排查问题。
401 鉴权失败。 请检查HTTP头中Authorization参数。
404 找不到服务。 请检查请求URL是否正确。
500 服务内部错误。 请通过在线提单提交问题。
502 请求连接异常,常见于网络状况不稳定。 建议稍后重试,或通过在线提单提交问题。
503 流量控制。

· 平均分配发送速度。

· 平均分布推送时间段,不要集中发送。

504 网关超时。 建议稍后重试,或通过在线提单提交问题。

业务响应码

[h2]80000000 成功

错误信息

Success.

错误描述

发送成功。

可能原因

发送成功。

处理步骤

不涉及。

[h2]82600001 系统内部错误

错误信息

system error.

错误描述

系统内部错误。

可能原因

其他未知错误。

处理步骤

请通过在线提单提交问题。

[h2]82600002 参数错误

错误信息

invalid parameter {errorTips}.

错误描述

参数错误。

可能原因

携带的参数不合法。

处理步骤

请按照响应消息中的提示,检查并修改请求参数。

[h2]82600003 拒绝服务

错误信息

access deny.

错误描述

拒绝服务。

可能原因

未开通服务动态消息发送权益。

处理步骤

请开通服务动态消息发送权益。

[h2]82600004 风控异常

错误信息

status content blocked.

错误描述

风控异常。

可能原因

场景参数中存在违禁参数。

处理步骤

请按照响应消息中的提示,检查场景参数是否携带违禁参数。

[h2]82600005 服务动态下发异常

错误信息

send message failed{errorTips}.

错误描述

服务动态下发异常。

可能原因

  1. 接收端没有在线设备。

  2. 请求消息体超过默认大小(4096Bytes)。

处理步骤

按照响应消息中的提示,检查消息下发异常情况:

  1. 检查接收端是否有在线设备。

  2. 检查请求消息体是否超过默认大小(4096Bytes),并减小请求体后重新推送。

[h2]82600006 openID校验异常

错误信息

invalid openId.

错误描述

openID校验异常。

可能原因

携带不正确接收者openID。

处理步骤

请使用从端侧上报的openID,或请求华为账号服务器获取用户信息中的openID。

[h2]82600007 场景及子场景标识错误

错误信息

invalid sceneId or subSceneId.

错误描述

场景及子场景标识错误。

可能原因

场景及子场景未开通权益。

处理步骤

请按照已开通权益的场景及子场景标识发送。

[h2]82600008 授权码错误

错误信息

invalid code.

错误描述

授权码错误。

可能原因

  1. 交易订单号非法。

  2. 交易订单号超期未激活(有效期1小时)。

处理步骤

请检查交易订单号:

  1. 确保交易订单号合法。

  2. 请重新生成code进行推送。

使用华为支付订单号sysTransOrderNo作为授权码,重新推送消息。

[h2]82600009 场景状态错误

错误信息

invalid scene status.

错误描述

场景状态错误。

可能原因

请求体参数错误。

处理步骤

请按照响应消息中的提示,请按照服务动态发送场景说明检查并修改请求体参数。

[h2]82600010 状态必填参数缺失

错误信息

status content missing required field {errorTips}.

错误描述

状态必填参数缺失。

可能原因

状态必填参数缺失。

处理步骤

请按照响应消息中的提示,请按照服务动态发送场景说明检查并修改请求体参数。

[h2]82600011 状态参数格式不合法

错误信息

status content has invalid field {errorTips}.

错误描述

状态参数格式不合法。

可能原因

状态参数格式不合法。

处理步骤

请按照响应消息中的提示,检查并修改请求体参数。

[h2]82600012 状态跳转非法

错误信息

invalid status transition.

错误描述

状态跳转非法。

可能原因

状态跳转非法。

处理步骤

[h2]82600013 用户关闭服务动态推送

错误信息

user close service.

错误描述

用户关闭服务动态推送。

可能原因

用户关闭该场景服务动态推送。

处理步骤

请检查服务动态开关是否关闭,如关闭,需打开开关后再调用接口进行测试。服务动态开关设置路径:桌面主屏从左往右滑进入负一屏,点击头像进入“我的”,点击页面右上角,再点击“动态管理”,在“服务动态”列表找到对应的场景开关进行操作。

[h2]82600014 非法的图片资源ID

错误信息

invalid image id.

错误描述

非法的图片资源ID。

可能原因

资源ID对应的图片资源不存在。

处理步骤

请检查资源ID对应的图片资源是否存在,不存在则需要通过申请图片资源托管提供图片重新获取资源ID。

[h2]82600015 状态刷新次数超过限制

错误信息

status refresh frequency reached upper limit.

错误描述

状态刷新次数超过限制。

可能原因

状态刷新次数超过限制。

处理步骤

状态刷新次数超过限制,请减少无效状态刷新。

[h2]82600016 服务动态超期

错误信息

event expired.

错误描述

服务动态超期。

可能原因

服务动态超期,超过expireTime后将禁止刷新该服务动态消息。

处理步骤

合理设置expireTime并重新推送消息。

[h2]82600017 用户无授权设备

错误信息

no authorization device.

错误描述

用户无授权设备。

可能原因

用户该场景无授权设备。

处理步骤

用户该场景无授权设备,请添加授权设备再重新推送消息。

添加路径:

[h2]82600018 服务动态事件已结束

错误信息

event already closed.

错误描述

服务动态事件已结束。

可能原因

该事件已关闭,不允许继续发送。

处理步骤

该事件已关闭,不允许继续发送,请重新创建服务动态事件下发消息。

[h2]82600019 激活授权码超出阈值

错误信息

code reached upper limit.

错误描述

激活授权码超出阈值。

可能原因

向同一用户推送的授权码超过50个。

处理步骤

默认向同一用户推送的授权码不能超过50个,请减少授权码个数。