纷享开放平台(Open API)

红雪
338 阅读8分钟

企业内部应用开发

接口在线调试: open.fxiaoke.com/apitools.ht…

开发流程介绍

企业内部应用是企业基于纷享开放平台提供的开放能力，开发定制化的应用提供给企业内部使用。例如可以方便与企业 IT 系统（如：ERP、财务、HR、客服等）集成，实现业务数据获取和插入。

接入步骤

  1. 第一步：创建企业自建应用
  2. 第二步：获取CorpAccessToken
  3. 第三步：对CorpAccessToken做缓存处理
  4. 第四步：开发对接逻辑

第一步: 创建企业自建应用

image.png

第二步: 获取AccessToken和corpId

CorpAccessToken是企业应用访问相应公司数据的全局唯一票据，拉取信息和发送消息的接口都需要携带CorpAccessToken和CorpId。正常情况下CorpAccessToken的有效期为7200秒，有效期内重复获取返回相同结果。

第三步: 对AccessToken做缓存处理

每个 accessToken 的有效期为7200秒（2小时），有效期内重复获取返回相同结果。所以为了防止因为频率调用次数超出限制而影响功能正常使用的问题，建议开发者将中间生成的 AccessToken  进行缓存，过期以后再重新获取。

第四步: 获取openUserId

CRM相关接口需要传入接口调用者的身份（currentOpenUserId ） 参数，调用接口时会使用该用户的权限进行获取有权限的数据。如果是需要获取企业的所有数据则可以使用CRM管理员的openUserId**（CRM管理员具备所有功能/数据权限），或者在CRM中把该用户设置对应的数据权限。

第五步: 开发对接逻辑

开发对接程序前，请务必先查看接口调用说明：接口调用说明。

常见应用接入能力

企业内部应用免登： 在纷享上开发的企业内部应用，可以通过该方式无需输入账号密码即可直接登录该内部应用。

纷享免登： 提供了使用第三方系统账号登录纷享的能力。

事件更变订阅： 用户可以通过在纷享侧订阅事件的方式，来监听数据的变化，从而能够以一种很轻量级的方式就能达到几乎近实时的数据同步的效果。

创建应用

1. 创建自建应用

2. 自建应用开启开发模式

参数解释

image.png

接口调用说明

接口说明

接口地址需根据企业所在云选择

       纷享云 ：open.fxiaoke.com

       华为云 ：open-hwcloud.fxiaoke.com      

       双胞胎 ：open-crm.sbtjt.com      

       金山云 ：open-fxcrm.ksyun.com      

       紫光云 ：open-crm.unicloudea.com      

       鲲鹏云 ：open-hws.fxiaoke.com

       钉钉云 ：open-ale.fxiaoke.com

字符编码：UTF-8

Content-Type： Content-Type:application/json

CRM对象接口调用说明

访问频次控制说明

单接口调用限制：60次/20秒；如需提升，请咨询纷享相关人员，购买独立库产品。

总接口调用次数限制：根据购买的 Open API[100000次] 的资源包 进行统计，如需提高，请购买多个则次数会进行叠加。

官方接口文档说明

目录描述
企业内部应用开发1、内部应用开发的流 2、纷享开放能力介绍：应用免登、纷享免登、事件变更订阅 3、接口调用说明 4、接口身份校验接口文档
通讯录接口通讯录相关的接口文档 1、人员接口 2、部门接口 3、用户组接口 4、人员角色接口
CRM对象通用接口CRM对象的通用操作的接口文档 1、CRM日志 2、获取国家地区 3、对象描述接口 4、流程接口 5、自定义函数接口 6、相关团队接口 7、解锁锁定接口
CRM对象接口CRM对象的所有接口，包含预置对象和自定义对象。如果没找对应的接口则说明目前接口尚未开放
其他接口除了CRM对象接口和通讯录接口外的其余接口 1、任务代办接口 2、考勤外勤接口 3、协议审批接口 4、企业互联接口 5、消息发送接口 6、ERP库存接口 7、ERP仓库接口 8、老接口文档 9、纷享服务器IP地址
客户端开发客户端相关的jspapi接口

身份验证

获取应用级授权

CorpAccessToken是企业应用访问相应公司数据的全局唯一票据，拉取信息和发送消息的接口都需要携带CorpAccessToken和CorpId。正常情况下CorpAccessToken的有效期为7200秒，有效期内重复获取返回相同结果。

请求说明

请求方式：post+application/json 方式

请求路径：open.fxiaoke.com/cgi/corpAcc…

参数说明

参数参数类型必须说明
appIdString是AppId(企业应用ID) ，获取方式见 应用身份认证参数
appSecretString是APPSecret(企业应用凭证密钥) ，获取方式见 应用身份认证参数
permanentCodeString是永久授权码，获取方式见 应用身份认证参数

请求包结构体示例:

{
    "appId": "APPID",
    "appSecret":"APPSECRET",
    "permanentCode":"PERMANETCODE"
}

参数获取位置: image.png

返回说明

参数必须说明
errorCode是返回码
errorMessage是对返回码的文本描述内容
corpAccessToken是企业应用访问公司合法性凭证
corpId是开放平台派发的公司帐号
expiresIn是企业应用访问公司合法性凭证的过期时间，单位为秒，取值在0~7200之间，在过期时间在0-6600之间请求该接口会返回相同的corpAccessToken，在6600-7200之间请求该接口会返回新的token，如果要续期token，则需要在该时刻进行请求。

a)正确的Json返回结果示例:

{
    "errorCode": 0,
    "errorMessage": "success",
    "corpAccessToken": "CORP_ACCESS_TOKEN",
    "corpId": "CORP_ID",
    "expiresIn": 7200
}

b)错误的Json返回示例:

{
    "errorCode": 10001,
    "errorMessage": "the parameter appId is missing"
}

获取用户级授权

纷享用户级授权采用OAuth2标准实现，OAuth（开放授权）是一个开放标准，允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而无需将用户名和密码提供给第三方网站或分享他们数据的所有内容。

授权方式

目前纷享支持OAuth2.0的授权方式：

  • 授权码模式

授权码模式

授权码模式认证的流程图如下所示：

image.png

通过CODE获取用户身份会有一定的时间开销。对于频繁获取用户身份的场景，建议采用如下方案：

  • 用户跳转到企业应用页面时，企业应用校验是否有代表用户身份的cookie，此cookie由企业应用生成
  • 如果没有获取到cookie，调用身份验证接口，获取用户身份后，由企业应用生成代表用户身份的cookie
  • 根据cookie获取用户身份，进入相应的页面

获取Code

请求说明

请求方式：get 方式

请求路径：open.fxiaoke.com/oauth2.0/au…

参数说明
参数参数类型必须说明
appIdString是自建应用的appId
redirectUrlString是回调地址，需要与创建应用填写的web端跳转地址保持一致，否则会报错该参数错误
responseTypeString是固定值：code
stateString是client端的状态值。用于第三方应用防止CSRF攻击，成功授权后回调时会原样带回

  1. state值说明

    在发起授权流程生成state参数时,要保证随机生成,并且尽量避免重复。例如：state= MD5（时间戳+当前帐号）。纷享在授权完成后，将重定向到开发者的服务器。此时开发者的服务器应检测state参数是否一致（即cookie或session里的state）。如果不一致，开发者的服务器应该拒绝此请求，并且不再发起换取access_token的请求。如果一致，则流程正常运行。

    强烈建议开发者实现以上过程，以防止CSRF攻击。

    请求包结构体示例：

    https://open.fxiaoke.com/oauth2.0/authorize?responseType=code&appId=FSAID_xxx&redirectUrl=https://open.fxiaoke.com/xxx&state=77598SDASF

  2. redirectUrl值说明

    image.png

返回说明
参数参数类型说明
codeString回调地址
stateString请求时默认返回

返回示例:

https://open.fxiaoke.com/xxx?code=xxxxxxx&state=77598SDASF

通过code获取accessToken

请求说明

请求方式：post+application/json 方式

请求路径：open.fxiaoke.com/oauth2.0/to…

参数说明
参数参数类型必须说明
grantTypeString是授权模式，该接口值为：authorization_code
appIdString是自建应用的appId
appSecretString是自建应用的appSecret
redirectUrlString是回调地址
codeString是跳转返回的code

请求包结构体示例:

{   
     "corpAccessToken": "Corp_Access_Token",
     "code": "CODE" 
}
返回说明
参数必须说明
openUserId是用户的openUserId
accessToken是关联用户和appId信息的token,有效期两个小时
corpId是开放平台派发的公司帐号
refreshToken是用于刷新accessToken,有效期两个月
expiresIn是过期时间

a) 正确的JSON返回结果示例:

{    
    "errorCode": 0,
    "errorMessage": "success",
    "openUserId": "openUserId",
    "accessToken": "accessToken",
    "corpId": "corpId",
    "refreshToken": "refreshToken",
    "expiresIn": 158xxxxx
}

b) 错误的JSON返回示例:

{    
    "errorCode": 10001,
    "errorMessage": "the parameter appId is missing"
}
刷新accessToken有效期
avatar
文章
阅读
粉丝