友好速搭 -- 使用手册

友好速搭

使用手册 > 后台使用 > 开放 API > 获取授权 > 开放应用授权
开放 API
使用说明 获取授权 全部 API 特殊 API 开放功能

开放应用授权

开放应用,是指通过友好速搭审核,进入应用市场的应用。

要开发开放应用,开发者需要拥有合作伙伴帐号,并通过企业资质认证。

开放应用的 OAuth2 授权过程,参照:Authorization Code

授权流程示例: #Authorization Code

在友好速搭的 OAuth2 实现中,上图的组成部分对应如下:

  • Client:开放应用
  • Resource Owner:友好速搭的用户
  • Authorization Server:地址是https://apps.youhaosuda.com/oauth2/
  • Resource Server:地址是https://api.youhaosuda.com/v1/...

下面介绍友好速搭 OAuth2 授权过程:

第一步:获取应用凭证

在应用创建后,就能获取对应的 App Key 和 App Secret,要做好保密工作,防止泄露这两个值,尤其是 App Secret。

第二步:用户安装应用

在用户在应用市场,选择了应用,点击安装时,友好速搭会向应用发起请求,请求的URL,是应用在创建时填写的 callback 网址,完整的请求 URL 示例如下: http://example.org/some/redirect/uri?shop_key={shop_key}&account_id={account_id}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括:

  • shop_key:店铺唯一标识
  • account_id:用户的唯一标志
  • time_stamp:时间戳
  • hmac:安全验证码,参见跳转请求安全验证

第三步:请求授权

应用在验证来自友好速搭的请求后,需再次跳转到友好速搭,来获取用户授权,跳转网址示例: https://apps.youhaosuda.com/oauth2/authorize?response_type={response_type}&client_id={client_id}&shop_key={shop_key}&scope={scope}&state={state}&redirect_uri={redirect_uri} 网址中参数包括如下:

  • response_type:必须,值必须为code
  • client_id:必须,值为应用的 App Key
  • shop_key:必须,上一步网址中的shop_key
  • scope:必须,多个 API 权限,间隔
  • state:可选,若包含此参数,则在用户授权后跳转,将这个参数返回
  • redirect_uri:可选,若不带此参数,将使用应用创建时填写的回调网址

第四步:确认安装

当用户确认授权后,友好速搭将会再次将用户跳转到应用,跳转网址如下: https://example.org/some/redirect/uri?code={code}&shop_key={shop_key}&account_id={account_id}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括:

  • code:授权码(Authorization Code)
  • shop_key:上一步网址中的shop_key
  • account_id:用户的唯一标志
  • time_stamp:时间戳
  • hmac:安全验证码,参见跳转请求安全验证

应用在收到授权码后,可以发起POST请求,来获取 Access Token:

POST https://apps.youhaosuda.com/oauth2/token

POST请求中,需包含如下 form-data (application/x-www-form-urlencoded)参数:

  • grant_type:必须,值必须为authorization_code
  • code:必须,值为上述的授权码
  • client_id:必须,值为应用的 App Key
  • redirect_uri:必须,且必须是请求授权中使用的参数:redirect_uri

若请求合法,服务器将返回应用操作 API 的 access token:

{
  "token": "f85632530bf277ec9ac6f649fc327f17"
}

这个 access token 不会过期,应用需要持久存储这个值,并确保不会泄露。

第五步:使用开放 API

应用在获取API的 access token 后,就可以访问权限范围内的 API。在访问 API 的请求头中,加入X-API-ACCESS-TOKEN字段,值为上步返回的 access token。

友好速搭 API 权限

对部分 API 有权限限制,如下表:

权限名称 资源对象
read_basic,write_basic Shop, Metafield, Account, Country, Province, City, District
read_content,write_content Page, Redirect, Webhook
read_themes,write_themes Theme, Asset
read_products,write_products Product, ProductVariant, ProductImage
read_customers,write_customers Customer, CustomerAddress
read_orders,write_orders Order, Payment, PaymentMehod, Shipment, ShipmentSupplier
read_script_tags,write_script_tags ScriptTag

当需要操作上表资源对象时,需要在请求授权scope参数中,包含指定权限。 未在上表列出的资源对象,无权限限制。

当应用需要更新已安装应用的scope时,只需重新跳转到请求授权来通知已安装应用,再次确认授权来更新scope值。

应用删除通知

用户在店铺后台删除应用时,友好速搭会使用 webhook 方式来通知第三方应用,通知地址为创建应用时填写的 callback 地址,完整的请求 URL 示例如下: http://example.org/some/redirect/uri?event=delete&shop_key={shop_key}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括:

  • event:通知事件类型,当前操作为delete
  • shop_key:应用授权中的shop_key
  • time_stamp:时间戳
  • hmac:安全验证码,参见跳转请求安全验证

更新 App Secret

应用可以在合作伙伴后台,应用详细页面重新生成 App Secret,此时友好速搭将分发一个新的 App Secret给应用使用,此时所有的跳转 hmac的签名将使用新的 Secret 进行加密,应用需及时将旧的 Secret 进行替换,以防用户在使用过程中出现问题。

更新 Access Token

应用可以在合作伙伴后台,应用详细页面生成 Refresh Token 来手动触发更新店铺访问 API 的 Access Token。Refresh Token的时效为1小时。 应用生成 Refresh Token,可以发起POST请求,来获取来刷新访问 API的 Access Token:

POST https://apps.youhaosuda.com/oauth2/refresh_token

POST请求中,需包含如下 form-data (application/x-www-form-urlencoded)参数:

  • refresh_token:必须,生成的 Refresh Token
  • client_id:必须,值为应用的 App Key
  • shop_key:需要刷新 access token 的店铺唯一标识

若请求合法,服务器将返回新的访问 API 的 access token:

{
  "token": "f85632530bf277ec9ac6f649fc327f17"
}

跳转请求安全验证

从友好速搭跳转到应用的请求,在参数中都包含hmac,应用可以验证这个字段,来确认请求是否来源自友好速搭。

以下示例如果计算hmac,在不同场景的跳转中,所带参数会有区别,除了hmac以外的参数,都需参与计算。

例如友好速搭返回授权码的请求参数如下:

"shop_key=a94a110d86d2452eb3e2af4cfb8a3828&code=a84a110d86d2452eb3e2af4cfb8a3828&account_id=1&time_stamp=2013-08-27T13:58:35Z&hmac=a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"

将请求中的所有参数,转换成如下的字典:

{  
  "shop_key": "a94a110d86d2452eb3e2af4cfb8a3828",  
  "code": "a84a110d86d2452eb3e2af4cfb8a3828",  
  "account_id": "1",
  "time_stamp": "2013-08-27T13:58:35Z",    
  "hmac": "a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"
}

将上面字典结构中,hmac字段剔除,得到下面的结构:

{ 
  "shop_key": "a94a110d86d2452eb3e2af4cfb8a3828",  
  "code": "a84a110d86d2452eb3e2af4cfb8a3828",  
  "account_id": "1",
  "time_stamp": "2013-08-27T13:58:35Z"
}

将上面的字典,按照键值正序排列,组成字符串:

"account_id=1&code=a84a110d86d2452eb3e2af4cfb8a3828&shop_key=a94a110d86d2452eb3e2af4cfb8a3828&time_stamp=2013-08-27T13:58:35Z"

最后,将上面的字符串,应用密钥,通过 HMAC-SHA256 加密,Ruby 代码示例如下:

digest = OpenSSL::Digest.new('sha256')
# 仅作示例,应使用应用的Secret
secret = "hush"
message = "account_id=1&code=a84a110d86d2452eb3e2af4cfb8a3828&shop_key=a94a110d86d2452eb3e2af4cfb8a3828&time_stamp=2013-08-27T13:58:35Z"
digest = OpenSSL::HMAC.hexdigest(digest, secret, message)
# 判断结果是否相同
digest == "a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"

计算得出的结果,如和请求参数中的hmac相同,则说明请求确实来自友好速搭。

获取授权时发生错误,参见 OAuth2 错误码。 使用 API 发生错误时,请参见 API 错误码

以上内容仍未解决您的问题? 联系在线客服
免费领取15天试用
立即注册
联系客服
微信咨询
微信二维码

领取免费试用资格

姓名 *

电话 *

公司名称

所在地区

意向产品

提交

提交成功

你好, XXX女士/先生 ,你的需求已提交成功,后续会有专门的客户经理与你电话联系。谢谢!