文档首页> 云商店> 接入指南> SaaS类商品接入指南V1.0> 接口描述> 新购商品
更新时间：2024-07-17 GMT+08:00
查看PDF

新购商品

接口说明

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

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

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

    针对新购场景接口调用失败的情况，云商店会持续调用到60次（每3分钟1次）后停止调用。若服务商接口问题在60次调用时间内解决，则在下一次调用时接口响应成功，订单开通成功；若服务商接口问题在60次调用后仍无解决，系统则判断订单为失败，并自动进行订单退订。若商品单月因接口失败导致的失败订单超过5个，云商店将对该商品下架处理。

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

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

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

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

请求消息

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

请求方法：GET

参数

是否必选

参数类型

最大字符长度

说明

authToken

M

String

50

安全校验令牌。

取值请参见authToken取值说明。

timeStamp

M

String

20

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

格式：yyyyMMddHHmmssSSS

activity

M

String

20

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

新购场景取值：newInstance

customerId

M

String

100

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

customerName

O

String

64

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

userId

O

String

64

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

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

userName

O

String

64

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

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

mobilePhone

O

String

256

客户手机号码。

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

手机号加密规则如下：

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

iv+base64(AES_CBC(accessKey,mobilePhone))

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

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

说明：

客户手机号码不包含国家码，且若客户没有绑定手机号，将无法获取该参数。

email

O

String

256

客户邮箱。

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

邮箱加密规则如下：

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

iv+base64(AES_CBC(accessKey,email))

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

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

businessId

M

String

64

云商店业务ID。

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

orderId

M

String

64

云商店订单ID。

skuCode

O

String

64

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

说明：

该参数可在商品审核通过上架后，在“Seller Console > Product Management > My Products”页面，单击该商品操作列的的“Details”按钮进入商品详情页面获取。

productId

M

String

64

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

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

说明：

该参数可在商品审核通过上架后，在“Seller Console > Product Management > My Products”页面，单击该商品操作列的的“Details”按钮进入商品详情页面获取。

testFlag

O

String

2

是否为调试请求。

  • 1：调试请求
  • 0： 非调试请求

    默认取值为“0”。

trialFlag

O

String

2

是否是开通试用实例。

  • 0：非试用实例
  • 1：试用实例
  • 不传试用参数

expireTime

O

DateTime

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为发布商品时填写值。

amount

O

Integer

4

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

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

单位：个（次）

说明：

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

例如：30个用户

diskSize

O

Integer

4

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

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

单位：GB

说明：

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

例如：100GB

bandWidth

O

Integer

4

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

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

单位：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…

orderAmount

O

bigdecimal

20

订单金额。

说明：

仅通用商品订单请求时传该参数。

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

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

单位：美元

provisionType

O

integer

2

商品实例开通方式。

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

acceptanceTime

O

String

20

用户验收时间。

说明：

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

格式：yyyyMMddHHmmssSSS

startTime

O

String

20

开始时间。

格式：yyyyMMddHHmmss

说明：

只有按需套餐包商品新购时传递，其它计费类型不传。
  • 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://isvserver.com/produceAPI?activity=newInstance&businessId=03pf80c2bae96vc49b80b917bea776d7&customerId=3736bb8ad93b43fca8012c64a82cec25 &expireTime=20180725000000&orderId=HWS001014ED483AA1E8&productId= 005a8781ef0c4a47a3dbfc4c1e72871e&saasExtendParams=W3sibmFtZSI6ImVtYWlsMTEiLCJ2YWx1ZSI6ImVtYWlsMTFlbWFpbDExIn0seyJuYW1lIjoiZW1haWwyMiIsInZhbHVlIjoiZW1haWwyMmVtYWlsMjIifV0%3D&timeStamp=20170725025113409&testFlag=0&authToken=09lsS5y+KCtxBu+ON4TXv1SrjH5KVYka9sx2MauHrQU=

响应消息

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

参数

是否必选

类型

最大字符长度

参数说明

resultCode

M

String

6

调用结果码。

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

resultMsg

O

String

255

调用结果描述。

encryptType

O

String

2

敏感信息加密算法

1：AES256_CBC_PKCS5Padding（默认值）

2：AES128_CBC_PKCS5Padding

说明：

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

instanceId

O

String

64

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

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

说明：

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

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

appInfo

O

AppInfo

N/A

应用实例信息。

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

说明：

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

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

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

appInfo为JSON字符串，数据结构定义请参见下表。

AppInfo数据结构定义如下：

参数

是否必选

类型及范围

最大字符长度

参数说明

frontEndUrl

M

String

512

前台地址。

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

adminUrl

O

String

512

管理地址。

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

userName

O

String

128

加密后的管理员账号。

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

iv+base64(AES_CBC(accessKey,userName))

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

password

O

String

128

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

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

iv+base64(AES_CBC(accessKey,pwd))

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

ip

O

String

64

网站的IP。

memo

O

String

1024

备注。
  • 获取accessKey，请参见获取Key值。
  • 用户名密码所校验的长度是密文的长度（包括iv向量）。
  • 服务商的服务器在处理接口请求时，需要做好幂等性处理。

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

  • SaaS实例信息如果有变化，例如，adminUrl发生变化，在云商店服务重新调用此接口，传入相同的orderId时，服务商的服务器需要返回更新后的SaaS实例信息。

    为保证安全，云商店不持久存储SaaS实例信息。

    ISV生产接口响应中，除memo参数外，其他参数请不要返回中文。

响应消息示例：

{
    "resultCode":"000000",
    "resultMsg":"success.",
    "instanceId":"03pf80c2bae96vc49b80b917bea776d7",
    "encryptType":"1",
    "appInfo":{
        "frontEndUrl":"http://www.isvserver.com",
        "adminUrl":"http://www. isvserver.com",
        "userName":"luQg154bx766030TobyT0ghfQRx3tvVEdpwMRg==",
        "password":"7Bx4DyX7980a59T0qbhnpfhCz82Uc5cZQQtExg=="
    }
}

父主题： 接口描述