一、接口鉴权文档

1. 应用场景介绍
薄盒开放平台的 API 域名是:,用户在调用薄盒开放平台接口时,需要首先完成鉴权认证。正式环境接口域名上线前会以邮件方式发送相关信息。
接口调用时,需要提供用户身份信息供鉴权,用户需要提前向薄盒申请以获取商户的 secretId 和 secretKey。
2. 具体接口介绍
调用鉴权接口生成鉴权需要的签名数据是调用薄盒开放平台API接口的第一步,相当于创建了一个登录凭证,其它的业务API接口,都需要依赖于签名数据来鉴权调用者身份。
因此开发者,在使用业务接口前,要明确签名数据的颁发来源,使用正确的签名数据。
请求方式: GET
请求地址:/api/v1/auth/getsigndata?secreteId={secretId}&secretKey={secretKey}
此处${secretId} 和 ${secretKey},为需要替换的变量,根据实际的值进行更新。其它接口也采用相同的参数标注,不再说明。
请求参数:
参数 类型 必填项 描述
secretId string Y 注册用户时生成的 secretId
secretKey string Y 注册用户时生成的 secretKey
返回结果:
            {
                "code":200,
                "msg":"成功",
                "data":{
                    "signature":"",
                    "signatureTime":11111,
                    "nonce":"sdfafsdf",
                    "expiresIn":3600
                }
            }
        
data对象(生成各项签名数据):
字段名 描述
signature 签名后的数据
signatureTime 时间戳
nonce 随机数
expiresIn 过期时间,默认3600秒,1小时
注意事项:
开发者需要缓存签名数据,用于后续业务接口的调用(注意:不能频繁调用getsigndata接口,否则会受到频率拦截)。当签名数据失效或过期时,需要重新获取。
data的有效期通过返回的expiresIn属性来传达,正常情况下为3600秒(1小时),有效期内重复获取将导致上次获取的signData失效。开放平台会保证在刷新signData过程的短时间内(默认2分钟),新老signData都可用,这保证了第三方业务的平滑过渡;
薄盒开放平台可能会出于运营需要,提前使signData失效,开发者应实现signData失效时重新获取的逻辑。
签名数据使用说明
在调用各业务API时需要将获取的签名数据等相关信息设置到到 HTTP 请求的 header 中,Content-Type 需要设置为:application/json;charset=utf-8。
放到 Header 中的字段清单如下:
字段名 类型 描述
secretId string 密钥ID
signatureTime string 签名时间
signature string 签名
nonce int 随机数
cloudTraceId string 请求追踪id,建议采用UUID字符串
3. 错误码
错误码 描述
140001 请求路径不存在
140002 该服务暂时不可用
140003 签名过期
140004 签名不匹配
140005 secreId 不存在
140006 secreId 参数丢失
140007 signatureTime 参数丢失
140008 signature 参数丢失
140009 nonce 参数丢失
140010 签名时间格式错误
140020 服务器繁忙
140030 重复请求
65535 系统错误