小钉云基础 API 文档

版本：V1.4 ｜ 接口路径前缀：/vehicle-externalinterface 文档生成：基于《小钉云基础 API 文档 1.4》整理｜ 最后更新：2025-08-12 适用产品：小钉云（移动劳动力管理 / MWM 基础开放接口）

一、文档说明

项	内容
接口协议	HTTPS + JSON（请求 `Content-Type: application/json`，响应 `/`）
Base URL（已脱敏）	`https://www.xxxx.com/openapi/`
认证方式	`userKey` 换取 `access_token`，后续请求通过请求头 `Authorization` 携带
字符集	UTF-8
请求方式	全部为 `POST`

⚠️ 脱敏说明：原始文档中的真实服务域名已在本文中统一替换为占位地址 https://www.xxxx.com，接入时请向平台管理员获取实际可用域名与 userKey。

二、快速开始

向平台管理员申请 userKey（密匙）。
调用 获取 Token 接口，用 userKey 换取 access_token。
在后续所有业务接口的请求头中加入 Authorization: <access_token>。
按接口规范以 JSON Body 传入查询条件，解析统一响应结构中的 data 字段。

示例：获取 Token 并调用设备信息接口

# 1. 获取 Token
curl -X POST 'https://www.xxxx.com/openapi/auth/userKeyLogin' \
  -H 'Content-Type: application/json' \
  -d '{"userKey": "YOUR_USER_KEY"}'

# 2. 携带 Token 调用业务接口
curl -X POST 'https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getEquipmentInfoList' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_ACCESS_TOKEN' \
  -d '{"equipmentIdList": []}'

三、通用规范

3.1 公共请求头部

Header 名称	描述	类型	是否必须
`Authorization`	请求合法性校验签名，取值为「获取 Token」接口返回的 `access_token`	string	是（获取 Token 接口除外）

3.2 公共响应结构

所有接口统一返回如下结构：

{
  "code": 0,
  "data": {},
  "msg": ""
}

字段	类型	说明
`code`	integer(int32)	业务状态码，`0` 表示成功
`data`	object / array	业务数据，结构随接口而异
`msg`	string	提示信息，成功时通常为空

3.3 响应状态码（HTTP）

状态码	说明
`200`	OK，请求成功
`201`	Created
`401`	Unauthorized，Token 缺失或无效
`403`	Forbidden，无权限
`404`	Not Found，接口或资源不存在

3.4 约定说明

时间类字段标注 date-time 的，按接口返回原始时间字符串（多为 yyyy-MM-dd HH:mm:ss）。
工时/时长类字段凡标注「单位：毫秒」的，返回值为 Unix 毫秒时间戳。
数组查询条件（如 wholeIdList、groupIdList）为空数组或不传时，通常返回全量数据，以实际环境为准。

四、接口列表

序号	接口	路径
1	获取 Token	`/auth/userKeyLogin`
2	设备信息数据获取	`/vehicle-externalinterface/hxkj/interface/getEquipmentInfoList`
3	组织数据获取	`/vehicle-externalinterface/hxkj/interface/getGroupInfoList`
4	人员信息数据获取	`/vehicle-externalinterface/hxkj/interface/getPersonnelList`
5	花名册数据获取	`/vehicle-externalinterface/hxkj/interface/getRosterList`
6	人员排班信息数据获取	`/vehicle-externalinterface/hxkj/interface/getSchedulingList`
7	工位 ID 信息获取	`/vehicle-externalinterface/hxkj/interface/getStationIdList`
8	工位信息获取	`/vehicle-externalinterface/hxkj/interface/getStationInfoList`
9	轨迹数据获取	`/vehicle-externalinterface/hxkj/interface/getTrajectoryList`
10	月度报表统计数据获取	`/vehicle-externalinterface/hxkj/interface/gerMonthlyReportNewList`

五、接口详情

5.1 获取 Token

接口地址：https://www.xxxx.com/openapi/auth/userKeyLogin
请求方式：POST
接口描述：使用平台下发的 userKey 换取访问令牌 access_token，有效期见响应 expires_in。

请求参数（Body）

参数	类型	必填	说明
`userKey`	string	是	密匙，由平台生成，需向平台管理员获取

请求示例

{
  "userKey": ""
}

响应参数

字段	类型	说明
`code`	integer(int32)	状态码
`data.access_token`	string	Token 令牌
`data.expires_in`	string	过期时间
`data.userName`	string	用户名
`msg`	string	提示信息

响应示例

{
  "code": 0,
  "data": {
    "access_token": "",
    "expires_in": "",
    "userName": ""
  },
  "msg": ""
}

5.2 设备信息数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getEquipmentInfoList
请求方式：POST
接口描述：获取设备（人员绑定终端）的实时定位、电量、速度等信息。

请求参数（Body）

参数	类型	必填	说明
`equipmentIdList`	array<string>	否	设备 ID 集合，为空返回全量

请求示例

{
  "equipmentIdList": []
}

响应参数（data 为设备信息数组）

字段	类型	说明
`direct`	number(double)	方向
`equipmentId`	string	设备 ID
`gpsTime`	string(date-time)	定位时间
`lat`	number(double)	纬度
`lng`	number(double)	经度
`powerNumber`	integer(int32)	电量（百分比）
`recvTime`	string(date-time)	服务器时间
`reportTypeName`	string	定位模式
`speed`	number(double)	速度
`stateLiveName`	string	在线状态
`stepNumber`	integer(int32)	步数
`wifiInfo`	string	WiFi 信息
`wifiNumber`	integer(int32)	WiFi 数量

响应示例

{
  "code": 0,
  "data": [
    {
      "direct": 0,
      "equipmentId": "",
      "gpsTime": "",
      "lat": 0,
      "lng": 0,
      "powerNumber": 0,
      "recvTime": "",
      "reportTypeName": "",
      "speed": 0,
      "stateLiveName": "",
      "stepNumber": 0,
      "wifiInfo": "",
      "wifiNumber": 0
    }
  ],
  "msg": ""
}

5.3 组织数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getGroupInfoList
请求方式：POST
接口描述：获取组织架构（部门树）信息，无查询条件参数。

请求参数：暂无

响应参数（data 为组织信息数组）

字段	类型	说明
`groupName`	string	部门名称
`id`	integer(int64)	部门 ID
`parentId`	Long	上级部门 ID
`departmentCode`	string	部门编码（对应编码）
`organizeId`	string	组织 ID（对应编码）

响应示例

{
  "code": 0,
  "data": [
    {
      "groupName": "",
      "id": 0,
      "parentId": 0,
      "departmentCode": "",
      "organizeId": ""
    }
  ],
  "msg": ""
}

5.4 人员信息数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getPersonnelList
请求方式：POST
接口描述：获取人员实时在岗、考勤、工时、里程、责任工位等综合信息。

请求参数（Body）

参数	类型	必填	说明
`wholeIdList`	array<integer(int64)>	否	人员 ID 集合，为空返回全量

请求示例

{
  "wholeIdList": []
}

响应参数（data 为人员信息数组）

字段	类型	说明
`className`	string	排班（班次名）
`equipmentId`	string	设备 ID
`phoneNumber`	string	手机号
`cardId`	string	身份证
`wholeTypeName`	string	职务
`registerTime`	string(date-time)	签到时间
`reschTypeName`	string	当前排班
`signoutTime`	string(date-time)	签退时间
`stateCheckName`	string	考勤状态
`stateLiveName`	string	在岗状态
`stationList`	array(Station)	责任工位列表，见下方子结构
`todayMileage`	number(double)	今日里程（单位：KM）
`todayStepNumber`	integer(int32)	今日步数
`totaClassTime`	integer(int64)	排班工时（单位：毫秒）
`totalnegativeTime`	integer(int64)	负工时（单位：毫秒）
`wholeId`	integer(int64)	人员 ID
`wholeName`	string	姓名
`workDate`	string(date-time)	日期
`workHourTime`	integer(int64)	工时（单位：毫秒）
`workMileage`	number(double)	在岗里程（单位：KM）
`workStepNumber`	integer(int32)	在岗步数

data[].stationList[] 子结构（Station）

字段	类型	说明
`id`	integer	工位 ID
`stationName`	string	工位名称
`wholeId`	integer	人员 ID

响应示例

{
  "code": 0,
  "data": [
    {
      "className": "",
      "equipmentId": "",
      "phoneNumber": "",
      "cardId": "",
      "wholeTypeName": "",
      "registerTime": "",
      "reschTypeName": "",
      "signoutTime": "",
      "stateCheckName": "",
      "stateLiveName": "",
      "stationList": [
        { "id": 0, "stationName": "", "wholeId": 0 }
      ],
      "todayMileage": 0,
      "todayStepNumber": 0,
      "totaClassTime": 0,
      "totalnegativeTime": 0,
      "wholeId": 0,
      "wholeName": "",
      "workDate": "",
      "workHourTime": 0,
      "workMileage": 0,
      "workStepNumber": 0
    }
  ],
  "msg": ""
}

5.5 花名册数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getRosterList
请求方式：POST
接口描述：按组织获取人员花名册（在职状态）信息。

请求参数（Body）

参数	类型	必填	说明
`groupIdList`	array<integer(int64)>	否	组织 ID 集合，为空返回全量

请求示例

{
  "groupIdList": []
}

响应参数（data 为花名册数组）

字段	类型	说明
`id`	integer(int64)	人员 ID
`isObJob`	integer(int32)	是否在职：`0` 离职，`1` 在职
`wholeName`	string	姓名
`groupId`	Long	所属部门 ID

响应示例

{
  "code": 0,
  "data": [
    { "id": 0, "isObJob": 0, "wholeName": "", "groupId": 0 }
  ],
  "msg": ""
}

5.6 人员排班信息数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getSchedulingList
请求方式：POST
接口描述：按人员与时间范围获取排班（班次）信息。

请求参数（Body）

参数	类型	必填	说明
`endDate`	string(date-time)	否	结束时间
`startDate`	string(date-time)	否	开始时间
`wholeIdList`	array<integer(int64)>	否	人员 ID 集合

请求示例

{
  "endDate": "",
  "startDate": "",
  "wholeIdList": []
}

响应参数（data 为排班信息数组）

字段	类型	说明
`className`	string	班次名称
`id`	integer(int64)	排班详情 ID
`isTemporary`	integer(int32)	是否临时排班
`reschTypeName`	string	当前排班
`restTime`	string	休息时间
`wholeId`	integer(int64)	员工 ID
`workDate`	string(date-time)	排班日期
`workTime`	string	工作时间

响应示例

{
  "code": 0,
  "data": [
    {
      "className": "",
      "id": 0,
      "isTemporary": 0,
      "reschTypeName": "",
      "restTime": "",
      "wholeId": 0,
      "workDate": "",
      "workTime": ""
    }
  ],
  "msg": ""
}

5.7 工位 ID 信息获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getStationIdList
请求方式：POST
接口描述：按组织获取工位 ID 集合，供后续「工位信息获取」入参使用。

请求参数（Body）

参数	类型	必填	说明
`groupIdList`	array<integer(int64)>	否	组织 ID 集合，为空返回全量

请求示例

{
  "groupIdList": []
}

响应参数（data 为工位 ID 信息对象）

字段	类型	说明
`stationIdList`	array<integer(int64)>	工位 ID 集合

响应示例

{
  "code": 0,
  "data": { "stationIdList": [] },
  "msg": ""
}

5.8 工位信息获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getStationInfoList
请求方式：POST
接口描述：按工位 ID 获取工位名称及其地理围栏详情（点/线/面）。

请求参数（Body）

参数	类型	必填	说明
`stationIdList`	array<integer(int64)>	否	工位 ID 集合，为空返回全量

请求示例

{
  "stationIdList": []
}

响应参数（data 为工位信息数组）

字段	类型	说明
`id`	integer(int64)	工位 ID
`stationName`	string	工位名称
`stationDetailList`	array(StationDetail)	工位地理详情，见下方子结构

data[].stationDetailList[] 子结构（StationDetail，高德坐标系）

字段	类型	说明
`drawType`	integer	画图类型：`1`-点，`2`-线，`3`-面
`id`	integer	ID
`lat`	number	纬度（高德地图纬度）
`lng`	number	经度（高德地图经度）
`pointOrder`	integer	画点的顺序
`stationId`	integer	工位 ID
`stationLocpoId`	integer	工位下的详情工位 ID（用于区分详细工位）

响应示例

{
  "code": 0,
  "data": [
    {
      "id": 0,
      "stationName": "",
      "stationDetailList": [
        {
          "drawType": 0, "id": 0, "lat": 0, "lng": 0,
          "pointOrder": 0, "stationId": 0, "stationLocpoId": 0
        }
      ]
    }
  ],
  "msg": ""
}

5.9 轨迹数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/getTrajectoryList
请求方式：POST
接口描述：按人员与时间范围获取定位轨迹，返回结构为「人员 ID → 轨迹点列表」的映射。

请求参数（Body）

参数	类型	必填	说明
`endDate`	string(date-time)	否	结束时间
`startDate`	string(date-time)	否	开始时间
`wholeIdList`	array<integer(int64)>	否	人员 ID 集合

请求示例

{
  "endDate": "",
  "startDate": "",
  "wholeIdList": []
}

响应参数（data 为 Map<人员ID, 轨迹信息列表>，轨迹点字段如下）

字段	类型	说明
`direct`	number(double)	方向
`equipmentId`	string	设备 ID
`gpsTime`	string	定位时间
`lat`	number(double)	纬度
`lng`	number(double)	经度
`powerNumber`	integer(int32)	电量（百分比）
`reportTypeName`	string	定位模式
`speed`	number(double)	速度
`stepNumber`	integer(int32)	步数
`todayMileage`	integer(int32)	今日里程
`todayStepNumber`	integer(int32)	今日步数
`wholeId`	integer(int64)	人员 ID
`workMileage`	integer(int32)	在岗里程
`workStepNumber`	integer(int32)	在岗步数

响应示例

{
  "code": 0,
  "data": {
    "additionalProperties1": [
      {
        "direct": 0, "equipmentId": "", "gpsTime": "", "lat": 0, "lng": 0,
        "powerNumber": 0, "reportTypeName": "", "speed": 0, "stepNumber": 0,
        "todayMileage": 0, "todayStepNumber": 0, "wholeId": 0,
        "workMileage": 0, "workStepNumber": 0
      }
    ]
  },
  "msg": ""
}

5.10 月度报表统计数据获取

接口地址：https://www.xxxx.com/openapi/vehicle-externalinterface/hxkj/interface/gerMonthlyReportNewList
请求方式：POST
接口描述：获取人员月度考勤/工时/加班/脱岗等综合统计报表，结构较复杂，按分组对象返回。

注：原始接口路径为 gerMonthlyReportNewList（疑似 get 笔误），以平台实际路径为准。

请求参数（Body）

参数	类型	必填	说明
`endDate`	string(date-time)	否	结束日期
`startDate`	string(date-time)	否	开始日期
`wholeIdList`	array<integer(int64)>	否	人员 ID 集合

请求示例

{
  "endDate": "",
  "startDate": "",
  "wholeIdList": []
}

响应参数（data 为每月统计报表数组）

data[] 顶层字段及分组对象：

分组	字段	类型	说明
—	`wholeId`	string	人员 ID
—	`wholeName`	string	姓名
`absentCardStatistics`（缺卡补卡统计）	`absentCardCount`	integer	缺卡次数
	`reissueCardDays`	integer	补卡天数
`attendanceExceptionStatistics`（出勤异常统计）	`lateCount`	integer	迟到次数
	`lateHoursCN`	string	迟到时长
	`lateMs`	integer	迟到（毫秒）
	`leaveEarly`	integer	早退次数
	`leaveEarlyHoursCN`	string	早退时长
	`leaveEarlyMs`	integer	早退（毫秒）
	`severityLateCount`	integer	严重迟到次数
	`severityLateHoursCN`	string	严重迟到时长
	`severityLateMs`	integer	严重迟到（毫秒）
	`severityLeaveEarly`	integer	严重早退次数
	`severityLeaveEarlyHoursCN`	string	严重早退时长
	`severityLeaveEarlyMs`	integer	严重早退（毫秒）
	`lossWorkList`	array	迟到早退明细集合，见下
	`attendanceGroupName`	string	考勤组
	`attendanceType`	string	考勤类型
`attendanceResultByMonth`（每日考勤结果）	`date`	string	日期
	`value`	string	考勤结果
`attendanceStatistics`（出勤统计）	`attendanceDays`	number	出勤天数
	`exceptionDays`	integer	异常考勤天数
	`leaveDays`	number	请假天数
	`noWorkDays`	integer	旷工天数
	`planWorkDays`	number	应出勤天数
`baseInfo`（基本信息）	`age`	string	年龄
	`contractCompany`	string	合同公司
	`createDate`	string	入职日期
	`employStatus`	string	员工状态（`0`-正式，`1`-试用）
	`employType`	string	人员类型（`0`-无类型，`1`-全职，`2`-兼职，`3`-实习，`4`-劳务派遣，`5`-退休返聘，`6`-劳务外包，`7`-灵活用工）
	`groupArchitecture`	string	组织
	`groupId`	integer	部门 ID
	`groupName`	string	部门
	`idCardHidden`	string	身份证号
	`leadName`	string	直属上级
	`overdueDate`	string	离职日期
	`phoneNumber`	string	电话
	`sex`	string	性别（`1`-男，`2`-女）
	`stationName`	string	工位
	`wholeId`	string	人员 ID
	`wholeIdNo`	string	工号
	`wholeTypeName`	string	职务
`leaveStatistics`（请假统计，数组）	`day`	string	请假天数
	`id`	string	请假类型 ID
	`type`	string	请假类型名称
`overTimeStatistics`（加班统计）	`holidayOverTimeHours`	integer	节假日加班
	`holidayOverTimeHoursCN`	string	节假日加班（文本）
	`overTimeHours`	integer	加班总时长
	`overTimeHoursCN`	string	加班总时长（文本）
	`overTimeHoursPay`	integer	加班总时长-计加班费
	`overTimeHoursPayCN`	string	加班总时长-计加班费（文本）
	`overTimeHoursRest`	integer	加班总时长-计调休
	`overTimeHoursRestCN`	string	加班总时长-计调休（文本）
	`restDayOverTimeHours`	integer	休息日加班
	`restDayOverTimeHoursCN`	string	休息日加班（文本）
	`workDayOverTimeHours`	integer	工作日加班
	`workDayOverTimeHoursCN`	string	工作日加班（文本）
`sitOffWorkStatistics`（坐岗脱岗统计）	`offWorkCount`	integer	脱岗次数
	`offWorkHours`	string	脱岗时长
	`sitWorkCount`	integer	坐岗次数
	`sitWorkHours`	string	坐岗时长
	`sitOffWorkList`	array	脱岗坐岗明细集合，见下
	`wholeId`	string	人员 ID
	`wholeName`	string	姓名
`workHourStatistics`（工时统计）	`absentHours`	string	缺勤工时
	`noWorkHours`	string	旷工时长
	`totaClassHours`	string	排班工时
	`totalnegativeHours`	string	负工时
	`workHours`	string	工时

attendanceExceptionStatistics.lossWorkList[] 明细

字段	类型	说明
`eventType`	string	事件类型：`27`-迟到事件，`28`-早退事件
`hours`	long	时长
`hoursString`	string	时长（文本）
`type`	integer	考勤类型：`1`-迟到，`2`-早退，`12`-严重迟到，`13`-严重早退，`17`-旷工迟到
`eventDate`	string	事件日期

sitOffWorkStatistics.sitOffWorkList[] 明细

字段	类型	说明
`eventType`	integer	事件类型：`21`-脱岗事件，`25`-坐岗事件
`minute`	long	时长（分钟）
`hours`	string	时长
`startTime`	string	开始时间
`endTime`	string	结束时间
`workDate`	string	事件日期

响应示例

{
  "code": 0,
  "data": [
    {
      "absentCardStatistics": { "absentCardCount": 0, "reissueCardDays": 0 },
      "attendanceExceptionStatistics": {
        "lateCount": 0, "lateHoursCN": "", "lateMs": 0,
        "leaveEarly": 0, "leaveEarlyHoursCN": "", "leaveEarlyMs": 0,
        "severityLateCount": 0, "severityLateHoursCN": "", "severityLateMs": 0,
        "severityLeaveEarly": 0, "severityLeaveEarlyHoursCN": "", "severityLeaveEarlyMs": 0,
        "lossWorkList": [],
        "attendanceGroupName": "", "attendanceType": ""
      },
      "attendanceResultByMonth": [ { "date": "", "value": "" } ],
      "attendanceStatistics": {
        "attendanceDays": 0, "exceptionDays": 0, "leaveDays": 0, "noWorkDays": 0, "planWorkDays": 0
      },
      "baseInfo": {
        "age": "", "contractCompany": "", "createDate": "", "employStatus": "",
        "employType": "", "groupArchitecture": "", "groupId": 0, "groupName": "",
        "idCardHidden": "", "leadName": "", "overdueDate": "", "phoneNumber": "",
        "sex": "", "stationName": "", "wholeId": "", "wholeIdNo": "", "wholeTypeName": ""
      },
      "leaveStatistics": [ { "day": "", "id": "", "type": "" } ],
      "overTimeStatistics": {
        "holidayOverTimeHours": 0, "holidayOverTimeHoursCN": "", "overTimeHours": 0,
        "overTimeHoursCN": "", "overTimeHoursPay": 0, "overTimeHoursPayCN": "",
        "overTimeHoursRest": 0, "overTimeHoursRestCN": "", "restDayOverTimeHours": 0,
        "restDayOverTimeHoursCN": "", "workDayOverTimeHours": 0, "workDayOverTimeHoursCN": ""
      },
      "sitOffWorkStatistics": {
        "offWorkCount": 0, "offWorkHours": "", "sitWorkCount": 0, "sitWorkHours": "",
        "sitOffWorkList": [], "wholeId": "", "wholeName": ""
      },
      "workHourStatistics": {
        "absentHours": "", "noWorkHours": "", "totaClassHours": "", "totalnegativeHours": "", "workHours": ""
      },
      "wholeId": "", "wholeName": ""
    }
  ],
  "msg": ""
}

六、修订记录

版本	日期	变更
V1.4	2025-08-12	基于《小钉云基础 API 文档 1.4》整理生成基础 API 文档（域名脱敏为 `https://www.xxxx.com`）

📌 接入提示：实际 userKey、Base URL、字段枚举值（如考勤类型编码）以平台管理员下发为准；本文档字段说明与示例源自 V1.4 原始接口定义，如发现与线上不一致请以线上返回为准。

一、文档说明​

二、快速开始​

三、通用规范​

3.1 公共请求头部​

3.2 公共响应结构​

3.3 响应状态码（HTTP）​

3.4 约定说明​

四、接口列表​

五、接口详情​

5.1 获取 Token​

5.2 设备信息数据获取​

5.3 组织数据获取​

5.4 人员信息数据获取​

5.5 花名册数据获取​

5.6 人员排班信息数据获取​

5.7 工位 ID 信息获取​

5.8 工位信息获取​

5.9 轨迹数据获取​

5.10 月度报表统计数据获取​

六、修订记录​

一、文档说明

二、快速开始

三、通用规范

3.1 公共请求头部

3.2 公共响应结构

3.3 响应状态码（HTTP）

3.4 约定说明

四、接口列表

五、接口详情

5.1 获取 Token

5.2 设备信息数据获取

5.3 组织数据获取

5.4 人员信息数据获取

5.5 花名册数据获取

5.6 人员排班信息数据获取

5.7 工位 ID 信息获取

5.8 工位信息获取

5.9 轨迹数据获取

5.10 月度报表统计数据获取

六、修订记录