办公地址接入
对接流程
- 调用办公地址批量新增接口,同步地址信息到美团企业版,接口返回美团企业版存储的地址id
- 通过美团企业版地址id,为地址绑定应用范围(全员、某些员工、部门、或者角色)
状态码说明
代码 | 错误描述 | 排查问题建议 |
0 | 成功 | |
-1 | 内部服务异常 | 可联系美团企业版对接人员,协助排查具体原因 |
10000 | token不合法 | 参考:token不合法 |
11000 | 方法名和请求接口不匹配 | 请确认请求中的"method"参数是否与接口说明中method指定方法名一致 |
11001 | 鉴权失败,无接口访问权限 | 访问接口未授权,需要联系美团企业版对接人员,协助开通相关接口权限 |
11005 | content不合法 | 传入参数不是标准的Object类型,调用方可通过Json工具确认 |
11010 | ts缺失或ts时间已过期 | ts(时间戳)单位:秒,参数为空,或者ts时间戳超过10分钟,已经过期,需重新获取最新时间戳 |
12000 | 访问频率过高 | 接口限制每分钟调用100次,超过则提示访问频率过高 |
30000 | 访问次数超过配额 | 接口限制每日调用10万次,超过则提示访问次数超过配额 |
30001 | 越权访问 | 请求参数entId不在token授权范围内,无法访问该企业数据,需要确认token和entId是否正确 |
10130000 | 参数异常 | 请求参数校验异常,请根据接口调用返回结果确认异常具体原因 |
10130001 | 参数不匹配 | 请求传入参数名称或者类型不匹配,请调用方与接口文档核对修正 |
20130001 | 数据越权访问 | 请求需要访问或使用的数据,不属于当前企业,无法进行操作,具体数据可结合调用返回结果确认 |
40130000 | 业务异常 | 请求执行过程中,业务校验未通过,具体原因可结合调用返回结果确认 |
40130001 | 数据异常 | 请求执行过程中,业务数据校验未通过,具体原因可结合调用返回结果确认 |
40130002 | 数据被删除 | 请求访问或者使用的数据,已经被删除,无法被操作,具体数据可结合调用返回结果确认 |
1 批量添加办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,批量同步新增办公地址 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/batch/add |
method | address.batch.add |
服务端超时时间 | 10秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.batch.add | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressAddInfos | List<AddressAddInfoDTO > | 是 | 详见AddressAddInfoDTO字段说明 | 新增地址列表(限制最大size:50) |
AddressAddInfoDTO字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressName | String | 是 | 望京国际研发园 | 地址名称(限制最长为260个字符) |
specificAddress | String | 是 | 北京市朝阳区望京东路6号 | 详细地址(限制最长为100个字符) |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息(限制最长为300个字符) |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识(限制最长为50个字符) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressAddResultItems | List<AddressAddResult > | 是 | 详见AddressAddResult字段说明 | 办公地址新增结果列表 |
AddressAddResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
result | Integer | 是 | 0 | 地址添加结果代码,详见状态码说明 |
message | String | 否 | 成功 | 地址添加错误描述 |
addressId | Long | 否 | 124 | 美团企业版地址id(result=0时,返回该属性值) |
addressName | String | 是 | 望京国际研发园 | 地址名称(限制最长为260个字符) |
specificAddress | String | 是 | 北京市朝阳区望京东路6号 | 详细地址(限制最长为100个字符) |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息(限制最长为300个字符) |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识(限制最长为50个字符) |
示例请求与结果
业务请求
业务响应
2 批量更新办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,批量同步更新办公地址信息 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/batch/update |
method | address.batch.update |
服务端超时时间 | 10秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.batch.update | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressUpdateInfos | List<AddressUpdateInfoDTO > | 是 | 详见AddressUpdateInfoDTO字段说明 | 更新地址列表(限制最大size:50) |
AddressUpdateInfoDTO字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressId | Long | 是 | 124 | 美团企业版地址id |
addressName | String | 是 | 望京国际研发园 | 地址名称(限制最长为260个字符) |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
specificAddress | String | 否 | 北京市朝阳区望京东路6号 | 详细地址(限制最长为100个字符) |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息(限制最长为300个字符) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识(限制最长为50个字符) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressUpdateResultItems | List<AddressUpdateResult > | 是 | 详见AddressUpdateResult字段说明 | 办公地址更新结果列表 |
AddressUpdateResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
result | Integer | 是 | 0 | 地址更新结果代码,详见状态码说明 |
message | String | 否 | 成功 | 地址更新错误描述 |
addressId | Long | 否 | 124 | 美团企业版地址id |
示例请求与结果
业务请求
业务响应
3 批量删除办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,批量同步删除办公地址 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/batch/delete |
method | address.batch.delete |
服务端超时时间 | 5秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.batch.delete | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressIds | List<Long > | 是 | [1004, 1005, 1006] | 删除地址,美团企业版地址id列表(限制最大size:50) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressDeleteResultItems | List<AddressDeleteResult > | 是 | 详见AddressDeleteResult字段说明 | 办公地址删除结果列表 |
AddressDeleteResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
result | Integer | 是 | 0 | 地址删除结果代码,详见状态码说明 |
message | String | 否 | 成功 | 地址删除错误描述 |
addressId | Long | 否 | 124 | 美团企业版地址id |
示例请求与结果
业务请求
业务响应
4 批量查询办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,从美团企业版批量查询办公地址 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/batch/query |
method | address.batch.query |
服务端超时时间 | 5秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.batch.query | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressIds | List<Long > | 是 | [1004, 1005, 1006] | 查询办公地址,美团企业版地址id列表(限制最大size:50) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressQueryResultItems | List<AddressQueryResult > | 否 | 详见AddressQueryResult字段说明 | 办公地址查询结果列表 |
AddressQueryResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressId | Long | 是 | 124 | 美团企业版地址id |
addressName | String | 是 | 望京国际研发园 | 地址名称 |
specificAddress | String | 是 | 北京市朝阳区望京东路6号 | 详细地址 |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息 |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识 |
provinceId | Long | 否 | 110000 | 省级id |
provinceName | String | 否 | 北京市 | 省级名称 |
cityId | Long | 否 | 110100 | 市级id |
cityName | String | 否 | 北京市 | 市级名称 |
districtId | Long | 否 | 110105 | 县区级ID |
districtName | String | 否 | 朝阳区 | 县区级名称 |
示例请求与结果
业务请求
业务响应
5 为办公地址批量绑定应用人群
接口说明
名称 | 描述 |
功能 | 企业通过该接口,为办公地址批量绑定应用人群(全员、部分人群) |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/relation/batch/bind |
method | address.relation.batch.bind |
服务端超时时间 | 10秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.relation.batch.bind | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressId | Long | 是 | 1004 | 美团企业版地址id |
effectiveForAllStaff | Boolean | 否 | true | 是否将地址绑定企业(true:全员生效,不允许再绑定员工、部门或者角色) |
staffIds | List<Long > | 否 | [2001, 2008] | 需要与地址绑定的美团企业版员工id列表(限制最大size:50) |
orgIds | List<Long > | 否 | [3001, 3008] | 需要与地址绑定的美团企业版部门id列表(限制最大size:50) |
tagIds | List<Long > | 否 | [4001, 4008] | 需要与地址绑定的美团企业版角色id列表(限制最大size:50) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
relationAddResultItems | List<RelationAddResult > | 是 | 详见RelationAddResult字段说明 | 办公地址绑定应用范围结果列表 |
RelationAddResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
result | Integer | 是 | 0 | 地址绑定结果代码,详见状态码说明 |
message | String | 否 | 成功 | 地址绑定错误描述 |
relationType | Integer | 是 | 1 | 地址应用人群类型(1:员工;2:部门;3:角色;4:全员) |
uniqueId | Long | 是 | 2001 | 美团企业版数据id(relationType: 1-美团企业版员工id;2-美团企业版部门id;3-美团企业版角色id;4-美团企业版企业id) |
示例请求与结果
业务请求
业务响应
6 为办公地址批量解绑应用人群
接口说明
名称 | 描述 |
功能 | 企业通过该接口,为办公地址批量解绑应用人群(解绑全员、解绑部分人群) |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/relation/batch/unbind |
method | address.relation.batch.unbind |
服务端超时时间 | 10秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.relation.batch.unbind | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressId | Long | 是 | 1004 | 美团企业版地址id |
cancellationEffectiveForAllStaff | Boolean | 否 | true | 是否解除地址与企业绑定(true:解除地址与企业的绑定) |
staffIds | List<Long > | 否 | [2001, 2008] | 需要与地址解除绑定的美团企业版员工id列表(限制最大size:50) |
orgIds | List<Long > | 否 | [3001, 3008] | 需要与地址解除绑定的美团企业版部门id列表(限制最大size:50) |
tagIds | List<Long > | 否 | [4001, 4008] | 需要与地址解除绑定的美团企业版角色id列表(限制最大size:50) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, List> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
relationDeleteResultItems | List<RelationDeleteResult > | 是 | 详见RelationDeleteResult字段说明 | 办公地址解绑应用范围结果列表 |
RelationDeleteResult
名称 | 类型 | 是否非空 | 示例 | 说明 |
result | Integer | 是 | 0 | 地址解绑结果代码,详见状态码说明 |
message | String | 否 | 成功 | 地址解绑错误描述 |
relationType | Integer | 是 | 1 | 地址应用人群类型(1:员工;2:部门;3:角色;4:全员) |
uniqueId | Long | 是 | 2001 | 美团企业版数据id(relationType: 1-美团企业版员工id;2-美团企业版部门id;3-美团企业版角色id;4-美团企业版企业id) |
示例请求与结果
业务请求
业务响应
7 分页查询办公地址绑定的应用人群
接口说明
名称 | 描述 |
功能 | 企业通过该接口,从美团企业版查询办公地址绑定的应用人群 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/relation/query/paged |
method | address.relation.query.paged |
服务端超时时间 | 5秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.relation.query.paged | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
addressId | Long | 是 | 1004 | 美团企业版地址id |
relationType | Integer | 否 | 1 | 地址应用人群类型(1:员工;2:部门;3:角色;4:全员) |
pageNo | Integer | 是 | 1 | 分页查询页码(从"1"开始) |
pageSize | Integer | 否 | 50 | 分页查询单次查询数据条数(限制单次最多查询50条) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, Object> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
pageNo | Integer | 是 | 1 | 分页查询页码 |
pageSize | Integer | 是 | 50 | 分页查询单次查询数据条数 |
totalSize | Integer | 是 | 103 | 符合查询条件的数据数量 |
pageCount | Integer | 是 | 3 | 分页总数 |
relationQueryResultItems | List<RelationQueryResult > | 否 | 详见RelationQueryResult字段说明 | 办公地址应用范围查询结果列表 |
RelationQueryResult
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressId | Long | 是 | 0 | |
relationType | Integer | 是 | 1 | 地址应用人群类型(1:员工;2:部门;3:角色;4:全员) |
uniqueId | Long | 是 | 2001 | 美团企业版数据id(relationType: 1-美团企业版员工id;2-美团企业版部门id;3-美团企业版角色id;4-美团企业版企业id) |
示例请求与结果
业务请求
业务响应
8 分页查询企业全量办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,可分页查询美团企业版维护的企业办公地址 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/get/all/paged |
method | address.get.all.paged |
服务端超时时间 | 5秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.get.all.paged | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
pageNo | Integer | 是 | 1 | 分页查询页码(从"1"开始) |
pageSize | Integer | 否 | 500 | 分页查询单次查询数据条数(限制单次最多查询500条) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<String, Object> | 否 | 详见data字段说明 | 请求结果数据 |
data字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
pageNo | Integer | 是 | 1 | 分页查询页码 |
pageSize | Integer | 是 | 50 | 分页查询单次查询数据条数 |
totalSize | Integer | 是 | 103 | 符合查询条件的数据数量 |
pageCount | Integer | 是 | 3 | 分页总数 |
addressQueryResultItems | List<AddressQueryResult > | 否 | 详见AddressQueryResult字段说明 | 办公地址查询结果列表 |
AddressQueryResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressId | Long | 是 | 124 | 美团企业版地址id |
addressName | String | 是 | 望京国际研发园 | 地址名称 |
specificAddress | String | 是 | 北京市朝阳区望京东路6号 | 详细地址 |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息 |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识 |
provinceId | Long | 否 | 110000 | 省级id |
provinceName | String | 否 | 北京市 | 省级名称 |
cityId | Long | 否 | 110100 | 市级id |
cityName | String | 否 | 北京市 | 市级名称 |
districtId | Long | 否 | 110105 | 县区级ID |
districtName | String | 否 | 朝阳区 | 县区级名称 |
示例请求与结果
业务请求
业务响应
9 查询不同应用人群绑定的办公地址
接口说明
名称 | 描述 |
功能 | 企业通过该接口,查询不同应用人群绑定的办公地址信息 |
HTTP方法 | POST |
请求方 | 第三方平台 |
响应方 | 美团企业版平台 |
url | $API_HOST/address/query/by/bind/ids |
method | address.query.by.bind.ids |
服务端超时时间 | 5秒 |
业务参数
名称 | 类型 | 是否必填 | 示例 | 说明 |
ts | Long | 是 | 1657852687 | 时间戳(单位:秒,请求有效期:10分钟) |
method | String | 是 | address.query.by.bind.ids | 方法名称 |
entId | Long | 是 | 1 | 美团企业版分配的企业id |
relationType | Integer | 是 | 1 | 地址应用人群类型(1:员工;2:部门;3:角色;4:全员) |
ids | List<Long > | 是 | [1004, 1005] | 绑定数据id列表(限制在50条内),与地址应用人群类型对应(1:员工id列表,2:部门列表,3:角色id列表,4:企业id) |
业务响应
名称 | 类型 | 是否非空 | 示例 | 说明 |
status | Integer | 是 | 0 | 请求结果代码,详见状态码说明 |
msg | String | 否 | 成功 | 请求结果描述 |
data | Map<Long, List<AddressQueryResult >> | 否 | {1004:[{"addressId":124, "addressName":"望京国际研发园"... ...}]} | 请求结果Map。 key:绑定数据id; value:绑定数据id对应的地址信息列表, 详见AddressQueryResult字段说明 |
AddressQueryResult字段说明
名称 | 类型 | 是否非空 | 示例 | 说明 |
addressId | Long | 是 | 124 | 美团企业版地址id |
addressName | String | 是 | 望京国际研发园 | 地址名称 |
specificAddress | String | 是 | 北京市朝阳区望京东路6号 | 详细地址 |
remarkName | String | 否 | 美团总部,或42层4201-4209单元 | 企业内部地址别名,或楼层&门牌号等补充信息 |
longitude | String | 是 | 116.488611 | 经度(限制最长为20个字符,坐标系为GCJ02) |
latitude | String | 是 | 40.006842 | 纬度(限制最长为20个字符,坐标系为GCJ02) |
outterId | String | 否 | A0923B23 | 企业侧地址唯一标识 |
provinceId | Long | 否 | 110000 | 省级id |
provinceName | String | 否 | 北京市 | 省级名称 |
cityId | Long | 否 | 110100 | 市级id |
cityName | String | 否 | 北京市 | 市级名称 |
districtId | Long | 否 | 110105 | 县区级ID |
districtName | String | 否 | 朝阳区 | 县区级名称 |
示例请求与结果
业务请求
业务响应