API文档

1 概述

数位云场景识别 API v3接口用于查询用户的场景位置、标签等 POI数据，用户可以使用 Java、Golang、C#、 C++、Python 等开发语言发送请求且接收 JSON 格式数据。

1.1 接入流程

在数位云菜单“我的应用”创建一个应用后，即可查看到AppID和AppKey，与数位商务同事取得联系，激活AppID和AppKey；
使用AppID和AppKey接入API进行测试，提供单次和批量两种请求接口，接入步骤如下：

1) 请求头：按格式设置请求头；

2) 请求体：按请求参数字段和示例的格式设置请求体；

3) 签名：按签名规则计算签名，并给签名参数 sign 字段赋值；

4) 加密：按加解密规则对请求体加密；

5) 发送请求：将请求头和加密后的请求体发送至接口地址即可获得加密后的响应；

6) 解密：将加密后的响应按加解密规则解密即可获得明文场景识别结果；

7) 接入成功标志：响应中 retCode 字段值为0或201001；

8) 业务码：详细的retCode 说明可参考业务码说明；

9) 同时也提供多种语言API接入SDK，可简化接入过程，详情参考SDK中的README.md。
成功接入API后，数位商务同事将提供场景开始测试；
测试通过后协商正式上线。

2 接口说明

2.1 场景识别单次请求接口

接口地址：https://api.jjfinder.com/v3/scene/api

通过POST方式提交数据到API需要使用测试AppID作为唯一标识，使用测试AppKey进行签名。

注意：请求接口的域名及AppID、AppKey请以商务邮件为准，正式上线时请使用生产的配置。

2.1.1接口参数说明

2.1.1.1设置请求头

在请求头中添加Authorization，值为场景识别单次请求接口 2.1.1.2 中参数内容拼接，格式如下：

t=%d;a=%s;

生成Authorization样例代码如下：

  public String authorization(){      
          return String.format("t=%d;a=%s;",timestamp, appId);  }

添加请求头样例代码：

conn.setRequestProperty("Content-Type","application/json");
conn.setRequestProperty("Authorization",authorization);

2.1.1.2 请求参数

定位请求必须参数：

序号	字段	数据类型	是否签名	含义
1	timestamp	Long	是	请求时间戳(ms)
2	appId	String	是	appId，由数位分配
3	oid	String	是	唯一标识 Android设备标识为IMEI号 iOS设备标识为IDFA
4	oidType	String	是	唯一标识符类型（数位最终值为小写保存） 1：IMEI 4：iOS设备IDFA
5	mac	String	是	mac地址/或者iOS IDFV
6	macType	String	是	3：MAC地址（默认缺省，可以不传）
7	networkMode	String	是	连网方式 0：unknown 1：WiFi 2：2G 3：3G 4：4G 5：5G
8	ssidEncode	Integer	是	ssid是否做base64加密(1加密0不加密)
9	osType	Integer	是	操作系统类型： 0：未知 1：Android 手机 2：IOS 手机 3：Android TV 4：苹果TV 5：Android 手表 6：IOS 手表 7：Android 平板 8：IOS 平板 9：车载
10	appChannel	Integer	是	流量来源的应用类型: 0：未知 1：app 2：微信小程序 3：支付宝小程序 4：百度小程序 5：头条小程序 6：快应用 7：设备操作系统集成 8：其他
11	passthrough	String	是	透传字段
12	sign	String	否	签名
13	signals	List	否	WiFi信号列表
13.1	bssid	String	否	信号bssid
13.2	rssi	Integer	否	信号强度（dBm）
13.3	ssid	String	否	信号名称
13.4	connectState	Integer	否	是否为连接信号(1连接，默认为null)
13.5	timestamp	Long	否	采集时间戳
13.6	band	Integer	否	频段（1:2.4G，2:5G）
13.7	channel	Integer	否	信道

连接基站信息：每次定位

14	baseStationList	List	否	基站信息列表，根据运营商情况填写具备的参数值
14.1	type	Integer	否	所属网络 0:未知, 1:GSM,2: CDMA,3:WCDMA ,4:LTE
14.2	mcc	Integer	否	移动国家代码 (GSM,CDMA,WCDMA,LTE)
14.3	mnc	Integer	否	移动网络号码 (GSM,CDMA,WCDMA,LTE)
14.4	lac	Integer	否	位置区域码 (GSM,WCDMA)
14.5	cid	Integer	否	UMTS小区身份(GSM,WCDMA)
14.6	tac	Integer	否	跟踪区域码 (LTE)
14.7	ci	Integer	否	小区标识(LTE)
14.8	pci	Integer	否	物理小区id (LTE)
14.9	psc	Integer	否	WCDMA主扰码(WCDMA)
14.10	sid	Integer	否	CDMA System ID (CDMA)
14.11	nid	Integer	否	Network ID (CDMA)
14.12	bid	Integer	否	Base Station ID (CDMA)
14.13	dBm	Integer	否	1毫瓦分贝数 (GSM,CDMA,WCDMA,LTE)
14.14	asuLevel	Integer	否	Asu信号单元 (GSM,CDMA,WCDMA,LTE)
14.15	level	Integer	否	信号格(GSM,CDMA,WCDMA,LTE)
14.16	timestamp	Long	否	采集时间戳
14.17	register	Integer	否	是否已注册
14.18	baseStationType	String	否	基站实例类型
14.19	earfcn	Integer	否	Android N 新增，绝对射频频道号(LTE)
14.20	bandWidth	Integer	否	小区带宽(LTE)
14.21	arfcn	Integer	否	Android N 新增，绝对射频频道号(GSM)
14.22	bsic	Integer	否	Android N 新增，基站识别码，物理小区id(GSM)
14.23	uarfcn	Integer	否	Android N 新增，绝对射频频道号(WCDMA)
14.24	rsrp	Integer	否	信号接收强度(LTE)
14.25	rsrq	Integer	否	信号接收质量(LTE)
14.26	rssnr	Integer	否	信噪比(LTE)
14.27	cqi	Integer	否	信道质量指标(LTE)
14.28	timingAdvance	Integer	否	时间提前量(GSM,LTE)
14.29	csiRsrp	Integer	否	csi信号接收强度(NR)
14.30	csiRsrq	Integer	否	csi信号接收质量(NR)
14.31	csiSinr	Integer	否	csi信噪比(NR)
14.32	ssRsrp	Integer	否	ss信号接收强度(NR)
14.33	ssRsrq	Integer	否	ss信号接收质量(NR)
14.34	ssSinr	Integer	否	ss信噪比(NR)
14.35	nci	Long	否	小区标识(NR)
14.36	nrarfcn	Integer	否	绝对射频频道号(NR)
14.37	bitErrorRate	Integer	否	误码率(GSM，WCDMA)
14.38	mCdmaDbm	Integer	否	电信2G Dbm
14.39	mCdmaEcio	Integer	否	电信2G Ec/Io)
14.40	mEvdoDbm	Integer	否	电信3G Dbm
14.41	mEvdoEcio	Integer	否	电信3G Ec/Io
14.42	mEvdoSnr	Integer	否	电信3G 信噪比

设备信息发送周期：每月首次

15	deviceInfo	Map	否	设备信息
15.1	imei	String	否	Android 系统的设备号
15.2	idfa	String	否	仅iOS 6.0以上系统的IDFA，如 4CFD11F0-09D0-4BF3-91CE-D50600BD0E64
15.3	andid	String	否	用户终端的Android ID，如 9774d56d682e549c
15.4	device	String	否	设备品牌和型号，如honor v8、Sumsang S6
15.5	osv	String	否	操作系统版本，如 iPhone 8.1.2 的参数填写 8.1.2
15.6	carrier	String	否	运营商 0：unknown 1：CMCC 2：CUCC 3：CTCC
15.7	imsi	String	否	国际移动用户识别码，如 460030912121001
15.8	romInfo	String	否	Rom信息, 如：Meizu/FLYME/Flyme+6.2.0.2A
15.9	width	Float	否	屏幕宽度
15.10	height	Float	否	屏幕高度

应用列表发送周期：每星期首次

16	appInfo	List	否	手机安装app信息
16.1	applicationId	String	否	应用的 PackageName
16.2	versionCode	Integer	否	版本号
16.3	versionName	String	否	版本号
16.4	firstTime	Long	否	首次安装时间ms
16.5	lastTime	Long	否	最新更新时间ms
16.6	totalTime	Long	否	App前台使用时长

蓝牙列表发送周期：每次定位

17	bluetoothInfo	List	否	周边蓝牙设备信息
17.1	name	String	否	设备名称
17.2	mac	String	否	MAC地址，去除冒号分隔符保持小写
17.3	rssi	Integer	否	信号强度（dBm）
17.4	ibeaconUUID	String	否	设备UUID
17.5	ibeaconMajorId	Integer	否	设备MajorId
17.6	ibeaconMinorId	Integer	否	设备MinorId
17.7	timestamp	Long	否	采集时间戳

磁场信息发送周期：每次定位

18	magneticInfo	Map	否	移动设备所在位置的磁场信息
18.1	magX	Double	否	X轴方向的磁感应强度
18.2	magY	Double	否	Y轴方向的磁感应强度
18.3	magZ	Double	否	Z轴方向的磁感应强度
18.4	timestamp	Long	否	采集时间戳
18.5	sensorName	String	否	传感器名称
18.6	sensorVendor	String	否	传感器供应商
18.7	sensorVersion	String	否	传感器版本

姿态方向信息发送周期：每次定位

19	orientationInfo	Map	否	移动设备的姿态方向信息
19.1	pitch	Double	否	俯仰角，绕X轴产生的角
19.2	roll	Double	否	翻转角，绕Y轴产生的角
19.3	azimuth	Double	否	方向角，绕Z轴产生的角
19.4	timestamp	Long	否	采集时间戳
19.5	sensorName	String	否	传感器名称
19.6	sensorVendor	String	否	传感器供应商
19.7	sensorVersion	String	否	传感器版本

光强信息发送周期：每次定位

20	lightInfo	Map	否	移动设备获取到的光强信息
20.1	lux	Double	否	光强
20.2	timestamp	Long	否	采集时间戳
20.3	sensorName	String	否	传感器名称
20.4	sensorVendor	String	否	传感器供应商
20.5	sensorVersion	String	否	传感器版本

GPS信息发送周期：每次定位

21	gpsInfo	Map	否	GPS定位相关信息
21.1	satelliteInfo	List	否	卫星信息
21.1.1	mHasEphemeris	Boolean	否	GPS引擎是否有卫星星历(有则返回true)
21.1.2	mHasAlmanac	Boolean	否	GPS引擎是否有近似轨道信息(有则返回true)
21.1.3	mUsedInFix	Boolean	否	卫星是否被GPS引擎用于计算最近位置(是则返回true)
21.1.4	mPrn	Integer	否	伪随机噪声码,是一个具有一定周期的取值0和1的离散符号串,它具有类似于白噪声的自相关函数
21.1.5	mSnr	Double	否	卫星的信噪比 (单位：db)
21.1.6	mElevation	Double	否	卫星的高度角，范围0-90度
21.1.7	mAzimuth	Double	否	卫星的方位角，范围0-360度
21.1.8	mCarrierFrequencyHz	Double	否	所跟踪信号的载波频率
21.2	mProvider	String	否	获取是网络定位、GPS定位还是被动定位
21.3	mHorizontalAccuracyMeters	Double	否	获取此位置的估计精确度 (单位：m)
21.4	mAltitude	Double	否	海拔高度，以WGS 84模型作为参考
21.5	mBearing	Double	否	方向度数（0,360）表示正北偏东多少度（0->北，90->东，180->南，270->西）
21.6	mElapsedRealtimeNanos	Long	否	从移动终端启动的时候起经过的时间 (单位：ns)
21.7	mSpeed	Double	否	自传速度（单位：m/s）
21.8	mSatelliteCount	Integer	否	扫描到的卫星总数
21.9	timestamp	Long	否	采集时间戳

经纬度坐标信息：每次定位

22	coordinateInfo	Map	否	经纬度坐标信息
22.1	coordinateSystem	String	否	坐标系 BD09：百度坐标系 GCJ02：高德、火星坐标系 WGS84：谷歌地球坐标系
22.2	longitude	Double	否	GPS经度
22.3	latitude	Double	否	GPS纬度
22.4	timestamp	Long	否	采集时间戳

请求参数示例：测试前请替换appId及签名信息sign

{
    "timestamp": 1490839495229,
    "appId": "38f6a65f4df2",
    "oid": "52D846AC-63A6-4362-BAC8-DB0EC3B0F82B",
    "oidType": "4",
    "mac": "80FC7C2C-A17D-4537-9BFA-9184D07D0431",
    "networkMode": "3",
    "passthrough": "passthrough_example",
    "sign": "b1d149458113278a3e61287ce1896644abe00189",
    "signals": [{
        "bssid": "e4aa5d3e7d10",
        "rssi": -55,
        "ssid": "Coastal City Free",
        "connectState": 1,
        "timestamp": 1490839495229
    }, {
        "bssid": "e4aa5d3e7d11",
        "rssi": -55,
        "ssid": "LCD_WiFi",
        "timestamp": 1490839495229
    }, {
        "bssid": "8682f42adad5",
        "rssi": -57,
        "ssid": "Superdry2",
        "timestamp": 1490839495229
    }, {
        "bssid": "8482f42adad5",
        "rssi": -57,
        "ssid": "Superdry",
        "timestamp": 1490839495229
    }],
    "baseStationList": [{
        "type": 4,
        "mcc": 460,
        "mnc": 11,
        "lac": null,
        "cid": null,
        "tac": 6165,
        "ci": 26366002,
        "pci": 189,
        "psc": null,
        "sid": null,
        "nid": null,
        "bid": null,
        "dBm": -93,
        "asuLevel": 4,
        "level": 4,
        "timestamp": 1490839495229,
        "register": 1
    }],
"coordinateInfo": {
        "coordinateSystem": "GCJ02",
        "longitude": 113.9359091493863,
        "latitude": 22.5269166908687,
        "timestamp": 1490839495229
    },
    "deviceInfo": {
        "imei": "861839038135744",
        "idfa": "",
        "andid": "bf49728053e511bf",
        "device": "honor v8",
        "osv": "6.0",
        "carrier": "2",
        "imsi": "460030912121001",
        "romInfo": "Meizu/FLYME/Flyme+6.2.0.2A",
        "width": 540,
        "height": 960
    },
    "appInfo": [{
        "applicationId": "com.example.app",
        "versionCode": 2,
        "versionName": "1.1",
        "firstTime": 1487045308000,
        "lastTime": 1487045308000,
        "totalTime": 1487045308000
    }],
    "bluetoothInfo": [{
            "name": "",
            "mac": "64a651e5ff4f",
            "rssi": -26,
            "ibeaconUUID": "00000000-0000-0000-0000-000000000000",
            "ibeaconMajorId": 100,
            "ibeaconMinorId": 1,
            "timestamp": 1490839495229
        },
        {
            "name": "",
            "mac": "64a651e5ff4f",
            "rssi": -52,
            "ibeaconUUID": "00000000-0000-0000-0000-000000000000",
            "ibeaconMajorId": 100,
            "ibeaconMinorId": 1,
            "timestamp": 1490839495229
        }
    ],
    "magneticInfo": {
        "magX": 41.4567754607595,
        "magY": 34.7876059543584,
        "magZ": 30.1879635400726,
        "sensorName": "MMC3416PJ Magnetometer",
        "sensorVendor": "MEMSIC",
        "sensorVersion": "1",
        "timestamp": 1490839495229
    },
    "orientationInfo": {
        "pitch": 10,
        "roll": -30,
        "azimuth": 180,
        "sensorName": "Orientation",
        "sensorVendor": "QTI",
        "sensorVersion": "2",
        "timestamp": 1490839495229
    },
    "lightInfo": {
        "lux": 115,
        "sensorName": "APDS-9921 Light",
        "sensorVendor": "Avago",
        "sensorVersion": "1",
        "timestamp": 1490839495229
    },
    "gpsInfo": {
        "satelliteInfo": [{
            "mHasEphemeris": false,
            "mHasAlmanac": true,
            "mUsedInFix": false,
            "mPrn": 13,
            "mSnr": 0.0,
            "mElevation": 49.0,
            "mAzimuth": 299.0
        }],
        "mProvider": "gps",
        "mHorizontalAccuracyMeters": 56.70,
        "mAltitude": 0.0,
        "mBearing": 77,
        "mElapsedRealtimeNanos": 123456789,
        "mSpeed": 0.0,
        "mSatelliteCount": 1,
        "timestamp": 1490839495229
    },
    "ssidEncode": 0,
    "osType": 1,
    "appChannel": 1
}

2.1.1.3 响应参数

序号	字段	数据类型	说明
1	retCode	Integer	业务码。0：定位成功，包含结果; >0：参见业务码说明。
2	msg	String	业务码辅助提示信息。有定位结果："OK"; 无定位结果或其他：参见业务码说明。
3	requestSign	String	请求签名
4	data		返回数据实体
4.1	timestamp	String	接口响应时间戳（ms）
4.2	city	String	城市
4.3	region	String	行政区
4.4	area	String	商圈信息
4.5	address	String	地址
4.6	floorName	String	楼层信息
4.7	name	String	POI名称
4.8	brand	String	品牌
4.9	areaCategory	String	商圈分类
4.10	areaAttribute	String	商圈属性
4.11	poiId	String	POI唯一标识
4.12	poiCategory	String	POI分类
4.13	poiAttribute	String	POI属性
4.14	coordinateSystem	String	经纬度坐标系类型： BD09-百度坐标系； GCJ02-火星坐标系； WGS84-地球坐标系
4.15	longitude	Double	经度
4.16	latitude	Double	纬度
4.17	passthrough	String	透传参数

响应参数示例：

{
    "retCode": 0,
    "msg": "OK",
    "requestSign": "439d8190a0ac977306ae436859bd4a9b25a64ada",
    "data": {
        "timestamp": 1552374907740,
        "city": "深圳市",
        "region": "南山区",
        "area": "海岸城购物中心",
        "address": "文心四路14",
        "floorName": "1",
        "name": "zara",
        "brand": "zara",
        "areaCategory": "购物中心;商场",
        "areaAttribute": "档次:高档",
        "poiId": "fdae3e2cd316bb8a",
        "poiCategory": "购物;服装",
        "poiAttribute": "风格:潮流时尚|品牌来源:欧美",
        "coordinateSystem": "GCJ02",
        "longitude": 113.936074,
        "latitude": 22.51703,
        "passthrough": "passthrough_example"
    }
}

2.2 场景识别批量请求接口

接口地址：https://api.jjfinder.com/v3/scene/api/batch

通过POST方式提交数据到API需要使用测试AppID作为唯一标识，使用测试AppKey进行签名。

注意：请求接口的域名及AppID、AppKey请以商务邮件为准，正式上线时请使用生产的配置。

2.2.1接口参数说明

2.2.1.1设置请求头

在请求头中添加Authorization，值为 2.2.1.2 中参数内容以及请求List长度拼接，List长度值允许范围是：[1, 10]，格式如下：

t=%d;a=%s;bs=%d;

生成Authorization样例代码如下：

public String authorization(){      
    return String.format("t=%d;a=%s;bs=%d;",timestamp, appId, requestListSize);  }

添加请求头样例代码：

conn.setRequestProperty("Content-Type","application/json");

conn.setRequestProperty("Authorization",authorization);

2.2.1.2 请求参数

定位请求必须参数：只需把 2.1.1.2 对象改为List ，List最多允许放10条数据

请求参数示例：测试前请替换appId及签名信息sign

[
{
    "timestamp": 1490839495229,
    "appId": "38f6a65f4df2",
    "oid": "52D846AC-63A6-4362-BAC8-DB0EC3B0F82B",
    "oidType": "4",
    "mac": "80FC7C2C-A17D-4537-9BFA-9184D07D0431",
    "networkMode": "3",
    "passthrough": "passthrough_example",
    "sign": "b1d149458113278a3e61287ce1896644abe00189",
    "signals": [{
        "bssid": "e4aa5d3e7d10",
        "rssi": -55,
        "ssid": "Coastal City Free",
        "connectState": 1,
        "timestamp": 1490839495229
    }, {
        "bssid": "e4aa5d3e7d11",
        "rssi": -55,
        "ssid": "LCD_WiFi",
        "timestamp": 1490839495229
    }, {
        "bssid": "8682f42adad5",
        "rssi": -57,
        "ssid": "Superdry2",
        "timestamp": 1490839495229
    }, {
        "bssid": "8482f42adad5",
        "rssi": -57,
        "ssid": "Superdry",
        "timestamp": 1490839495229
    }],
    "baseStationList": [{
        "type": 4,
        "mcc": 460,
        "mnc": 11,
        "lac": null,
        "cid": null,
        "tac": 6165,
        "ci": 26366002,
        "pci": 189,
        "psc": null,
        "sid": null,
        "nid": null,
        "bid": null,
        "dBm": -93,
        "asuLevel": 4,
        "level": 4,
        "timestamp": 1490839495229,
        "register": 1
    }],
"coordinateInfo": {
        "coordinateSystem": "GCJ02",
        "longitude": 113.9359091493863,
        "latitude": 22.5269166908687,
        "timestamp": 1490839495229
    },
    "deviceInfo": {
        "imei": "861839038135744",
        "idfa": "",
        "andid": "bf49728053e511bf",
        "device": "honor v8",
        "osv": "6.0",
        "carrier": "2",
        "imsi": "460030912121001",
        "romInfo": "Meizu/FLYME/Flyme+6.2.0.2A",
        "width": 540,
        "height": 960
    },
    "appInfo": [{
        "applicationId": "com.example.app",
        "versionCode": 2,
        "versionName": "1.1",
        "firstTime": 1487045308000,
        "lastTime": 1487045308000,
        "totalTime": 1487045308000
    }],
    "bluetoothInfo": [{
            "name": "",
            "mac": "64a651e5ff4f",
            "rssi": -26,
            "ibeaconUUID": "00000000-0000-0000-0000-000000000000",
            "ibeaconMajorId": 100,
            "ibeaconMinorId": 1,
            "timestamp": 1490839495229
        },
        {
            "name": "",
            "mac": "64a651e5ff4f",
            "rssi": -52,
            "ibeaconUUID": "00000000-0000-0000-0000-000000000000",
            "ibeaconMajorId": 100,
            "ibeaconMinorId": 1,
            "timestamp": 1490839495229
        }
    ],
    "magneticInfo": {
        "magX": 41.4567754607595,
        "magY": 34.7876059543584,
        "magZ": 30.1879635400726,
        "sensorName": "MMC3416PJ Magnetometer",
        "sensorVendor": "MEMSIC",
        "sensorVersion": "1",
        "timestamp": 1490839495229
    },
    "orientationInfo": {
        "pitch": 10,
        "roll": -30,
        "azimuth": 180,
        "sensorName": "Orientation",
        "sensorVendor": "QTI",
        "sensorVersion": "2",
        "timestamp": 1490839495229
    },
    "lightInfo": {
        "lux": 115,
        "sensorName": "APDS-9921 Light",
        "sensorVendor": "Avago",
        "sensorVersion": "1",
        "timestamp": 1490839495229
    },
    "gpsInfo": {
        "satelliteInfo": [{
            "mHasEphemeris": false,
            "mHasAlmanac": true,
            "mUsedInFix": false,
            "mPrn": 13,
            "mSnr": 0.0,
            "mElevation": 49.0,
            "mAzimuth": 299.0
        }],
        "mProvider": "gps",
        "mHorizontalAccuracyMeters": 56.70,
        "mAltitude": 0.0,
        "mBearing": 77,
        "mElapsedRealtimeNanos": 123456789,
        "mSpeed": 0.0,
        "mSatelliteCount": 1,
        "timestamp": 1490839495229
    },
    "ssidEncode": 0,
    "osType": 1,
    "appChannel": 1
}
]

2.2.1.3 响应参数

响应参数说明：即 2.1.1.3 的响应参数的List形式，可以通过requestSign与请求进行关联

响应参数示例：

[
{
    "retCode": 0,
    "msg": "OK",
    "requestSign": "439d8190a0ac977306ae436859bd4a9b25a64ada",
    "data": {
        "timestamp":1552374907740,
        "city": "深圳市",
        "region": "南山区",
        "area": "海岸城购物中心",
        "address": "文心四路14",
        "floorName": "1",
        "name": "zara",
        "brand": "zara",
        "areaCategory": "购物中心;商场",
        "areaAttribute": "档次:高档",
        "poiId": "fdae3e2cd316bb8a",
        "poiCategory": "购物;服装",
        "poiAttribute": "风格:潮流时尚|品牌来源:欧美",
        "coordinateSystem": "GCJ02",
        "longitude": 113.936074,
        "latitude": 22.51703,
        "passthrough": "passthrough_example"
    }
}
]

2.3 请求和响应数据需要AES加解密

2.3.1 加解密方式

加解密密钥：appkey去除"-"后取前16位；

加密算法：AES128；

AES模式：CBC；

AES填充方式：PKCS#7；

AES向量：appkey去除"-"后取后16位；

字符集：UTF-8；

编码：Base64编码。

2.3.2 加解密示例

A、AppKey: 5d4a7bac-98a2-4a9f-a47a-38f6a65f4df2

密钥：5d4a7bac98a24a9f

向量：a47a38f6a65f4df2

B、对上面 2.1.1.2 中的单接口请求参数示例数据加密示例如下：

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

C、对上面 2.2.1.2 中的批量接口请求参数示例数据加密示例如下：

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

3 签名算法

3.1 签名算法说明

1) 字符集为 utf-8;

2) 所有不为空的参数都需要加入签名，参数必须为做 urlencode 之前的原始数值。如中文："位置",作为参数传输时编码为%E9%87%91%E5%B8%81,做签名时则要用其原始中文值"位置"(注意字符集必须是 UTF-8)；

3) 对所有不为空的参数按照参数名字母升序排列(如php的ksort函数)；

4) 使用符号 # 拼装排序后的参数值, 最后用 # 连接应用的appKey, 整体用sha1计算签名, 就是 sign参数的值. 注意有些语言的计算结果里字母为大写, 需要转化为小写。

5) 批量接口List里面的每一条数据单独计算签名。

3.2 签名示例

对上面 2.1.1.2 请求参数示例数据签名示例如下：

A 参数名按照升序排序并把appKey的值拼接到最后，参数名拼接示例如下：

appChannel#appId#mac#networkMode#oid#oidType#osType#ssidEncode#timestamp#appKey

B 参数值拼接成签名串结果如下：

1#38f6a65f4df2#80FC7C2C-A17D-4537-9BFA-9184D07D0431#3#52D846AC-63A6-4362-BAC8-DB0EC3B0F82B#4#1#0#1490839495229#5d4a7bac-98a2-4a9f-a47a-38f6a65f4df2

C 对签名串做sha1加密后转小写即可得出sign结果如下：

b1d149458113278a3e61287ce1896644abe00189

4 后台 SDK

数位提供了Java、Golang两个版本的后台SDK,已在github开源，对上述请求头设置、加密、签名、请求及响应过程进行了封装，如果后台是这两种语言开发的，可以直接集成SDK包，以简化接入过程。

Java SDK：https://github.com/sw-cloud/shuwei-elbs-sdk-java

Golang SDK：https://github.com/sw-cloud/shuwei-elbs-sdk-go

5 业务码说明

retCode	msg	remark
0	OK	定位有结果
100001	System error	服务器错误
100002	Environment error	环境错误
100003	Miss required parameter	缺少必传参数
100004	Parameter value invalid	参数格式错误
100005	Sign error	签名错误
100006	Package name error	包名错误
100007	Request data is null	请求数据为空
100008	Lack authorization	限制访问。缺少头部授权信息
100009	Restricted access.App TPS reach limit	限制访问。应用每秒事务数达到上限
100010	Restricted access.Transaction reach limit	限制访问。达到事务数配额上限
100011	Restricted access.TPS reach limit	限制访问。接口每秒事务数达到上限
100012	Api version is wrong	接口版本错误
10002001	Illegal oid.Fake oid	疑似虚假设备号
10002002	Illegal oid.Oid request frequency is too high	高频请求
201001	No result	定位无结果
203004	AppId invalid	AppId无效
203005	App is disabled	App不可用
203006	App type error	App类型错误

howell92

发布了5 篇原创文章 · 获赞 0 · 访问量 82

私信关注

数位云开发者平台：室内定位api接入文档