接口规则说明

环境准备

jdk
1.7.0_80-b15及以上版本使用。
接入URL地址
魔点平台：https://oapi.moredian.com
钉钉平台：https://toapi.moredian.com

接口规则

接口规则 相关描述
传输方式 仅支持HTTPS传输
URL格式 魔点平台https://oapi.moredian.com/uri；钉钉平台https://toapi.moredian.com/uri。每个API都有唯一的uri，详见API的接口定义
请求方式 GET/POST
数据格式 大部分请求和返回数据都为JSON格式，有部分请求接口是multipart/form-data。
字符编码 统一采用UTF-8字符编码
请求Headers HTTP请求中的头信息。大部分设置Content-Type:application/json，部分接口是multipart/form-data。
Header HTTP请求中的头信息中的一个键值对。
Path HTTP请求路径。如请求地址为https://oapi.moredian.com/app/getAppToken，则Path指"/app/getAppToken"。
Query 请求地址中的参数。如请求地址为https://oapi.moredian.com/app/getAppToken?appId=XXX&appKey=XXX，则Query为appId:XXX,appKey:XXX。
Body 指POST请求中body中以键值对存在的参数。

返回值规则

对于API接口调用返回的结果统一采用JSON格式，内容字段采用驼峰式方式命名，所有接口的返回结果里都有result、message，部分接口返回结果中没有data。返回的接口内容格式如下：

  1.     {
  2.           "result"://响应码
  3.           "message"://响应消息
  4.           "data"://响应数据
  5.         }

开发者需根据result是否为0判断是否调用成功，返回0表示成功，非0表示失败。message仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。data中返回接口具体内容。
开发者需要特别注意当data为null时的result，以便很好地理解接口返回的信息。
成功调用举例如下：

  1.    {
  2.           "result":"0",
  3.           "message":"操作成功",
  4.           "data":true
  5.         }

失败调用举例如下：

  1.  {
  2.           "result":"-1",
  3.           "message":"操作失败"
  4.         }

result为非0时都为错误码。错误码具体释义，参照附录错误码说明。

魔点开放平台SDK对接说明

SDK下载

魔蓝版API和钉钉版API分别提供了Java版本SDK供开发者使用，SDK下载：点击下载

开发概述

使用魔点提供的AppId，AppKey以及OrgId，OrgAuthKey（创建机构接口获取或者企业授权后获取）调用SDK对应Request获取token。

请求示例

以下为魔蓝版SDK调用API的请求示例，钉钉版SDK类似，替换接入URL地址即可：

  1. // 获取appToken，appToken有效期为返回data的expires，单位秒，过期后需再次获取
  2. IOpenApiClient client = new DefaultOpenApiClient(DefaultProfile.getProfile("https://oapi.moredian.com"));
  3. GetAppTokenRequest request = new GetAppTokenRequest();
  4. request.setAppId(AppId);
  5. request.setAppKey(AppKey);
  6. GetAppTokenResponse response = client.getResponse(request);
  1. // 获取ISV应用下accessToken，accessToken有效期为返回data的expires，单位秒，过期后需再次获取
  2. IOpenApiClient client = new DefaultOpenApiClient(DefaultProfile.getProfile("https://oapi.moredian.com"));
  3. GetAppOrgAccessTokenRequest request = new GetAppOrgAccessTokenRequest();
  4. request.setAppToken(appToken);
  5. request.setOrgId(OrgId);
  6. request.setOrgAuthKey(OrgAuthKey);
  7. GetAppOrgAccessTokenResponse response = client.getResponse(request);
  1. // 获取企业内部应用下accessToken，accessToken有效期为返回data的expires，单位秒，过期后需再次获取
  2. IOpenApiClient client = new DefaultOpenApiClient(DefaultProfile.getProfile("https://oapi.moredian.com"));
  3. GetOrgAccessTokenRequest request = new GetOrgAccessTokenRequest();
  4. request.setOrgId(OrgId);
  5. request.setOrgAuthKey(OrgAuthKey);
  6. GetOrgAccessTokenResponse response = client.getResponse(request);
  1. // 查询内部成员信息
  2. IOpenApiClient client = new DefaultOpenApiClient(DefaultProfile.getProfile("https://oapi.moredian.com"));
  3. GetMemberRequest request = new GetMemberRequest();
  4. request.setAccessToken(accessToken);
  5. GetMemberRequest.GetMemberRequestBody getMemberRequestBody = new GetMemberRequest.GetMemberRequestBody();
  6. getMemberRequestBody.setMemberId(1L);
  7. request.setBody(getMemberRequestBody);
  8. GetMemberResponse response = client.getResponse(request);

请求示例说明

1.定义Client对象，设置接口地址URL，Client只需要定义一次即可，其他API复用。

2.构造相关业务Request对象，对应业务的Request对象命名，一般使用驼峰形式+Request，具体请阅读SDK源码注释或者通过路径 “云端接口文档->请求参数->请求示例->Java” 查看。

3.Request对象设置业务参数，其中accessToken、appToken使用GetAppOrgAccessTokenRequest、GetOrgAccessTokenRequest、GetAppTokenRequest等Request对象获取。

4.调用client.getResponse获取执行结果，得到Response对象，与Request相对应。

钉钉开放平台对接

（1）开发者需要与钉钉开放平台对接，以第三方企业应用开发为例，具体操作可参照钉钉开放平台接入指南。https://open.dingtalk.com/document/isv/third-party-enterprise-application-description

（2）对接钉钉开放平台服务端API接口通讯录管理接口，获取基础信息，如用户ID，部门ID等信息。具体接口参照钉钉开放平台服务端API列表。https://open.dingtalk.com/document/isvapp-server/call-server-apis-3

文档更新时间: 2023-03-29 07:37   作者：liuqian