第三方应用开发 服务端API 应用授权 自建应用代开发
自建应用代开发

目录

  • 概述
  • 企业应用代开发流程图示
  •       创建代开发模版
  •             1. 概述
  •             2. 创建代开发模版
  •             3. 提交代开发模版上线
  •             4. 获取代开发模版授权二维码
  •       企业应用代开发
  •             1. 概述
  •             2. 开始代开发应用配置
  •             3. 配置自定义权限
  •             4. 自行测试
  •             5. 代开发应用上线
  • 与自建应用接口的差异
  •       1.secret的获取
  •       2.secret的重置
  •       3.获取应用access_token
  •       4.接口权限
  •       5.设置应用
  •       6.接口调用ip白名单
  •       7.通讯录变更回调
  •       8.授权变更回调
  • 代开发应用与第三方应用的兼容
  •       corpid的转换
  •       userid的转换
  •       external_userid的转换
  • 概述

    企业微信保持开放的第三方合作策略,致力于和所有的合作伙伴携手为用户提供最优质的企业服务。
    为此,企业微信开放自建应用代开发模式,企业可通过扫码授权的方式,授权第三方服务商代开发自建应用,更加安全、高效、便捷。
    服务商可通过自建应用代开发模式,为企业提供灵活的、定制的应用服务。通过原第三方标准应用模式,向企业提供标准的、统一的应用服务。
    本指引将介绍企业微信服务商,为企业用户提供自建应用代开发的流程。
    企业应用代开发同时支持 网页应用 和 小程序应用。

    企业应用代开发流程图示

    创建代开发模版

    1. 概述

    ● 代开发应用模版,是服务商向企业提供一类自建应用代开发的载体,与授权二维码一一对应。例如CRM和ERP可以是两个代开发应用模版,对应两个授权二维码,企业可以选择需要的应用能力授权代开发自建应用。

    ● 一个代开发应用模版,可以被多个企业扫码授权。例如服务商的CRM代开发应用模版,多个企业授权后,服务商可为这些企业代开发CRM自建应用。

    ● 每个模版仅可以被同一个企业授权安装一个代开发应用。例如企业扫码授权了服务商的CRM代开发模版,服务商可为该企业代开发一个CRM应用,不可以一个模版代开发多个应用。服务商可通过多个代开发模版为企业代开发多个应用。

     

    2. 创建代开发模版

    1) 进入 服务商后台-应用管理-应用代开发 ,点击“创建代开发应用模版”,进行代开发应用模版基础信息和开发信息配置。

    2) 配置代开发模版信息填写标准:

     

    填写项填写标准
    代开发应用模版logo必须为正方形,像素为750﹡750,1M以内的jpg、png图片,不可使用企业微信logo或进行二次修改
    代开发应用模版名称2-10个字,建议包含品牌名,不可使用特殊字符及特殊词汇 (如:“微信”、“特卖”、“企业微信”、“企微”、“抽奖”、“免费”等)
    代开发应用模版介绍4-20个字,简单清晰描述应用功能和使用场景
    分类根据应用的功能及场景进行选择
    目标行业根据应用目标用户的行业进行选择
    代开发模版回调URL填写带https:// 头的有效URL链接,填写URL时需要正确响应企业微信验证URL的请求。用于接收企业用户授权成功信息

     

    3. 提交代开发模版上线

    代开发模版创建成功后,仅保存了模版信息。需要进入 服务商后台-应用管理-代开发应用上线 提交模版上线审核,审核通过后手动提交上线。模版正式上线后才会生成对应的授权二维码。
    1) 点击提交上线按钮,选择需要提交上线审核的代开发模版。

    2) 提交后可在代开发应用上线列表中,查看模版上线审核单。

    3) 审核通过后,审核状态将变为“待上线”,进入审核详情页,点击“提交上线”,进行代开发模版上线。

    4. 获取代开发模版授权二维码

    1) 模版上线提交成功后,回到 服务商后台-应用管理-代开发应用,进入代开发模版详情页,可查看对应的授权二维码。

     

    2) 若需要将多个代开发应用模版组合成一个授权二维码,让企业进行批量授权,可在代开发应用首页,点击右上角“批量授权”按钮,选择2-9个已上线的代开发应用模版,生成批量授权二维码。批量授权二维码有效期为10天,超过10天需要重新生成。

    3) 将代开发模版对应的授权二维码,提供给企业客户管理员,进行扫码授权。

     

    企业应用代开发

    1. 概述

    ● 企业扫描服务商代开发二维码,授权成功后,企业侧自动创建由该服务商代开发的自建应用,初始状态为开发中,不可正常使用。待服务商正式上线企业代开发应用,则企业侧该应用状态变成已启用,企业管理员可设置可见范围正常使用。企业侧可以随时取消授权,服务商侧不可删除代开发企业应用。

    ● 自建应用代开发,应用权限分为基础权限和自定义权限。
    基础权限为企业扫码授权服务商进行自建应用代开发,应用即可获取基础权限。
    自定义权限,则需要企业再次确认后,代开发应用才可以获取具体自定义权限。
    哪些为基础权限,哪些为自定义权限,代开发权限明细可查看:代开发权限说明

    2. 开始代开发应用配置

    1) 进入 服务商后台-应用管理-应用代开发 ,点击提供给企业扫码授权的代开发模版,进入模版详情页,可以查看该代开发模版对应的企业授权列表。

    2) 点击“开始代开发应用”为该企业代开发应用配置基础信息和开发信息。其中代开发应用logo、名称、介绍,回调URL信息,会默认填写代开发模版的信息,可以进行修改,提升填写效率。

    填写项填写标准
    代开发应用logo必须为正方形,像素为750﹡750,1M以内的jpg、png图片,不可使用企业微信logo或进行二次修改
    代开发应用名称2-10个字,建议包含品牌名,不可使用特殊字符及特殊词汇 (如:“微信”、“特卖”、“企业微信”、“企微”、“抽奖”、“免费”等)
    代开发应用介绍4-120个字,简单清晰描述应用功能和使用场景
    应用主页用户从企业微信工作台进入应用时将直接跳转到对应的主页URL
    可信域名填写不带http:// 或https:// 头,可信域名必须通过ICP备案验证,设置可信域名后支持应用的OAuth2授权、JSSDK调用等
    IP白名单选填。只有白名单内的IP才能正常调用企业微信API,若后续IP有修改,需要及时进行列表更新
    代开发应用回调URL填写带https:// 头的有效URL链接,填写URL时需要正确响应企业微信验证URL的请求。用于接收托管企业微信应用的用户消息、进入应用事件等事件

    3) 自建应用代开发支持关联小程序。小程序需要先在微信小程序平台审核和发布,然后在服务商管理后台进行关联。关联步骤如下:
    ● 首次创建代开发应用,可点击 “已有小程序,快速创建”进行关联。
    ● 已创建的代开发应用,可在 “代开发应用详情 - 使用配置 -应用主页”中进行关联。
    关联成功后,小程序中可调用企业微信相关接口能力,同时也可将小程序配置在代开发应用的菜单中。

    3. 配置自定义权限

    企业完成代开发应用授权后,代开发应用若需要额外的自定义权限,实现相关功能的开发,可以申请获取代开发应用自定义权限。
    1) 进入服务商后台,代开发应用详情页,权限设置模块,点击右上角“编辑”按钮,可进行代开发应用自定义权限编辑。
    2) 进入编辑状态后,可选择代开发应用所需要的自定义权限进行勾选。代开发应用自定义权限可多次编辑,每次编辑保存后将立即向企业客户发送一条代开发应用权限变更推送消息。
    3) 企业客户管理员收到代开发应用权限变更消息,若企业同意权限则服务商所选择的自定义权限立即生效。若企业选择暂不授权,则本次服务商选择的权限不生效,代开发应用依旧保持之前的自定义权限。
    4) 代开发应用详情页,权限设置模块,非编辑状态:
    ● 当前申请的代开发自定义权限待企业侧确认的,会在权限后面展示“待企业客户确认”提示;
    ● 当企业同意授权后,权限设置模块将更新为企业确认后的权限状态,且没有“待企业客服确认”提示;
    ● 当企业暂不授权后,权限设置模块将回退为申请之前的权限状态,即服务商申请的没有成功。
    5) 在权限设置模块,点击右上角的“查看企业已确认权限”,可查看当前代开发应用生效的权限状态。
    6) 代开发应用自定义权限,与应用上线状态无关,申请自定义权限企业确认后则立即生效,可调用相关接口。自定义权限企业确认后,企业侧不需要到企业管理后台去配置可调用应用(例如客户联系相关权限,服务商勾选企业确认后,代开发应用即可调用,不需要再到企业管理后台客户联系配置可调用应用)。

    4. 自行测试

    可通过服务商测试企业,进行代开发应用测试。(若无测试企业可创建一个测试企业,无需注册服务商账号,作为测试企业使用即可)。

    ● 服务商测试企业,管理员扫描需要代开发应用的同一个代开发模版二维码,授权后为该测试企业配置相同的代开发应用信息。

    ● 将服务商测试企业的代开发应用提交上线审核,审核通过后提交正式上线。

    ● 服务商测试企业管理员收到代开发应用上线消息,设置该应用可见范围,可见范围内成员可以进行应用使用和测试相关功能。

    5. 代开发应用上线

    1) 自行测试完毕后,进入服务商后台-应用管理-代开发应用上线,点击“提交上线”按钮,选择需要上线的代开发模版,和对应的企业代开发应用,提交上线审核。
    ● 提交上线页,左侧先选择需要上线代开发应用所属代开发模版,然后在右侧选择这个模版下,需要提交上线审核的企业代开发应用,勾选后确定提交。则该企业代开发应用进入上线审核流程。
    ● 提交代开发应用上线,不需要再次提交所属代开发模版的上线流程。代开发模版仅在修改模版配置信息时需要保存后提交模版上线。

    2) 审核通过后,进入代开发应用审核详情页,点击提交上线,确认正式上线企业代开发应用。

    3) 正式上线后,企业管理员将收到代开发应用已完成消息,可引导企业管理员先设置小范围的可见范围,进行应用使用,若无问题再设置更大可见范围。

    与自建应用接口的差异

    代开发自建应用跟“企业内部开发”自建应用的接口调用方式大部分一致,主要以下几个差异点:

    1.secret的获取

    不同于自建应用开发模式,secret由企业管理员登录管理端获取,代开发的自建应用secret获取方式如下:
    (1)企业管理员扫代开发模版授权码时,授权完成后会推送授权成功通知到应用代开发模版回调url。
    (2)收到回调后,开发者通过获取企业永久授权码接口获取到的permanent_code,即为代开发应用的secret。(注意:此种情况获取企业永久授权码接口会多返回is_customized_app字段,且值为true,表示是代开发模版授权,另外接口不返回access_token字段)。

    注:
    1. 应用代开发模版id即为suite_id。企业微信后台也会定期向应用代开发模版回调url推送suite_ticket
    2. 可通过获取第三方应用凭证接口获取suite_access_token。
    3. suite_access_token可用于获取企业永久授权码
    4. 可调用获取企业授权信息(注意:此种情况接口会多返回is_customized_app字段,且值为true,表示是代开发模版授权)

    2.secret的重置

    服务商可在服务商管理端的代开发应用详情页点击“重新获取”(见下图)来重置应用secret。点击“重新获取”后,企业微信后台会回调重置永久授权码通知。开发者收到回调事件后,可使用AuthCode通过获取企业永久授权码接口获取代开发应用最新的secret(即permanent_code字段)。

    3.获取应用access_token

    有了代开发应用的secret之后,接口调用凭证access_token的获取方式就与自建应用完全一样了,调用的是获取access_token接口。注意,这与第三方应用的access_token获取方式不一样。

    4.接口权限

    自建应用代开发的接口权限分为基础权限和自定义权限,具体可查看:代开发权限说明
    其中自定义权限,由服务商申请企业确认,或者企业在应用管理中主动配置后,企业侧不需要到企业管理后台去配置可调用应用。(例如客户联系相关权限,服务商勾选企业确认后,代开发应用即可调用,不需要再到企业管理后台客户联系配置可调用应用)。

    5.设置应用

    针对代开发自建应用,不允许调用设置应用接口设置应用

    6.接口调用ip白名单

    针对代开发自建应用,若服务商在服务商管理端为应用配置了ip白名单,则接口只允许ip白名单内的ip发起请求。如果未配置ip白名单,则跟自建应用一致,允许任何ip发起请求。

    7.通讯录变更回调

    企业通讯录变更时,企业微信后台会回调通讯录回调通知到代开发应用回调URL上。

    8.授权变更回调

    修改代开发应用可见范围时,企业微信后台会回调变更授权通知到代开发模板回调URL上。

    代开发应用与第三方应用的兼容

    部分企业同时授权了服务商的代开发应用与第三方应用,由于代开发应用获取的corpid、userid、external_userid,与第三方应用获取的不一样。为了服务商能够为企业正常提供服务,企业微信提供了转换接口如下。

    corpid的转换

    将代开发应用获取的corpid转换为第三方应用获取的corpid
    接口定义参见corpid转换

    userid的转换

    将代开发应用获取的userid转换为第三方应用获取的userid
    接口定义参见userid转换

    external_userid的转换

    将代开发应用获取的external_userid转换为第三方应用获取的external_userid
    接口定义参见代开发应用external_userid转换

    上一篇
    成员授权应用
    下一篇
    通讯录权限体系