悦工作平台开放接口

悦工作

OPEN API

开放接口

1 接口约定

1.1 接口参数签名方法

为了开放接口不被恶意调用，在调用接口前，需要生成参数签名串。在签名过程中会使用到悦工作平台为企业生成的secret字符串（企业的secret由悦工作提供，可向悦工作索取。请妥善保管该值）；

假设请求如下接口：

https://open.ywork.me/api/gettoken?k3=v3&k2=v2&k1=v1&timestamp=14474756354

具体的签名方法如下：

将参数根据字母顺序从小到大排序并根据url格式进行拼接：
k1=v1&k2=v2&k3=v3×tamp=14474756354
在签名串前面加上请的接口URL全路径，不包括参数

url=https://open.ywork.me/api/gettoken&k1=v1&k2=v2&k3=v3×tamp=14474756354

在签名串后面加上企业自己的secret：
url= https://open.ywork.me/api/gettoken&k1=v1&k2=v2&k3=v3×tamp=14474756354&secret=secret
使用sha1加密得到签名字符串：
sha1得到签名串：signature
最终得到的请求链接如下：
https://open.ywork.me/api/gettoken?k3=v3&k2=v2&k1=v1×tamp=14474756354&signature=${ signature}

注：签名串一般都与时间戳相关，每次调用前需要重新生成，该签名串只能使用一次，即使被拦截后也无法再使用相同的参数进行操作；签名算法是公开的，请妥善保管自己的secret字符串。

1.2 数据加密

部分接口为安全性考虑，需要对数据进行AES加密，加解密KEY为MD5(secret)，所以请妥善保管secret.

1.3 接口调用频率

每个企业每个接口每分钟调用次数为1200次，超出将直接返回错误，拒绝提供服务。

1.4 文档术语

* 最小版本：指该接口或字段被支持的最低版本，低于该版本的API不存在该接口或字段；
* 最大版本：指该接口或字段被支持的最高版本，高于该版本的API不存在该接口或字段；
* ALL:表示所有版本都支持；

2 通用接口

2.1获取访问悦工作平台的access_token

请求地址

https://open.ywork.me/api/gettoken?corpid=id&timestamp=1423567845893&nonce=nonce&signature= signature&v=1.0

请求方式: GET
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

access_token是调用悦工作开放接口的唯一票据；AccessToken需要用CorpID来换取，不同的CorpID会返回不同的AccessToken。正常情况下AccessToken有效期为7200秒，有效期内重复获取返回相同结果（离过期时间小于5分钟时将生成新的Token,原Token在5分钟内还可以继续使用），请自行保存返回结果，并在快要过期时重新获取。

JSON参数
参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
corpid	String	是	1.0	ALL	企业id
timestamp	Long	是	1.0	ALL	调用该接口的时间戳（与服务器的时间只允许相差5分钟）
nonce	String	是	1.0	ALL	随机串，保证不能生成相同的的签名串
signature	String	是	1.0	ALL	参数签名串，不参与生成签名，生成方法见第1点，该签名串只能使用一次，再次调用需要重新生成
v	String	是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同

返回值

{
    "errcode": 0,
    "errmsg":  "ok",
    "access_token":"9123j2i13saopi30123",
    "expires_in":7200
}

参数名	参数类型	长度	必须	最小版本	最大版本	说明
errcode	Integer		是	1.0	ALL	错误码
errmsg	String		是	1.0	ALL	对错误码的描述
access_token	String	是		1.0	ALL	企业access_token
expires_in	Integer	是		1.0	ALL	企业access_token超时时间,单位为秒，默认有效时间为两小时

2.2 获取访问OSS的ACCESS_ID和ACCESS_KEY

请求地址

https://open.ywork.me/api/getosstoken?access_token=token&timestamp=1423567845893& nonce=nonce&signature=signature&v=1.0

请求方式: GET
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

客户端需要将附件（图片，文档等文件）直接上传到OSS中，然后将得到链接保存到业务表中；调用该接口获取到OSS访问ID和KEY，再调用OSS相关api进行附件上传。

JSON参数
参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
access_token	String	是	1.0	ALL	访问悦工作平台的access_token
timestamp	Long	是	1.0	ALL	调用该接口的时间戳（与服务器的时间只允许相差5分钟）
nonce	String	是	1.0	ALL	随机串，保证不能生成相同的的签名串
signature	String	是	1.0	ALL	参数签名串，不参与生成签名，生成方法见第1点，该签名串只能使用一次，再次调用需要重新生成
v	String	是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同

返回值

{
  "errcode":0,
  "errmsg":"ok",
  "data": “AES({
    ‘access_id’:’oss访问id’,
    ‘access_key’:’oss访问密钥’,
    'access_token':'oss访问临时token',
    'expiration'：token过期时间,
    'end_point': 'oss地址',
    'bucket':'oss bucket',
    ‘dir’：‘目录’
  }”)
}

参数名	参数类型	长度	必须	最小版本	最大版本	说明
errcode	Integer		是	1.0	ALL	错误码: 0：成功；1：接口错误
errmsg	String		是	1.0	ALL	对错误码的描述
data	String		是	1.0	ALL	对结果进行AES加密后的数据
access_id	String		是	1.0	ALL	oss访问id
access_key	String		是	1.0	ALL	oss访问密钥
access_token	String		是	1.0	ALL	oss访问临时token
expiration	long		是	1.0	ALL	token过期时间
end_point	String		是	1.0	ALL	oss上传地址
bucket	String		是	1.0	ALL	OSS bucket，大多数的接入企业是相同的
dir	String	是		1.0	ALL	有权限操作的OSS bucket下的子目录，每个企业不同

2.3 请求oauth2.0验证信息输入页面

请求地址

https://open.ywork.me/api/oauth2/user/login?access_token=token&v=1.0&callbackurl=CALLBACKURL&display=PC&appid=APPID

请求方式: GET
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

悦工作平台oauth2.0接口之一。当企业发起oauth认证请求时，在无法得到被认证用户相关数据情况下，需要跳转到指定页面，供用户输入验证相关验证数据，如用户名，密码等；该页面由悦工作平台提供。

JSON参数
参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
access_token	String	是	1.0	ALL	访问悦工作平台的access_token
v	String	是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同
callbackurl	String	是	1.0	ALL	企业回调地址，请进行编码；整个认证过程都将使用该页面来传递相关数据到企业应用中
display	String	是	1.0	ALL	“pc”:PC版登陆页；"mobile"：移动版登陆页
appid	Int	是	1.0	ALL	服务商应用在悦工作平台唯一的ID(联系运营人员获取)

返回值

如果请求企业有权调用该接口，则直接转向认证数据输入页面，否则转向企业回调页面，其中包含相关错误信息，如callback?errcode=400004;认证成功会向回调地址中追加code参数，请使用该参数调用2.4接口换取用户身份。

2.4 通过临时code换取用户身份

请求地址

https://open.ywork.me/api/oauth2/user/get?access_token=token&code=CODE&v=1.0

请求方式: GET
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

悦工作平台oauth2.0接口之一，通过临时验证码换取用户身份信息；code为通过其它方式验证身份成功后生成的临时认证码，5分钟内有效，当企业应用使用此code换取一次用户信息后立即失效，所以调用方必须保证整个过程的可靠性，否则必须重新认证。

JSON参数
参数列表

参数名	参数类型	长度	必须	最小版本	最大版本	说明
access_token	String		是	1.0	ALL	访问悦工作平台的access_token
code	String	32	是	1.0	ALL	通过oauth2.0认证成功后产生的临时认证code
v	String		是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同

返回值

{
  "errcode":0,
  "errmsg":"ok",
  "data": {
             "corpId":"corpId",
             "userId":"userId",
             "userName":"userName"
          }
  }

参数名	参数类型	必须	最小版本	最大版本	说明
errcode	Integer	是	1.0	ALL	错误码: 0：成功；1：接口错误
errmsg	String	是	1.0	ALL	对错误码的描述
data	JSON	是	1.0	ALL	包含用户身份信息的对象
corpId	String	是	1.0	ALL	认证用户所在企业ID
userId	String	是	1.0	ALL	用户在企业中的登陆名
userName	String	是	1.0	ALL	认证用户名称

3 第三方服务商接口

3.1 获取访问授权企业数据接口的app_acc_token

请求地址

https://open.ywork.me/api/getauthtoken?access_token=token&auth_code=code&timestamp=1423567845893& nonce=nonce&signature=signature&v=1.0

请求方式: GET
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

悦工作第三方服务商在调用悦工作中企业数据的接口前，必须先获取该企业的授权访问token,该token可通过企业授权码到悦工作平台换取；正常情况下AccessToken有效期为7200秒，有效期内重复获取返回相同结果，请自行保存返回结果，并在快要过期时重新获取。

JSON参数
参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
access_token	String	是	1.0	ALL	服务商访问悦工作平台的access_token,可以通过2.1接口获取
auth_code	String	是	1.0	ALL	企业在悦工作开通应用后生成的授权码（该授权码目前只能由企业管理员提供给第三方服务商）
timestamp	Long	是	1.0	ALL	调用该接口的时间戳（与服务器的时间只允许相差5分钟）
nonce	String	是	1.0	ALL	随机串，保证不能生成相同的的签名串
signature	String	是	1.0	ALL	参数签名串，不参与生成签名，生成方法见第1点，该签名串只能使用一次，再次调用需要重新生成
v	String	是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同

返回值

{
  "errcode":0,
  "errmsg":"ok",
  "access_token":"9123j2i13saopi30123",
  "expires_in":7200
}

参数名	参数类型	必须	最小版本	最大版本	说明
errcode	Integer	是	1.0	ALL	错误码
errmsg	String	是	1.0	ALL	对错误码的描述
access_token	String	是	1.0	ALL	企业access_token
expires_in	Integer	是	1.0	ALL	企业access_token超时时间,单位为秒，默认有效时间为两小时

4 通讯录接口

4.1 获取部门列表

4.2 增量获取部门列表

4.3 获取部门详情

4.4 获取部门人员成员列表

4.5 获取部门人员成员列表（详情）

4.6 获取人员详情

5 第三方系统接入接口

5.1 单点登陆

请求地址

http://第三方系统单点登陆地址/yworksso?reqtype=XXX&agentid=XXX&key=XXX&v=1.0

请求方式: POST
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述

    该接口由悦工作平台接入方提供，是悦工作平台根据业务需求进入接入方系统的统一入口，与业务相关的数据经加密后通过参数(key)传入到接入方系统中，接入方根据接收的参数执行对应的业务处理，悦工作平台不需要关心接入方的具体业务实现，只会传入必要的参数信息（如登入人员信息等），接入方必须返回接收成功的相关数据。

JSON参数
参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
reqtype	Integer	是	1.0	ALL	请求类型，具体说明请参照“reqtype参数说明”
agentid	Integer	否	1.0	ALL	在悦工作平台私有系统接入的自定义应用中查看，与加密数据相关
key	String	是	1.0	ALL	请求SSO的加密数据
v	String	是	1.0	ALL	接口版本，当前版本为：1.0

reqtype参数说明

reqtype	说明
0	普通请求,普通性的SSO请求，悦工作平台大部请求都属于此种类型
1	验证性请求,主要用于悦工作平台验证接入方是否正确接入了平台，包括验证密钥，数据加密算法等。悦工作向接入方推送数据（即url中key的值）格式为： {"encrypt":"xxxxx"}，其中encrypt的值为加密数据，接入方需要先将其值进行解密（解密验证）得到JSON串{"random":"xxxxx"}，再将random的值进行加密（加密验证）返回到悦工作平台，返回数据格式为：{"data":"加密后的random值", errcode:0, errmsg:"OK"}

Key加密参数说明（具体内容因reqtype而异）

{
  "uid": "SSO用户ID",
  "params": "与消息相关的数据，原样返回",
  "innerParams": "对于图文消息，每条图文相关的数据，原样返回",
  "msgId": "接入方的消息ID"
}

参数名	参数类型	必须	最小版本	最大版本	说明
uid	String	是	1.0	ALL	用户ID
params	String	是	1.0	ALL	与消息相关的数据，原样返回
innerParams	String	是	1.0	ALL	对于图文消息，每条图文相关的数据，原样返回
msgId	String	是	1.0	ALL	接入方的消息ID

返回值

{
  "errcode":0,
  "errmsg":"ok",
  "data":"data"
}

参数名	参数类型	必须	最小版本	最大版本	说明
errcode	Integer	是	1.0	ALL	错误码
errmsg	String	是	1.0	ALL	对错误码的描述
data	String	是	1.0	ALL	根据reqtype不同，返回的数据内容及格式不同

5.2 消息发送

请求地址

https://open.ywork.me/api/message/send?access_token=token&msgType=Text&v=1.0

请求方式: POST
最小版本: 1.0
最大版本: ALL
接口版本: 1.0
描述
JSON参数

{
  "messageBody": {
    "messageType": "Text",
    "text": "这是一条待办消息"
  },
  "targets": [
    {
      "determinTargetMethod": "SpecifyPlatform",
      "messageTargetPlatform": "QyWechat",
      "agentId": 2
    },
    {
      "determinTargetMethod": "SpecifyPlatform",
      "messageTargetPlatform": "DingDing",
      "agentId": 3
    },
    {
      "determinTargetMethod": "SpecifyModule",
      "modulePath": "/km/review"
    }
  ],
  "msgId": "14a2c3d45b7f23a12e43d123",
  "allUser":true,
  "userIds": ["U001", "U002"],
  "deptIds": ["d001","d002", "d003"],
  "senderId": "001",
  "senderName": "李世民",
  "sendtime": 1423468922578
}

参数名	参数类型	必须	最小版本	最大版本	说明
messageBody	JSON	是	1.0	ALL	消息体，与messageBody.messageType相关，不同的类型，消息结构不同，详见下面的消息体说明
messageBody.messageType	String	是	1.0	ALL	悦工作消息类型，不同类型的消息结构不同
targets	Array	否	1.0	ALL	消息发送的目标平台列表，不指定发送到默认的应用中
targets.determinTargetMethod	String	否	1.0	ALL	确定接收消息的平台的方式：SpecifyPlatform - 指定平台，SpecifyModule - 根据模块标识路径自动识别
targets.messageTargetPlatform	String	否	1.0	ALL	当targets.determinTargetMethod设置为SpecifyPlatform时的平台类型：QyWechat - 微信企业号，DingDing - 钉钉， MpWeChat - 微信服务号
targets.agentId	String	否	1.0	ALL	当targets.determinTargetMethod设置为SpecifyPlatform时，对应平台的应用ID
targets.modulePath	String	否	1.0	ALL	当targets.determinTargetMethod设置为SpecifyModule时的模块路径标识
msgId	String	否	1.0	ALL	私有系统内部消息ID
allUser	Boolean	否	1.0	ALL	是否将消息发给全公司员工，当设置为true时将忽略userIds和deptIds列表
userIds	Array	否	1.0	ALL	消息接收用户ID列表，为接入方内部用户ID（如EKP的loginName），悦工作平台自动将其转换成对应平台的ID，不能与deptIds同时为空
deptIds	Array	否	1.0	ALL	消息接收部门ID列表，为接入方内部部门ID，悦工作平台自动将其转换成对应平台的ID，不能与userIds同时为空
senderId	String	否	1.0	ALL	发送消息的接入方内部ID
senderName	String	否	1.0	ALL	发送消息人员名称
sendtime	long	是	1.0	ALL	消息发送时间

messageType对应的消息体结构
悦工作文本消息(Text)

  {
    "messageType": "Text",
    "params": "与当前消息相关的数据",
    "text": "这是一条文本消息"
  }

悦工作图片消息(Image)

  {
    "messageType": "Image",
    "params": "与当前消息相关的数据",
    "url": "这里应该是图片的URL"
  }

悦工作图文消息(ImageText)

{
    "messageType": "ImageText",
    "params": "与当前消息相关的数据",
    "yworkArticles": [
      {
        "title": "图文消息标题",
        "description": "图文描述内容",
        "params": "与当条图文消息相关的数据",
        "picurl": "当条图文的图片URL"
      },
      {
        "title": "图文消息标题",
        "description": "图文描述内容",
        "params": "与当条图文消息相关的数据",
        "picurl": "当条图文的图片URL"
      }
    ]
  }

参数列表

参数名	参数类型	必须	最小版本	最大版本	说明
access_token	String	是	1.0	ALL	访问悦工作平台的access_token,可以通过2.1接口获取
msgType	String	是	1.0	ALL	消息类型：文本(Text)、图片(Image)、图文(ImageText)
v	String	是	1.0	ALL	接口版本号，用于升级扩展接口，默认为1.0，不同版本的接口返回的内容有可能不同

返回值

{
  "errcode":0,
  "errmsg":"ok",
  "data":"14a2c3d45b7f23a12e43d123"
}

参数名	参数类型	必须	最小版本	最大版本	说明
errcode	Integer	是	1.0	ALL	错误码
errmsg	String	是	1.0	ALL	对错误码的描述
data	String	是	1.0	ALL	悦工作平台保存消息后的ID，使用该值可以查询消息处理状态

说明

1.　返回errcode为0时，仅代表悦工作平台已成功收到来自第三方系统的消息发送请求，且请求数据符合悦工作平台所要求的格式，不代表消息实际是否发送成功。 
2.　如需要指定具体的消息详情页面地址，请在params参数中自行指定。悦工作平台在请求第三方系统SSO接口时原样返回此参数。

6 全局返回码说明

企业每次调用接口时，可能获得正确或错误的返回码，企业可以根据返回码信息调试接口，排查错误。

返回码	说明
30001	已超出系统规定时间内访问次数
40001	不合法请求
40002	请求时间戳已超时
40003	请求客户端地址不在白名单内
40004	非法签名请求
40005	不合法请求
40006	不合法的corpid
40007	不合法的access_token或已过期
40008	缺失请求参数
40009	不存在的SP企业
40010	不存在的授权信息(请检查企业授权码)
40011	不存在的企业OSS服务器信息
40012	不存在的企业信息
50000	服务内部错误
60000	回调地址不合法
60001	不合法的code或已过期
60002	OA身份验证失败
60003	不合法的企业代码或域名
60004	未开启OA登陆服务