华为云云商店联营SaaS接入指导

针对服务商需要接入云商店联营SaaS的场景，本套资料对联营kit对接流程做了梳理、对接过程中常见问题做了归纳，服务商可以借助本套资料开展联营SaaS接入工作。

资料阅读指导：

    1、在做联营kit对接前先阅读 “SAAS对接学习材料.pdf ”和 “SAAS对接学习视频”；

    2、联营kit对接过程中遇到问题可以查询“SAAS对接FAQ.pdf”；

    3、接口对接完成后发布测试商品及自验参考“现网测试指南.pdf”和“联营SaaS类商品使用指导.pdf”。

    （* 完整资料可以在博客最下方附件处下载。）

资料无法解决的问题可以提开发者工单解决。

联营SaaS对接常见问题：

1、云商店是否可以提供正向代理服务器的IP地址给商家，以建立访问白名单？

• 云商店对外访问的IP不是固定的，因此不提供具体IP地址。

2、接口调测里面的生产地址是什么？

• 生产地址是商家用来接收华为云商店同步数据的地址，商品的五个地址和kit的五个地址要求填写一样的值
• 假设接口生产地址为：https://www.example.com/test

            1.商品的五个接口(get请求)，通过参数activity的值来识别是哪个接口在同步数据(具体参见接口描述)，

                 基础接口地址：https://www.example.com/test

            2. KIT的五个接口(post请求)，在生产地址后面自动拼接对应固定子路径来区分哪个接口同步数据(具体参见接口描述)

                 KIT接口地址：

                 租户信息同步接口：https://www.example.com/test/produceAPI/tenantSync

                 租户应用信息同步接口：https://www.example.com/test/produceAPI/applicationSync

                 租户应用授权信息同步接口：https://www.example.com/test/produceAPI/authSync

                 组织部门信息同步（增量）：https://www.example.com/test/produceAPI/singleOrgSync

                 组织部门信息同步（全量）：https://www.example.com/test/produceAPI/allOrgSync

                 注:在不改变页面填写的参数的前提下，每个接口多次调测都要能保证返回成功，各个接口间没有先后顺序

3、生产地址能不能先使用商家测试环境的地址？

• 可以先使用测试环境地址调测接口、创建应用凭证、对接登录，但是发布商品时必须创建正式的应用凭证，因此在申请正式的应用凭证前还需用生产环境的地址调测接口、创建应用凭证、对接登录。

4、云商店对商家提供的生产地址有什么要求？

• 生产地址格式为 协议（仅支持https）+域名+端口。

5、租户同步中的域名domainName应该如何填写？有何用处？

• domainName在接口调测时仅用于测试，可随便填写；在实际的租户同步接口中，domainName是云商店分配的，买家在下单商品后，云商店会同步租户信息至商家侧，商家需要存储租户ID和域名的对应关系；domainName的具体使用请参见登录流程。

6、申请应用凭证云商店调用租户同步接口时，商家收到的数据为什么少了instanceId、orderId字段？

• 申请应用凭证云商店调用租户同步接口时，由于没有真实的订单信息，所以这两个字段都是为空。只有当买家去购买商家的商品，产生真实订单后才会传对应参数值。直接在卖家中心-应用接入调试页面直接调测租户同步接口时也会传。

7、应用同步里的公钥如何生成？

• 密钥长度>=3072bit，密钥格式为PKCS#8，不设置私钥密码，可以使用此工具(https://try8.cn/tool/cipher/rsa)生成。

8、应用接入调试-应用同步接口调试页面中客户端secret填什么？

• 客户端secret调测的时候随便写，然后页面填写公钥(去掉前后注释)；华为会在后台通过公钥对secret加密传给伙伴，伙伴接收到后根据对应的私钥来解密，解密结果为页面填写的值，则解密成功。（比如页面填写的test，加密后变成abs，伙伴最后能解密得到test就可以）。

9、接口调测验签失败是什么原因？

            1.客户先看下有没有成功接收到请求参数，如果没有的话需要先确认下生产地址url是否正确(参照上文第二点)；

            2.看下返回结果resultCode是不是六个0；返回结果body签名的key的获取是不是对的，计算签名值的时候不要key+timeStamp，只要key。body是json字符串格式：{"resultCode":"000000","resultMsg":"Success"}；

            3.看下返回方式，要把body放到response里：getWriter().print(body)；不要直接return一个对象；

            4.再看下返回内容是不是接口定义的返回字段。

10、接口调测提示服务不可达怎么办？

            1.确认接口地址是否正确，kit的五个接口地址我们会后台拼接子路径

            2.接收到请求参数后，日志查看下最终返回的是不是成功结果信息(应用同步接口需要看下是否私钥解密失败)

11、联营kit的五个接口什么时候会同步数据

1. 1. 卖家侧：
      1. 创建应用凭证的时候会调用{1.租户同步，应用同步，5.组织部门同步(全量)}三个接口给伙伴同步数据；
      2. 申请测试账号的时候调用{3.应用授权同步}接口将该账号相关信息同步给伙伴
   2. 买家侧：
      1. 应用绑定组织的时候会调用{1.租户同步，应用同步，5.组织部门同步(全量)}三个接口给伙伴同步数据；
      2. 给组织下账号授权该应用的时候调用{3.应用授权同步}接口将该账号相关信息同步给伙伴；
      3. 绑定组织后对组织下部门调整的时候会调用{4.组织部门同步(增量)}

12、一个应用对应的应用登录地址是唯一的吗？

• 应用登录地址是申请应用凭证时填写的，该地址是用户从统一登录平台登录成功后重定向到商家的地址，商家接收到请求后，调用token和userinfo接口来获取到登录用户信息。

• 如果不同的客户/租户使用相同域名登录，选择共享域名，一个应用对应的应用登录地址唯一；
• 如果不同的客户/租户使用不同域名登录，选择独立域名，一个应用对应多个应用登录地址。此时凭证申请时填写的应用登录地址是卖家测试账号单点登录时使用，每个买家订单对应的应用登录地址需要在应用凭证上给对应的订单配置对应的应用登录地址。

13、登录调测获取token接口返回失败怎么办？

• 获取token的接口地址是{domain_name}/api/v1/oauth2/token；该接口涉及到三个动态参数的本地查下：
  1. domain_name：域名，在租户同步接口中传递了该参数，通过tenant查到对应的值，本身带有https协议头
  2. clientId：应用同步接口中传递了该值，通过tenantId和appId到应用同步接口中查到对应的clientId；appId伙伴可以在应用凭证保存后重新编辑，应用登录地址后面拼上该appId，或者直接根据接收登录请求的地址本地映射appId
  3. clientSecret：逻辑同clientId，需要注意此时需要通过私钥解密后传明文

14、发布kit商品的时候选择应用不显示生产地址怎么办？

• 找到这个应用维护的生产地址，到[调试用例管理]菜单下查询该地址对应的调测成功的案例，找到后随便点一条最后的操作列的“调测”，然后无序的调测十个接口（除了应用同步接口复制公钥，其余参数都不改直接多次调测），需要接口都调测成功。最后检查发布的商品是包周期还是按次的还是都有，确认新购接口是不是都调测并保存了对应场景。

15、商品发布提示缺少SaaS调试示例接口怎么办？

• 确认商品发布是包周期还是按次的，在新购接口里是否有对应的调测记录。调测的接口不分先后调用顺序，要保证多次重复调用都返回成功。

16、买家应用绑定组织卖家侧收到租户同步接口失败提醒(查不到实例instanceId)怎么办？

• 先在卖家侧再调测下租户同步接口，创建一条测试应用凭证，都成功的话，和商家确认下新购接口同步的时候，需要根据orderId来查是否已有对应的instanceId，如果已有则不要再新生成一个替换已有的。（买家查询订单资源信息的时候也会调用新购接口，此时商家不要去更新该订单的instanceId）

17、一个商品可以有多个appId吗？

• 商品发布的时候只能选择一条应用数据，所以一个商品只能对应一个appId。

18、之前在云商店上架过SaaS商品，现在上架联营SaaS是在之前的商品上升级为联营SaaS还是需要重新创建一个商品？

• 上架联营SaaS商品不能在之前的商品上升级，需要重新创建一个新的商品。点击发布联营商品，支持两种模式创建商品：复制商品信息和创建商品信息。

19、怎么才能在应用授权同步接口里拿到授权账号的手机号邮箱等信息？

• 商家创建应用凭证后，需要在操作列先申请授权权限，因为涉及隐私信息，所以只能申请后等买家去选择授权哪些额外信息同步过来。如果创建的联营账号没有配置手机号和邮箱，自然授权同步时也没有手机号和邮箱。

20、授权账号角色有哪些，是否可设置？

• 当前账号角色只有user和admin两个角色，因为每家商家的角色范围可能存在不一致场景，所以我们这只是设置这两种角色。伙伴可以拿到这两种角色账号后根据自身业务分配权限等操作。需要注意的是我们这边不会限制买家必须两种角色都要创建。

21、SaaS应用不能即开即用，新购接口该怎么返回？

• 当SaaS应用不能即开即用时，需要走服务监管流程给买家开通租户，总体流程：

• 而新购接口需要在调测时“商品实例开通方式”选择“用户验收后开通”，且云商店会在用户购买商品时、商家点击开通交付时、用户点击确认验收时调用新购接口，而新购接口都需要返回结果码成功000000。

22、云商店统一登录页面登录成功回调服务商提供的单点登录接口时传递的tenant是tenantId还是tenantCode？

• 是tenantId，通过联营Kit接口同步到SaaS系统。

23、申请应用凭证时，应用登录地址是填SaaS系统的登录地址吗？

• 应用登录地址不是SaaS系统的登录地址，而是服务商开发的单点登录回调接口地址。

24、云商店统一登录页面登录成功回调服务商提供的单点登录接口时仅传递了tenant和code，能否传递其他参数？

• 可以传递固定参数，需要在填写应用登录地址时在地址末尾拼接参数，如：https://xxx.xxx.com/login?appid=12345

25、如何限制一个用户对同一SaaS商品多次购买？

• 限制一个用户对同一个SaaS商品多次购买可以从多个条件去判断，包括华为云账号标识(customerId)，IAM账号标识(userId)，如限制同一个华为云账号对同一SaaS商品多次购买，可以在新购接口中先判断对应的customerId是否已存在对应的实例信息。

26、新购接口请求参数中没有SaaS开租的必要参数怎么办？

• 可以借助新购接口中的扩展参数添加需要的参数，需要在卖家中心调测新购接口时添加扩展参数再调测，并在发布商品时配置添加过的扩展参数。

27、走服务监管流程还需要开发接口吗？

• 需要。联营SaaS商品的服务监管流程中在用户购买该商品、商家点击开通交付、用户点击确认验收时都会调用新购接口。订单开通完成后，后面的订单续费、过期、释放以及联营kit接口同步信息都是正常通过接口实现。

28、基础接口调测失败，失败信息中心包含：bodySign is empty.

• 卖家中心调测失败信息包含：bodySign is empty.时，表示该接口一定存在的一个问题是接口响应时没有添加响应头bodySign，或bodySign响应头格式错误。

29、卖家中心调测应用同步接口还白，提示：公钥错误

• 公钥需要按照要求生成：密钥长度>=3072bit,填充方式OAEP，并且在使用共要是需要去掉公钥收尾-----xxxx-----部分。

30、新购接口返回的账号能够通过云商店提供的统一登录页面登录SaaS系统吗？

• 新购返回的账号是由SaaS系统开通的账号，只能走SaaS系统的登录入口登录；云商店统一页面是用于用户创建并授权给SaaS系统的联营账号登录。

31、卖家中心调测接口报错000503，报错信息如下：

• 接口调测前接口生产地址的域名需要在“卖家中心-应用工具-生产地址管理”中认证。

32、卖家中心调测联营kit接口报错call id2b interface fail：

1. 如果基础接口调测成功，联营kit接口却失败，且接口日志显示也正常返回了，检查接口响应头Body-Sign中两个等号左右是否有空格，针对联营kit的五个接口是不能有空格的。
2. 可能是接口响应超时，检查接口业务逻辑是否产生了死循环等问题。