文档首页/ 云商店/ 接入指南/ 商品接入相关接口/ SaaS类商品接入指南 V1.0（已下线）/ 联营SaaS类商品接入指南 V1.0/ 接口描述/ 基础接口描述/ 新购商品
更新时间：2024-12-25 GMT+08:00
查看PDF
分享

新购商品

接口说明

  • 客户购买商品并付款成功，云商店将调用本接口通知商家客户购买商品的信息和客户信息，商家收到该请求信息，需执行新购对应动作并将执行结果返回给云商店。
  • 商家需要返回此订单对应的唯一实例ID（instanceId），对不同的新购订单实例ID（instanceId）不可一致。建议此ID直接使用该订单首次请求时云商店传入的businessId，以确保instanceId的唯一性。

    按需商品是以规格维度交易的，如果一个规格下配置了多个按需计费项，就会出现一个订单ID对应多个接口请求的情况，需要基于订单号（orderId）和产品标识（productId）来创建实例，即在按需交易场景下，一个订单对会对应多个实例。

  • 当接口响应失败时，系统会邮件通知到商家云商店账号绑定的邮箱，生产接口消息中可查询接口“异常信息”，商家收到通知后须尽快处理接口异常，避免订单失败退订。

    针对新购场景接口调用失败的情况，云商店会持续调用3小时后停止调用，期间商家可在“卖家中心>生产接口消息”页面单击对应订单右侧操作栏的“重新启动”进行手动重试。若商家接口问题在3小时调用时间内解决，则在下一次调用接口响应成功，订单开通成功；若商家接口问题在3小时调用后仍未解决，系统则判断订单为失败，并自动进行订单退订。若商品单月因接口失败导致的失败订单超过5个，云商店将对该商品下架处理。

    • 请及时关注商家信息中客服邮箱以及云商店账号绑定的邮箱及手机的通知，收到调用失败通知及时处理接口异常。
    • 云商店会对接口异常导致订单失败的情况做监控，如SaaS商品频繁出现因接口异常导致订单失败的情况，云商店将对该商品做下架处理。
  • 商家的服务器在处理接口请求时，需要做好幂等性处理。

    云商店服务有可能重发请求，针对同一订单号（orderId），商家的服务器应当返回成功的响应及应用实例信息，不应该创建新的SaaS实例，返回之前成功创建的实例信息即可。

    按需交易场景，需要基于订单号（orderId）和产品标识（productId）构建幂等。

新购商品流程如下图所示：

请求消息

请求参数说明请参见下表。云商店会结合商家创建上架的商品售卖模式来对应请求，商家也需要根据请求的信息来对应执行生产。

请求方法：GET

参数

是否必选

参数类型

最大字符长度

说明

authToken

M

String

50

安全校验令牌。

取值请参见auth Token取值说明。

timeStamp

M

String

20

请求发起时的时间戳，取UTC时间。

格式：yyyyMMddHHmmssSSS

activity

M

String

20

接口请求标识，用于区分接口请求场景。

新购场景取值：newInstance

customerId

M

String

100

客户在华为云注册账号的唯一标识。

customerName

M

String

64

客户在华为云注册的账户名。

userId

O

String

64

客户以IAM用户认证方式登录时对应子用户的唯一标识。

非必传，如需此参数，在商品发布时“需要用户授权”请选择“基于IAM用户名创建应用管理账号等信息”。

userName

O

String

64

客户以IAM用户认证方式登录的用户名。

非必传，如需此参数，在商品发布时“需要用户授权”请选择“基于IAM用户名创建应用管理账号等信息”。

mobilePhone

O

String

256

客户手机号。

非必传，如需此参数，在商品发布时“需要用户授权”请选择“基于手机号码创建应用管理账号等信息”，取值为加密后的手机号码。

手机号加密规则如下：

由16位iv加密向量和base编码后的手机号密文组成。

iv+encryptAESCBCEncode(mobilePhone, accessKey, iv, keySize)

加密位数取ISV发布产品时选择的加密位数。

手机加密代码示例请参见ISV Server对资源开通后的用户名和密码加密。

手机解密代码示例请参见ISV Server解密手机号和邮箱。

说明：

手机号不包含国家码。

email

O

String

256

客户邮箱。

非必传，如需此参数，在商品发布时“需要用户授权”请选择“基于邮箱创建应用管理账号等信息”，取值为加密后的邮箱。

邮箱加密规则如下：

由16位iv加密向量和base编码后的邮箱密文组成。

iv+encryptAESCBCEncode(email, accessKey, iv, keySize)

加密位数取ISV发布产品时选择的加密位数。

邮箱加密代码示例请参见ISV Server对资源开通后的用户名和密码加密。

邮箱解密代码示例请参见ISV Server解密手机号和邮箱。

businessId

M

String

64

云商店业务ID。

每一次请求，businessId皆不一致。

orderId

M

String

64

云商店订单ID。

skuCode

O

String

64

产品规格标识。租户购买包月或包年的产品后，可能会续费，续费支持变更周期类型（例如包月转包年），此时，租户开通的实例instanceId对应的productId会变化，但skuCode不变。

说明：

该参数可在商品审核上架后，进入“卖家中心> 商品管理 > 我的商品 ”页面，单击该商品操作列的“详情”进入商品详情页面获取。

productId

M

String

64

产品标识，同一skuCode下，不同周期类型的productId不同。

例如：ISV发布产品，新增一个规格，会生成一个skuCode，再配置包年价格，包月价格，会生成两个productId。

说明：

该参数可在商品审核上架后，进入“卖家中心 > 商品管理 > 我的商品 ”页面，单击该商品操作列的“详情”进入商品详情页面获取。

trialFlag

O

String

2

是否是开通试用实例。

  • 1：试用实例
  • 0：非试用实例
  • 不传试用参数：2018年5月12日之前已发布成功的产品实例
    说明：

    取值为“0”时默认不传。

    取值为“1”时，periodType类型为：天：“day”。

testFlag

O

Integer

1

是否调测数据。

  • 1：接口调测数据
  • 不传参数：真实买家同步数据

startTime

O

String

20

开始时间。

格式：yyyyMMddHHmmss

说明：

只有按需套餐包商品新购时传递，其它计费类型不传。

expireTime

O

String

20

过期时间。

格式：yyyyMMddHHmmss

说明：
  • 按周期售卖的商品，会请求该参数。
  • 按需套餐包商品，会请求该参数。
  • 按需售卖的商品，不会请求该参数。
  • 按次售卖的商品，不会请求该参数。
  • 过期时间根据订单创建时间和购买周期计算而来，与订单实际过期时间有误差，仅供参考，不建议做其他用途，具体过期操作，以过期请求为准。

chargingMode

O

Integer

[3]

计费模式。

0：表示按需购买

1：表示包周期购买

3：表示按次购买

5：表示按需套餐包购买

saasExtendParams

O

String

2048

扩展参数。非必填。

扩展参数格式为json数组字符串通过 urlEncode(base64(saasExtendParams))携带到url参数中。在得到saasExtendParams参数的值后，需要通过base64Decode(urlDecode(saasExtendParams))获取扩展参数json数组。

例如：[{"name":"emailDomainName","value":"test.xxxx.com"},{"name":"extendParamName","value":"extendParamValue"}]

其中emailDomainName和extendParamName为发布商品时填写值。

说明：

（本说明仅适用于WeLink开放平台开发的商品）

请先在应用接入调试页面调测“WeLink商品接口调测必选参数”，发布WeLink开放平台开发的商品时，会包含name值为platformParams的扩展参数，值为json格式字符串，包含tenantName、tennantId、userId三个参数。

  • tenantName是WeLink中的企业名
  • tennantId是WeLink中的企业唯一标识符
  • userId是WeLink中订阅该应用的用户，通常为企业管理员（WeLink企业管理员可以有多个且企业管理员账号可被注销）

amount

O

Integer

7

数量类型的商品定价属性。非必填。

属性名称：数量（支持商家自定义名称）

单位：个（次）

说明：

对于包周期或一次性计费的多SKU定价的SaaS商品，租户下单购买包含“数量”线性属性的规格时，会填写及调整购买的个数或次数。

例如：30个用户

diskSize

O

Integer

7

数量类型的商品定价属性。非必填。

属性名称：硬盘大小（支持商家自定义名称）

单位：GB

说明：

对于包周期或一次性计费的多SKU定价的SaaS商品，租户下单购买包含“硬盘大小”线性属性的规格时，会填写及调整购买多少GB。

例如：100GB

bandWidth

O

Integer

7

数量类型的商品定价属性。非必填。

属性名称：带宽（支持商家自定义名称）

单位：Mbps

说明：

对于包周期或一次性计费的多SKU定价的SaaS商品，租户下单购买包含“带宽”线性属性的规格时，会填写及调整购买多少Mbps。

例如：20Mbps

periodType

O

String

10

周期类型。

说明：

非必传，如需此参数，计费类型需选择包周期或按需套餐包chargingMode=1、5，包周期及按需套餐包购买场景请求时传该参数

年："year"

月："month"

天：“day”

chargingMode=3、0，按次数及按需购买场景请求时不传该参数。

periodNumber

O

integer

5

周期数量。

说明：

非必传，如需此参数，计费类型需选择包周期或按需套餐包chargingMode=1、5，包周期及按需套餐包购买场景请求时传该参数。

周期数量：1,2,3…

provisionType

O

integer

2

商品实例开通方式。

说明：
  • 用户购买后同步开通（默认，云商店轮询调用newInstance生产接口）
  • 用户确认验收后开通（SaaS涉及服务监管）
    1. 用户购买该商品时，云商店调用新购商品接口，商家需返回结果码订单创建成功000000。
    2. 当商家点击开通交付时，云商店调用新购商品接口，商家需返回结果码成功000000。
    3. 用户点击确认验收时，云商店调用新购商品传入用户验收时间给到商家，商家需返回结果码成功000000。

acceptanceTime

O

String

20

用户验收时间。

说明：

此时间为用户计费开始时间，如选择的商品实例开通方式为“用户确认验收后开通”，则用户验收时间为必填项。

格式：yyyyMMddHHmmssSSS

orderAmount

O

bigdecimal

20

订单金额。

说明：

该金额为用户实际支付金额，供商家对账参考。

金额值大于等于0，最大三位小数。

单位：元
  • 2018年5月12日新增接口参数：trialFlag和skuCode。
    • 2018年5月12日之后发布产品或已发布成功的产品新增规格时，请填写此新参数并通过接口调试（trialFlag的三种值都要调试通过）。
    • 2018年5月12日之前已发布成功的产品如果不涉及免费试用变更，不要求做接口调试。
  • 2018年8月9日新增SaaS计费模式“按次”发布接口，如需选择“按次”发布，遵循SaaS类商品接入指南调试通过后才可选择该计费模式“按次”发布商品。
  • 2019年9月27日新增数量类型定价属性接口参数：amount、diskSize和bandWidth。如需发布支持多SKU定价的商品规格，且定价属性中包含数量类型的属性（数量、带宽、硬盘大小等），请先在商品属性管理页面新建数量类型属性，然后回到调试页面选择要进行调试的数量类型属性，填写参数值，进行调试。
  • 接口调试说明请参考 接口调试。

请求消息示例：

https://example.isv.com?activity=newInstance&businessId=03pf80c2bae96vc49b80b917bea776d7&customerId=3736bb8ad93b43fca8012c64a82cec25 &expireTime=20180725000000&orderId=HWS001014ED483AA1E8&productId= 005a8781ef0c4a47a3dbfc4c1e72871e&saasExtendParams=W3sibmFtZSI6ImVtYWlsMTEiLCJ2YWx1ZSI6ImVtYWlsMTFlbWFpbDExIn0seyJuYW1lIjoiZW1haWwyMiIsInZhbHVlIjoiZW1haWwyMmVtYWlsMjIifV0%3D&timeStamp=20170725025113409&testFlag=1&authToken=09lsS5y+KCtxBu+ON4TXv1SrjH5KVYka9sx2MauHrQU=

响应消息

响应参数说明请参见下表：

参数

是否必选

类型

最大字符长度

参数说明

resultCode

M

String

6

调用结果码。

具体请参见调用结果码说明。

resultMsg

O

String

255

调用结果描述。

encryptType

O

String

3

敏感信息加密算法

1：AES256_CBC_PKCS5Padding（默认值）

2：AES128_CBC_PKCS5Padding

说明：

敏感信息加密算法是AES256_CBC_PKCS5Padding时返回值为1，敏感信息加密算法是AES128_CBC_PKCS5Padding时返回值为2。

instanceId

M

String

64

实例ID，商家提供的唯一标识。

建议此ID直接使用该订单首次请求时云商店传入的businessId，以确保instanceId的唯一性。

说明：

云商店每次请求时的businessId皆不一致，如取businessId作为instanceId，取订单首次调用时的businessId即可。

若通过其他方式生成instanceId，请确保该参数的全局唯一性，例如使用UUID生成。避免生成的instanceId发生重复，导致用户开通SaaS实例失败。

appInfo

O

AppInfo

N/A

应用实例信息。

客户购买商品后，商家需要返回登录服务地址（网站地址）或免登地址供客户后续操作。

说明：

SaaS商品必须向客户提供应用使用信息，包括使用地址、账号、密码等。

如可实现通过短信、邮件等其他方式发送使用信息，则接口中允许不响应；否则，必须在接口中返回应用实例信息。

如使用信息不仅包含使用地址及账号密码，可通过如下memo参数灵活返回其他使用信息或使用说明等。

appInfo数据结构定义请参见下表。

AppInfo数据结构定义如下：

参数

是否必选

类型及范围

最大字符长度

参数说明

frontEndUrl

M

String

512

前台地址。

客户购买商品后，可以访问的网站地址。

adminUrl

O

String

512

管理地址。

客户购买商品后，可以访问的管理后台地址。

userName

O

String

128

加密后的管理员账号。

客户购买商品后，访问商家管理后台的账号（一般为邮箱和手机号）。该值由16位iv加密向量和base编码后的用户名密文组成。

iv+encryptAESCBCEncode(userName, accessKey, iv, keySize)

需要使用Key值对账号做加密处理，加密算法以encryptType参数为准。代码示例请参见ISV Server对资源开通后的用户名和密码加密。

password

O

String

128

加密后的管理员初始密码。

客户购买商品后，访问商家管理后台的密码（一般由商家生成）。该值由16位iv加密向量和base编码后的密码密文组成。

iv+encryptAESCBCEncode(password, accessKey, iv, keySize)

需要使用Key值对密码做加密处理，加密算法以encryptType参数为准。代码示例请参见ISV Server对资源开通后的用户名和密码加密。

memo

O

String

1024

备注。

说明：

如果备注包含中文内容，请将中文转换成unicode编码，例如：“中文”可以转换成“\u4e2d\u6587”。
  • 获取accessKey，请参见获取Key值。
  • 用户名密码所校验的长度是密文的长度（包括iv向量）。
  • 商家的服务器在处理接口请求时，需要做好幂等性处理。

    云商店服务有可能重发请求，针对同一订单号，商家的服务器应当返回成功的响应及应用实例信息，不应该创建新的SaaS实例，返回之前成功创建的实例信息即可。

  • SaaS实例信息如果有变化，例如，adminUrl发生变化，在云商店服务重新调用此接口，传入相同的orderId时，商家的服务器需要返回更新后的SaaS实例信息。为保证安全，云商店不持久存储SaaS实例信息。
  • ISV生产接口响应中，除memo参数外，其他参数请不要返回中文。

响应消息示例：

{
    "resultCode":"000000",
    "resultMsg":"success.",
    "instanceId":"03pf80c2bae96vc49b80b917bea776d7",
    "encryptType":"1",
    "appInfo":{
        "frontEndUrl":"https://marketplace.huaweicloud.com/",
        "adminUrl":"https://marketplace.huaweicloud.com",
        "userName":"luQ***TobyT***Rx***pwMRg==",
        "password":"7Bx***5***hC***atExg==",
        "memo" : "have a test, 测试！"
    }
}

父主题： 基础接口描述

相关文档