美团企业版开放平台

# 部门保存接口

# 1.概述

批量部门保存接口，如果部门不存在则新增部门，如果部门存在则更新部门，更新部门时如果字段为null则不更新对应字段，非null时则更新，单次调用最大保存部门数量为50

# 2.接口基本信息

名称 描述
请求方式 POST
调用地址 测试环境：https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/org/batch/save
正式环境：https://bep-openapi.meituan.com/api/sqt/open/org/batch/save
调用方 客户平台
响应方 美团企业版
响应超时时间 5秒
调用限频 每分钟访问不超过100次，每天累计访问不超过100000次

# 2.1.请求体

名称 类型 是否必填 示例 说明
accessKey String 是 美团企业版分配给客户的接入秘钥
content String 是 UgxoCGPQIzoP 请求体内容，将请求参数JSON序列化后进行加密的结果值，
参照：签名实例

# content加密前数据结构

名称 类型 是否必填 示例 说明
ts Long 是 1617085650321 13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId Long 是 46574 企业ID
orgInfoList List<OrgInfo> 是 见OrgInfo 部门信息列表，部门数量需<=50

OrgInfo字段说明

名称 类型 是否必填 示例 说明
orgId Long 否 1 部门id，美团侧对部门的唯一标识，更新部门时orgId与externalOrgId必传其一
externalOrgId String 否 code11 部门编码，企业侧对部门的唯一标识，美团侧会进行存储，新增部门时必传。要求：编码不重复，不超过128个字符，不包含“表情”符号
orgName String 否 美团 部门名字，不允许存在英文字符"-"和","，新增部门时必传
parentOrgId Long 否 0 父部门id，美团侧对部门的唯一标识，如果上级部门是公司填0，新增部门和更新上级部门时，parentOrgId和parentExternalOrgId必传其一
parentExternalOrgId String 否 code11 父部门唯一编码，企业侧对部门的唯一标识

# 2.2.响应参数

名称 类型 是否必填 示例 说明
traceId String 是 56a0af18ae30a168d4006c7c 日志查询ID，用于排查问题
status Integer 是 0 接口响应编码，编码枚举值和解决方案详见第四章错误码
msg String 否 错误描述信息，如部门数量太多
data String 是 UgxoCGPQIzoP 响应数据，将响应参数JSON序列化后进行加密的结果值，解密秘钥使用secretKey参数

# data解密后数据结构

类型 是否必填 示例 说明
List<OrgSaveResultItem> 是 见OrgSaveResultItem 返回结果

OrgSaveResultItem字段说明

名称 类型 是否必填 示例 说明
result Integer 是 0 针对每个部门保存结果的响应编码，编码枚举值和解决方案详见第四章错误码
itemMsg String 否 同步单个部门失败的描述信息
orgId Long 是 1 部门id，美团企业版对部门的唯一标识
externalOrgId String 否 code1 部门编码，企业侧对部门的唯一标识

# 3.示例

# 3.1.请求示例

# 3.1.1.请求示例

{
  "accessKey":"B3KSWLDSKSKDMJ",
  "content":"UgxoCGPQIzoP"
}

# 3.1.2.请求参数content解析

{
  "ts": 123123,
  "entId": 100746,
  "orgInfoList": [
    {
      "externalOrgId": "code1",
      "orgName": "部门名字",
      "parentOrgId": 0
    },
    {
      "externalOrgId": "code1",
      "orgName": "新部门名字",
      "parentOrgId": 1
    },
    {
      "externalOrgId": "code1",
      "parentOrgId": 2
    }
  ]
}

# 3.2.响应示例

# 3.2.1.响应结果

{
    "traceId":"56a0af18ae30a168d4006c7c",
    "status": 1,
    "msg":"部门同步失败",
    "data":"UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP"
}

# 3.2.2.响应参数data解析

[
    {
      "result": 0,
      "orgId": 1
    },
    {
      "result": 1,
      "itemMsg": "部门名字格式错误"
    }
]

# 4.错误码

# 4.1.status错误码

错误码 错误描述 解决方案
10010002 企业已停止合作，请联系客户经理进行确认 将接口调用的entId参数给到客户经理，由客户经理确认企业状态是否在合作中
10010003 content不合法 详细阅读content参数加密说明（签名实例），确认content加密方式和content解密前传参是否正确
10010004 ts缺失或ts时间已过期 确认ts是否传值并为13位时间戳，如果正确传值，则确认请求发起时间与美团企业版接受请求的时间差是否超过10分钟
10010005 entId不能为空 entId参数不可为空，如果未拿到entId参数，可以咨询客户经理获取
20010001 accessKey不合法 检查accessKey是否为客户经理给到的值，如果accessKey值正确，确认调用环境是否和accessKey一致，如使用测试环境的accessKey调用线上的接口
20010002 请求path不合法 检查接口调用地址是否正确，如是否有非法字符
20010003 鉴权失败，无接口访问权限 将接口调用地址给到客户经理，由客户经理检查接口权限是否开通并保存成功
20010004 越权访问，无法访问该企业数据，请检查entId的正确性 检查accessKey和entId两个参数的对应关系是否正确
30010001 访问频率过高 请确认接口访问频率，每个接口默认调用限频为每分钟不超过100次，超出调用频率会调用此错误
30010002 访问次数超过配额 请确认接口的累计访问次数，每个接口的默认累计调用量为10w次，超出限额则会报错
10080001 传入部门数量超出限制 请检查传入部门数量，部门保存接口单次同步部门数量不可超过50个
10080003 部门id和外部部门id为空 请检查orgId和externalOrgId字段是否传值，新增部门时，externalOrgId字段必传，更新部门时，orgId和externalOrgId二者必传其一
10080006 xx字段传值异常，数据类型不匹配 请检查字段传值情况，如:是否出现Integer类型字段传值'aaa'
10081001 传入部门为空 请检查orgInfoList字段是否为空对象
40080000 部分部门处理失败 请查看响应结果中的result和itemMsg信息，根据解决方案进行调整
40080001 未知错误，请联系美团侧研发 请提供响应结果中的traceId参数，联系客户经理进行排查

# 4.2.result 错误码

错误码 错误描述 解决方案
10081002 父部门不存在 请检查parentOrgId和parentExternalOrgId传值是否正确，且已经在美团企业版企业后台-组织架构菜单中存在，父部门需提前同步
10081003 orgId对应部门不存在 请检查orgId对应的部门是否存在，如不存在，无法更新
10081004 externalOrgId企业内重复 请检查企业内是否有重复externalOrgId，如有重复，请进行调整
10081005 部门名称不允许含有英文连接符“-”以及英文的“,”，请修改部门名称！ 请检查orgName字段传值，部门名称不允许含有英文连接符“-”以及英文的“,”
10081006 父部门为自己 请检查parentOrgId字段传值是否与orgId相同，或者parentExternalOrgId字段传值与externalOrgId相同，如无父部门，parentOrgId传值为0
10081007 部门名字为空 请检查orgName字段传值，新增部门时，orgName字段必传

# 5.代码实例

依赖SDK包地址：SDK下载地址

import com.meituan.sqt.client.SqtClient;
import com.meituan.sqt.constant.CommonConstants;
import com.meituan.sqt.enums.ResponseStatusEnum;
import com.meituan.sqt.exception.MtSqtException;
import com.meituan.sqt.request.in.org.OrgSaveRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.org.OrgSaveResultItem;

import java.util.Collections;
import java.util.List;
import java.util.Objects;

/**
 * @description: 部门信息保存请求示例代码
 * @author: xinghaiming@meituan.com
 * @data: 2023/4/11 16:51
 */
public class OrgSaveDemo {
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/org/batch/save";

    private static SqtClient sqtClient = null;

    static {
        // 初始化SqtClient，只需要初始化一次即可
        // entId，accessKey，secretKey需要根据不同环境动态的设置获取
        sqtClient = new SqtClient.Builder()
                .setEntId(CommonConstants.entId)
                .setAccessKey(CommonConstants.accessKey)
                .setSecretKey(CommonConstants.secretKey)
                .build();
    }

    public static void main(String[] args) throws MtSqtException {
        // 1. 构建请求对象
        // 1.1 设置通用参数
        OrgSaveRequest orgSaveRequest = new OrgSaveRequest();
        orgSaveRequest.setTs(System.currentTimeMillis());
        orgSaveRequest.setEntId(sqtClient.getEntId());
        // 1.2 封装需要保存的部门信息
        OrgSaveRequest.OrgInfo orgInfo = new OrgSaveRequest.OrgInfo();
        orgInfo.setOrgName("市场部");
        orgInfo.setExternalOrgId("ORG002");
        orgInfo.setParentExternalOrgId("ORG001");
        orgSaveRequest.setOrgInfoList(Collections.singletonList(orgInfo));
        // 2. API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<OrgSaveResultItem>> response = sqtClient.invokeApi(invokeUrl, orgSaveRequest, null, null);
        // 3. 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

        }
        // 4. 获取请求结果
        if(Objects.equals(ResponseStatusEnum.SUCCESS.getCode(), response.getStatus())) {
            // 4.1 请求成功获取部门保存结果,处理请求成功场景
            List<OrgSaveResultItem> resultItemList = response.getRealData();

        } else {
            // 处理请求失败场景
            handleRespFailResult(response);
        }
    }

    private static void handleRespFailResult(BaseApiResponse<List<OrgSaveResultItem>> response) {
        // 访问频率过高
        if (ResponseStatusEnum.HIGH_FREQUENCY_ACCESS.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 访问次数超过配额
        if (ResponseStatusEnum.EXCEED_ACCESS_NUMBER.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 其它失败场景，解决方案参考：https://h5.dianping.com/app/bep-docs/open-platform-doc/org/org_save.html#_4-%E9%94%99%E8%AF%AF%E7%A0%81

    }
}

# 6.版本记录

版本号 版本日期 更新内容
v1.0 2022-10-28 新增部门保存接口
v1.1 2023-11-09 新增错误码(10080006:字段传值异常，数据类型不匹配)
上次更新: 6/29/2026, 7:56:38 PM

← 部门删除 →