阿里云市场自动交付接入方案

简介

本文档描述了 SaaS 应用接入到云市场所须实现的接口定义，服务商通过提供以下接口，即可获得商品购买成功的信息，并将成功信息返回给云市场展示给用户。

术语信息

文中涉及相关术语解释如下：

• 发货 URL： 由服务商开发，用于接受云市场实例相关消息的地址。
• Token：由服务商提供，用于校验发货 URL 有效性。
• openId：当服务商的应用接入腾讯云开放平台后，可获得的腾讯云用户的唯一标识。

准备工作

在一个 SaaS 商品正式通过审核上架前，服务商需要进行以下准备工作：

1. 云市场发货接口开发（必选）。
2. 控制台的参数配置（必选）。
3. 接入腾讯云 OAuth（可选）。

接口开发

接口要求

在进行接口开发前，请了解以下相关要求：

服务商在控制台配置发货接口 URL 和 Token 后，云市场会以 URL PARAMS（GET 参数）的方式添加到接口 URL 上，携带的参数如下：

接口调试规则

• 接口创建成功后需要进行对应的调试才可以发布接口，上架 SaaS 交付类商品。
• 在服务商管理控制台的【在线接口调试】页面进行对应的接口调试，发布接口前必须将“创建实例”、“续费实例”、“实例过期”、“实例销毁”等接口调试成功，“实例配置变更”可选择性进行调试。
• “创建实例”、“续费实例”、“实例过期”、“实例销毁”这个四个接口是必须调试通过的，如果未调试通过会影响商品正常的销售，如果商品没有试用版，则可跳过“实例配置变更”接口调试。

签名规则

服务商通过对 signature 进行校验（校验方式如下）。加密/校验流程如下：

1. 判断 timestamp 是否已经超时（签名推荐超时为30s，免登校验推荐为120s）。
2. 将 Token、timestamp、eventId 三个参数进行字典序排序。
3. 将三个参数字符串，拼接成一个字符串进行 SHA256 加密。
4. 服务商将加密后的字符串与 signature 对比即可。

检验 signature 的 PHP 示例代码：

function checkSignature($signature, $token, $timestamp, $eventId)
{
  $currentTimestamp = time();
  if ($currentTimestamp - $timestamp > 30) {
    return false;
  }
  $timestamp = (string)$timestamp;
  $eventId = (string)$eventId;
  $params = array($token, $timestamp, $eventId);
  sort($params, SORT_STRING);
  $str = implode('', $params);
  $requestSignature = hash('sha256', $str);
  return $signature === $requestSignature;
}

接口验证过程

身份校验接口

• 接口名：verifyInterface。
• 接口说明：用户在 云市场服务商管理控制台 更改发货 URL 和 Token 时，后台会调用接口 URL 对 Token 进行实时校验，校验通过才可以设置成功。

请求参数说明

响应参数说明

请求示例

curl -X POST -H 'Content-Type: application/json' 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"verifyInterface","echoback":"Albert Einstein"}'

响应示例

{"echoback": "Albert Einstein"}

实例创建通知接口

• 接口名：createInstance。
• 接口说明：用户购买商品并支付后，云市场将通过实例创建通知接口发送信息至发货 URL。

请求参数说明

响应参数说明

请求示例

curl -X POST -H 'Content-Type: application/json' 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"createInstance","orderId":"20170109199524","accountId":"123545678"," openId ":"xz_D4XL_u7hKY5zt","productId":1024,"requestId":"fab8a029-22fa-41b1-ac08-5cdde878ed04","productInfo":{"productName":"云服务市场测试商品","isTrial":"false","spec":"普通版","timeSpan":2,"timeUnit":"m"}}'

响应示例

{"signId": "36441d902ba", "appInfo": {"website":"http://www.example.com", "authUrl": "http://www.example.com/oauth/login"},"additionalInfo":[{"name":"注意","value":"这是一条注意"},{"name":"说明","value":"这是说明"}]}

实例续费通知接口

接口名：renewInstance。
接口说明：用户续费商品后，云市场将通过实例续费通知接口发送消息至发货 URL。该接口需要服务商立即返回响应。

请求参数说明

响应参数说明

请求示例

curl -X POST -H 'Content-Type: application/json' 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"renewInstance","orderId":"20170109199524","accountId":"123545678"," openId ":"xz_D4XL_u7hKY5zt","productId":1024,"requestId":"3c45e1f3-22b9-4346-9898-4467d3aea000","signId":"kjsadkjhdskjh3k"," instanceExpireTime":"2017-02-09 19:59:59"}'

响应示例

{"success":"true"}

实例配置变更通知接口

• 接口名：modifyInstance。
• 接口说明：用户将实例从试用版转为正式版时，云市场将通过实例配置变更通知接口发送消息至发货 URL。

注意：

如果用户仅是配置变更，则参数中只会包含实例的新规格，而不会包含实例价格参数。

请求参数说明

响应参数说明

请求示例

curl -X POST -H 'Content-Type: application/json' 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"modifyInstance","orderId":"20170109199524","accountId":"123545678"," openId ":"xz_D4XL_u7hKY5zt","productId":1024,"requestId":"1d8326b2-9a94-4bf3-91ce-c7a94add99d3","signId":"kjsadkjhdskjh3k","spec":"  高级版","timeSpan":2,"timeUnit":"m"," instanceExpireTime":"2017-02-09 19:59:59" }'

响应示例

{"success":"true"}

实例过期通知接口

• 接口名：expireInstance。
• 接口说明：实例到期后（用户最后操作后的 instanceExpireTime ），云市场将通过实例续费通知接口发送消息至发货 URL。

请求参数说明

响应参数规范

请求示例

curl -X POST 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"expireInstance","accountId":"123545678"," openId ":"xz_D4XL_u7hKY5zt","productId":1024,"requestId":"ea372177-809d-4722-91d0-d6df4edf7bc9","signId":"kjsadkjhdskjh3k"}'

响应示例

{"success":"true"}

实例销毁通知接口

• 接口名：destroyInstance。
• 接口说明：用户退款、实例到期后的七天内如果用户没有进行续费操作，云市场会销毁该实例并通过该接口发送消息至发货 URL。

请求参数说明

响应参数说明

请求示例

curl -X POST 'http://isv/interface?signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"destroyInstance","orderId":"20170109199524","accountId":"123545678"," OpenID ":"xz_D4XL_u7hKY5zt","productId":1024,"requestId":"80b75030-6571-46a8-87ef-5b414f66dc39","signId":"kjsadkjhdskjh3k"}'

响应示例

{"success":"true"}

参数配置

在完成了相关开发后，服务商可登录 云市场服务商管理控制台，在【开发配置】> 【SaaS 接入设置】页面中，填写相关信息：

注意：

为保证数据的安全，发货 URL 必须为 HTTPS 协议，且发货 URL 不能包含查询字符串。如果配置保存失败，请检查 verifyInterface 接口是否正常。

在线接口调试

在接口开发过程中，您可以登录 云市场服务商管理控制台，在【开发配置】 > 【在线接口调试】中，可使用在线调试功能，用于模拟各种类型的发货行为。

注意：

此为调试环境，请勿使用正式环境的接口 URL 或数据库对接。

接入腾讯云 OAuth

为了提升用户使用 SaaS 产品的体验，建议服务商将应用接入腾讯云开放平台 OAuth ，实现用户在腾讯云控制台登录后，直接免登访问 SaaS 应用管理后台。

申请接入开放平台

由于腾讯云暂未开放申请腾讯云开放平台的入口，因此申请者需要先发邮件至：mqcloud@tencent.com 协助开通。邮件内容如下：

• 腾讯云账户的 ID：您的账号 ID 可在 腾讯云控制台 总览页面右上角处查看。
• 平台名称：平台名称会展示在授权页面。
• 平台 Logo：建议尺寸：260 x 48，PNG 格式，Logo 将会展示在授权页面中。
• 平台官网地址：您可以跳转到的第三方平台官网，即服务商的 SaaS 地址。
• 平台回调地址：去掉 HTTP[s] 的域名部分，不能只是顶级域名，例如可以为api.example.com，而不允许为 example.com。

申请成功后您将会得到如下的信息：

• AppId：第三方平台唯一标识。
• AppSecretId/AppSecretKey ：用来请求腾讯云 API 时的密钥对。
• EncryKey：用来校验回调地址中带入的 code 参数。

OAuth 接入说明

账号打通
云市场在发货通知中加入用户在腾讯云的标识 OpenID （对于不同服务商用户 OpenID 不同），服务商在获取到 OpenID 之后需要首先要查询该用户是否已与本地系统某个账户绑定，如果已经绑定，则直接处理发货逻辑；若未绑定，则应该在本地系统生成一个账号并与 OpenID 绑定。

免登校验
服务商对于发货的响应数据中应该返回一个authUrl，该 URL 最终会展示给用户。用户单击该 URL 后，服务商应该让用户登录到控制台以进行资源相关操作。

授权流程说明
服务商授权过程如下：

1. 用户单击authUrl（假设为：http://example.com/qcloud/auth） 后，若未检测到用户登录，则跳转（302跳转）到：https://www.cloud.tencent.com/open/authorize?scope=login&app_id=123456789012&redirect_url=https%3A%2F%2Fexample.com%2Fapi%2Foauth%2Fqcloud%2Fcallback&state=1234。 其中app_id为申请 OAuth 后获得的第三方平台唯一标识，redirect_url为提交腾讯云开放平台的平台回调地址域名。
2. 用户在腾讯云开放平台页面进行登录并且授权；
3. 页面跳转回第三方网站地址redirect_url，并且带上参数 code 和 signature ，类似：https://example.com/api/oauth/qcloud/callback?code=04f82b0d6fcfc0c2d967d808e6010bd8&signature=eafc9653bd5c17c6adea55bb516ba8b9&state=123， 其中 signature = md5(code+EncryKey)
   

   说明：

   • 为了防止暴力破解，signature 参数对 code 的合法性做了一个校验。
   • 该code一次性有效，并且有效期为6分钟。

4. 获取 code 并且校验合法之后，调用 code 校验接口，获取用户的以下信息：
   • userOpenId：用户在该第三方平台下的身份唯一标识。userOpenId即为用户在腾讯云的OpenID（不同第三方平台获取的标识不同）。
   • userUnionId：如果同一个腾讯云账户有多个第三方平台，用户在这些第三方平台的 userUnionId 一致。
   • userAccessToken：用户访问 Token。
   • expiresAt：用户访问 Token 过期时间（时间戳，当前时间 + 2小时）。
   • userRefreshToken：刷新 Token ，有效期为60天。

code 校验接口

1. 接口描述

• 接口请求域名：open.tencentcloudapi.com
• 接口说明：用于获取用户第三方开放平台的 access token

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。该接口使用分配给第三方平台的密钥调用。

3. 输出参数

4. 示例

• 输入示例：
  https://open.tencentcloudapi.com/?Action=GetUserAccessToken
  &UserAuthCode=testCode
  &<公共请求参数>

• 输出示例：
  {
    "Response": {
        "AppId": "10******99",
        "UserOpenId": "391f920b807ecbaa38f7e77ef5260cd4",
        "UserUnionId": "438344612f5e181dbb76d2fcf2634a7b",
        "UserAccessToken": "a649830709416d07be8f0dba1c7675ce",
        "ExpiresAt": 1581670707,
        "UserRefreshToken": "607202ece53c20a8ad91fa3512fa8ac7",
        "Scope": "login",
        "RequestId": "5bc7a27e-ba54-4b68-b37e-aaee60a2c5e2"
    }
  }