• 组织API（对组织的增删改）

一. 数据模型(*为必填字段)

特殊说明:

1. 企业内“组织编码”全局唯一;相同上级组织编码下的直接子组织“组织名称”不允许重复。

2. “省市区”3个地址字段和“详细地址信息字段”不能同时为空。否则会报错误码:10227、10228、10229。 

3. 表格中分拨中心细分项：300 转运中心 11 分拨中心 302 航空部 303 中转部 304 枢纽 350 集散中心 351 集散仓 352 集货点 353 接驳点 354 集配站 355 运作部

二. API接口(通过LINK提供)

特殊说明:

1. “更新组织”接口时,如果“上级组织编码”字段的入参值与当前值不一致,将会把组织移动到新的上级之下。

2. 更新或创建时,上级组织编码必须在菜鸟已存在。

3. 重复创建相同“组织编码”的组织,以第一个次请求为准。

4. “省市区”三个字段和“详细地址信息”字段不能同时为空。“省市区”需要整体输入,要么都输入,要么都不输入,否则会api报异常。

5. 更新或者删除组织时,以“组织编码”或者“deptId”作为组织的唯一标识。组织编码不允许更新。

6. 删除组织前,需要自行先删除或迁移完该组织下的所有账号(确保该组织是无人态),并且删除组织下的直接子组织,删除组织下的分组。

7. 组织类型目前有9种,如下:

总部:指快递公司总部

分拨中心:指中转中心

片区:管理部门,非行政区域,管理范围大于一个行政省

省区:管理部门,非行政区域,小于或等于一个省大于一个城市

市区:管理部门,非行政区域,管理范围小于等于一个市,大于一个区县

县区:管理部门,非行政区域,管理范围小于等于一个区县,大于1个网点

网点:有独立揽派业务,和快递公司直接签署加盟合同的,具备独立法人地位的公司,也叫做一级网点或分公司

承包区:有独立揽派业务,网点公司的下属所有分支机构,和快递公司没有直接加盟关系的

特别说明:如果组织类型跟您公司的组织类型定义有出入,直接在钉钉群联系菜鸟业务同学@姜橙 @泠弦。

 

• 账号API（对员工账号的增删改查）

一. 数据模型

概念解释: 职能(务)(有些快递公司叫:职务/岗位):

职能:此处职能是指人员所在的部门,比如“客服”指人员所在部门为客服部的,或人员所任职的岗位, 比如“小件员”指人员所担任的岗位。此处务必注意:接下来菜鸟天地页面权限管理, 会支持按“职能”进行一次性初始化配置,尽量将人员的职能精准化,否则人员权限与实际业务需要不符,会有大量繁琐的管理工作, 每个员工有一种核心的职能(比如:张三是 质控职能部门的员工,那么他的职能就是“质控”, 如果他是网点的小件员,那么他的职能 就是“小件员”)。

特殊说明:

1. 当前支持1~9种职能,如果不满足需求(少了某些职能类型 或 修改某些职能类型名称)则请联系菜鸟的同学 @姜橙 @泠弦。 职能类型值解释:

1: 小件员:负责揽件、 货点取待派货物和货物的装卸,及时对货物进行初步检验和交接

3: 财务:为企业财务管理体系负责,开展日常财务管理、财务预算、资金运作等各项工作

4: 营运:负责干线车辆及转运中心建设、维护及优化工作及路由规划

5: 客服:受理散客下单、客户咨询、查件、投诉等工作

6: 网管:负责末端网点准入准出、奖罚及日常管理

7: IT: 负责内部系统开发

8: 市场:负责大型客户开发、服务及公司整体营销策略制定

22: 质控:根据数据对整体网络质量/服务质量进行监控

99: 其他:无法映射到前面几种职能的，全部映射到 99

2.帐号类型：

1) 公司管理员:只有总部这个组织类型,才有的帐号类型,由菜鸟在系统初始设立, 一般限定1-2个人(此处务必注意!!公司管理员数量过多,容易造成大量管理混乱,数据安全风险也比较高);

2) 组织负责人:组织(例如:省区、网点、承包区等)的业务第一负责人,一般是省区总经理、网点老板、网点总经理、承包区老板。 注释:组织负责人,同时在菜鸟天地系统里拥有组织及帐号的管理页面(可以新建、更改、删除组织和人员信息)

3) 组织系统管理员:在菜鸟天地系统里拥有组织及帐号的管理页面(可以新建、更改、删除组织和人员信息)

4) 职能(务)负责人:“职能”这个部门的管理负责人,比如:一般职能为“客服”的部门, 职能(务)负责人为客服总监、客服总经理。 注释:未来,职能负责人同时在菜鸟天地系统里,可以管理自己职能部门内其他人员的人员信息管理

说明：人员的新增、更改、删除和人员的权限的新增、更改、删除

------比如: 总部的质控部门的总经理、副经理、总监 就是该质控部门的负责人;

------比如:总部的质控负责人“李四”(假设他自己拥有10个权限) 可以调整总部质控部门员工 “张三” 的权限(调整范围<=10);

二. API接口(通过LINK提供)

特殊说明:

1. 员工更新或者删除账号时,以“员工工号”或者“accountId”作为员工的唯一标识。员工工号不允许更新。
2. 创建账号接口调用成功后,会给账号关联的手机号发送短信。
3. 更新账号接口中,“员工所属组织编码”字段的入参值与当前值不一致时,将会把员工帐号移动到新的组织之下。

 

• 免登API（从CP内部系统进入菜鸟天地） 

一. 免登交互流程，其中红色的请求需要CP实现：

获取令牌(loginToken)：

LINK接口名称：CNUSER_GET_LOGIN_TOKEN

请求参数:员工工号

返回参数:loginToken

二. 对接方式：

PC版:

1. 生成快速登录菜鸟的URL,并从浏览器发起302跳转 https://login.cainiao.com/cplogin.htm?loginToken=2nAiCDsSZVXBS8kLApj9iA&amp;redirectUrl=https%3a%2f%2ffly.cainiao.com

2:登陆后的目标跳转地址。如菜鸟天地的地址为:https%3a%2f%2ffly.cainiao.com login_token:菜鸟返回的令牌(注意:login_token使用一次后即失效,且LINK接口返回起60秒后超时失效)。

无线版:

1. 生成快速登录菜鸟的URL,并从浏览器发起302跳转 https://login.cainiao.com/cplogin.htm?loginToken=2nAiCDsSZVXBS8kLApj9iA&amp;redirectUrl=https%3a%2f%2fm.fly.cainiao.com

2:登陆后的目标跳转地址。如菜鸟天地的地址为:https%3a%2f%2fm.fly.cainiao.com login_token:菜鸟返回的令牌(注意:login_token使用一次后即失效,且LINK接口返回起60秒后超时失效)。

三. 历史数据处理

对接后:

1. 历史人员账号数据通过“员工工号”关联 无员工工号的账号,会首先通过手机号码进行匹配,如果该手机号码存在对应帐号,则匹配成功

2. 历史组织组织数据通过“组织编码”关联

 

• LINK接入知识和常见问题

一. 接入LINK：

1. 请求的通用参数 详见LINK的对接文档,使用LINK二方包的CP可忽略此实现细节(appkey,以及对应的appsecret参数摘要)。 LINK接入文档参见:http://pac.i56.taobao.com/portal/portalDoc.htm?id=107，LINK SDK包参见:http://pac.i56.taobao.com/portal/portalDoc.htm?id=19

2. 请求的公共返回 errcode:异常码，errmsg:对返回码的文本表述内容

二. LINK对接常见问题：

1. 提示测试环境找不到订阅信息 解决方案:联系菜鸟开发@梁丰,根据appkey配置订阅关系。appkey和cpCode 1:1匹配

2. 返回错误信息:{“服务路由失败:Service route failed without any goal. Input condition is: xxxx”} 解决方案:联系菜鸟开发@梁丰,配置默认路由

3. 返回错误信息:{“服务 供商返回为NULL”} 解决方案:LINK网关的问题,将日常网关改为http://linkdaily.tbsandbox.com/gateway/link.do

4. 返回错误信息:{"success":"false","errorCode":"10310","id":"-1","errorMsg":"系统繁忙"} 解决方案:联系菜鸟PAC开发,确认是否fromCode是否在日常环境被调整了

5. 返回错误信息:{"success":"false","errorCode":"10411","id":"-1","errorMsg":"查询企业信息不存在"} 解决方案:确认fromCode对应的企业在调试前已经创建完成, 供fromCode给菜鸟开发@梁丰,确认企业信息。

6. 返回错误信息:{"success":false,"errorCode":"S02","errorMsg":"验签或加密失败:digist sign check not pass"} 解决方案:这个错误一般是签名错了,先检查下所有的参数类型是否正确(是不是有数字类型的传了字符串等等), 如果还未解决,则先使用工具MD5签名算法说明 中的样例先算下签名是否正确,再修改编码和SecretKey到正确的值进行请求。