order_site/docs/行业电子凭证/解决方案/技术方案/1.基础技术.md

基础技术 更新时间：2025-03-26 阅读数：5722 本处介绍开放平台的基础协议和通用接入方式

1.环境说明 两套环境相互独立，数据不可相互使用

环境 环境地址 说明 线上环境 https://open.kwaixiaodian.com 线上环境可直接使用 线下环境 https://gw-merchant-staging.test.gifshow.com 测试环境调用需要提供出口IP，并联系快手对接人添加ip白名单 2.授权流程 2.1 如何获取token 首先需要拿到appkey、appsecret、signSecret信息，线下环境找快手提供，线上环境到“开放平台-控制台-应用中心-应用详情”查看，请求示例如下 https://gw-merchant-staging.test.gifshow.com/integration/virtual/topup/mobile/order/callback?access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJAErnBVtjx5FPdE0AITaSq4xlW6XaTOaV_McGinj-hFivkyxAw1SZ3i28bLEa6xP-C4UuKlRz6uh3lukYRLDcAdRoSeCxQKnQhAPTTL4YL0_NqmqD-IiApwDDKEL1wBW7EbWH0ZRDO3UUNSCxMwkuF7nb57Fn7AygFMAE&appkey=ks683702719562282620&method=integration.virtual.topup.mobile.order.callback&param=%7B%22orderId%22%3A%22100%22%2C%22businessTime%22%3A%222021-06-08T14%3A16%3A01%2B0800%22%2C%22mobile%22%3A%2215990013607%22%2C%22status%22%3A%22FAILED%22%2C%22amount%22%3A%225000%22%2C%22bizType%22%3A20%7D&signMethod=MD5&timestamp=1623132961782&version=1&sign=c091ca3414a9d6429a0fda47c383d202

注：如果回调失败需要以指数周期（1m、2m、4m、8m...）重试

注意：

测试环境需要把自己的出口ip给到快手，配置白名单，否则无权限访问。配置对接人：屈国庆，王哲，杨天问 测试环境和线上环境，是两套token，不可混用。测试token，如下方式获取。线上token通过上面sdk调用，有效期48h。 Token授权码：参考文档（2.2节 商家开发者角色） 授权一定要用店主的主账号来授权，否则token换取到的sellerId就是子账号的id 线上token验证：https://open.kwaixiaodian.com/commonTool/tokenAuth/accessToken?cateId=0&typeIndex=1，需要快手app扫描登录 测试环境获取token的步骤（参考文档（2.2节 商家开发者角色））：

测试环境：优先使用集成中心自己调试 线上环境：需要按照开放平台的授权文档，通过你的店铺由店主授权(不要用子账号授权)，然后用你的redirect_uri来接收code。 用授权码code换取长时令牌refreshToken以及访问令牌accessToken 示例：https://gw-merchant-staging.test.gifshow.com/oauth2/access_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=code&code=bab4f0378269db7a1603de9d5a381615d7d2c451ffbb32f8ede78ac8f05b6171f7d4eb8c

用长时令牌refreshToken刷新访问令牌accessToken 示例： https://gw-merchant-staging.test.gifshow.com/oauth2/refresh_token?app_id=ks683702719562282620&app_secret=zSCiWmGOk_diMCU9k3zHcg&grant_type=refresh_token&refresh_token=ChJvYXV0aC5yZWZyZXNoVG9rZW4SkAGpBE83BKP9TeiwbEP1-IIQL2G08s8rU-OETIzfs5wFN2HeZgUaR_mfGjKHjHzfV-sicHG4IZmxVKlxQhdAZIdf01AR51ZtPN7sHY3eeW6RMnx8LPKo92V1yk-GnkXiiPMWpn9Vmhq0dk_U_aKh5Jwg7mMySO8IEDoz-fPk9Rc2rjUK3inqxNd7rqTQ9fz316oaEsFIUEDt4EyD090nGWRnwQ5g3SIgY-ctBM_4jrFXxBA9EF1jMaP6as57lNYIyOZf9Qlqq64oBTAB

后面就可以一直用第三步来刷新accessToken

3.签名算法 3.1 协议 https协议，支持GET/POST，调用地址、appkey、signSecret由快手提供，返回结果为json字符串。

3.2 签名 官方签名说明

快手电商开放平台的所有开放API调用都需要进行加签，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。当前平台支持的签名算法为MD5(signMethod=MD5)

下面将详细介绍签名流程：

对所有API系统参数和请求参数(不包括sign参数和byte[]类型的参数），根据参数名称进行字典顺序排序；

排序前的顺序是：appkey=ks123，version=1，method=open.xxx.xxx，signMethod=MD5，access_token=xxxx，timestamp=1583271919000，param={"title":"短袖", "relItemId":123456, "categoryId":12}

排序后的顺序是：appkey=ks123&param={"categoryId":12,"relItemId":123456,"title":"短袖"}&signMethod=MD5&timestamp=1583271919000&version=1&signSecret=abc

保留=符号，用&符号将多个参数及其值组装在一起，根据上面的示例得到的排序结果为：access_token=xxx&appkey=ks123&method=open.xxx.xxx&param={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5&timestamp=1583271919000&version=1

排序好参数后，在末尾加入signSecret（在应用创建审核通过后由平台分配，在“应用中心-应用列表-应用详情”中可见）进行对应算法的签名计算

MD5(access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx&param={"title":"短袖", "relItemId":123456, "categoryId":12}&signMethod=MD5&timestamp=1583271919000&version=1&signSecret=xxxxxx)=sign

签名加好后，将sign添加到请求参数中，并对param内容进行encode（双引号"和冒号:也需要encode），这里注意请求参数里面是不包括signSecret的，signSecret只是作为加签因子用于签名sign的计算，

所以千万不要将signSecret当作请求参数传输，请求参数内容见第3点API调用参数说明的表格内容，请求url样例：

https://open.kwaixiaodian.com/open/xxx/xxx?access_token=xxx&appkey=ks123&method=open.xxx.xxx.xxx&param=%7B%22title%22%3A%22%E7%9F%AD%E8%A2%96%22%2C%20%22relItemId%22%3A123456%2C%20%22categoryId%22%3A12%7D&version=1&signMethod=MD5&timestamp=1583271919000&sign=af2d80958e77e17f1d973003b7b7aec2 说明：param是json对象，需要排序

4.API调用 确认完成了授权流程后进行API的调用测试，内容详情可见《API调用说明》，也可使用平台提供的API测试工具测试