第三方应用开发 服务端API 接口调用许可 概述与指引
概述与指引

目录

  • 接口调用许可
  • 接口调用许可帐号
  • 接入指引
  • 许可帐号失效的表现
  •       基础帐号失效的接口表现
  •       互通帐号失效的接口表现
  • 测试指引
  • FAQ
  • 接口调用许可

    企业微信通过向服务商开放接口,实现企业微信与服务商产品之间的相互调用,一起满足企业在各应用场景下的使用需求。为了确保服务商正确与规范的使用接口,企业微信向服务商颁发接口调用许可。

    服务商在获得调用许可并在企业管理员授权后,可将帐号激活码绑定到企业成员,以激活基于该成员调用企业微信接口的能力。

    开通接口调用许可时,服务商向企业微信支付许可费用,同时取消现有的按照收款资金固定比例收取的“技术服务费”。

    接口调用许可帐号

    许可帐号,也即接口调用许可帐号,按照能力的不同,分为两种类型:基础帐号互通帐号
    服务商为企业提供服务时,至少需要为企业成员开通基础帐号,才能为该成员调用身份验证、应用发消息等接口。
    服务商为企业提供微信客户联系相关的功能时,需要为企业成员开通互通帐号。开通了互通帐号,自动拥有了基础帐号的能力。
    下文中,如无特殊说明,接口调用许可帐号将简称为许可帐号,或者帐号

    接入指引

    企业微信服务商管理端提供了下单、支付、绑定激活、退款等功能。为了提高服务商的工作效率,企业微信提供了以下接口,以让服务商可以更加自动化地处理帐号激活等事务,从而让企业获得更好的使用体验。

     

    一、下单购买帐号
    服务商下单为企业购买新的帐号,可以同时购买基础帐号与互通帐号。下单之后,需要到服务商管理端发起支付,支付完成之后,订单才能生效。查看接口详情

    二、下单续期帐号
    可以下单为一批已激活帐号的成员续期。同样,下单之后,需要到服务商管理端发起支付,支付完成之后,订单才能生效。查看接口详情

    三、获取订单详情
    由于目前需要在服务商管理端手动发起支付,故服务商的系统有必要在某个时机查询订单的状态,当订单已支付完成,则可再调用获取订单中的帐号列表接口,以获取帐号激活码列表。查看接口详情

    四、获取订单中的帐号列表
    查询指定订单下的接口许可帐号列表。若为购买帐号的订单,则返回帐号激活码列表;若为续期帐号的订单,则返回续期帐号的成员列表。注意,若是购买帐号的订单,则仅订单支付完成时,企业微信系统才会生成帐号,故支付完成之前,该接口不会返回帐号激活码。
    当订单为购买帐号的订单时,该接口尤其重要,因为获取到帐号激活码列表之后,服务商后续可以自动地为企业的成员绑定激活相应的服务能力。
    查看接口详情

    五、激活帐号
    将帐号激活码绑定到某个企业员工上,以对其激活相应的服务能力。查看接口详情

    六、帐号继承
    在企业员工离职或者工作范围的有变更时,允许将其许可帐号继承给其他员工。查看接口详情

    七、其他接口
    除了以上六个关键的接口,企业微信还提供了获取订单列表获取激活码详情获取企业的帐号列表获取成员的激活详情等接口,以让服务商可以在自己的系统中实现完整的接口调用许可管理。

     

    许可帐号失效的表现

    如果服务商没有为企业成员开通接口许可,或者已开通的接口许可过期,原则上将无法为该企业成员调用企业微信的接口,服务商需要及时开通或续期接口许可。目前明确有影响的接口包括但不限于以下列表。

    基础帐号失效的接口表现

    基础帐号失效包括两种情况:1. 未配置基础帐号,2. 基础帐号已过期。
    特别地,若配置了有效的互通帐号,则自动拥有了基础帐号。
    接口失效的表现
    身份验证提示用户联系服务商购买基础帐号
    小程序登录提示用户联系服务商购买基础帐号
    发送应用消息touser中基础帐号失效的成员会返回在unlicenseduser中,
    toparty或totag中基础帐号失效的成员将收不到该应用消息

     

    互通帐号失效的接口表现

    互通帐号失效包括两种情况:1. 未配置互通帐号,2. 互通帐号已过期。
    接口失效的表现
    获取客户列表若成员的互通帐号失效,则无法获取该成员的客户列表,此时接口返回错误码701008
    获取客户详情若成员的互通帐号失效,返回的跟进人follow_user不包含该成员;
    若客户的所有跟进人均无有效互通帐号,则无法获取该客户的详情,此时接口返回错误码701008
    批量获取客户详情若成员的互通帐号失效,则无法获取该成员的客户列表;
    若客户的所有跟进人均无有效互通帐号,则无法获取该客户的详情;若全部跟进人均无有效互通帐号,此时接口返回错误码701008
    获取客户群列表若群主的互通帐号失效,则无法获取群主对应的客户列表;若所有群主均无有效互通帐号,此时接口返回错误码701008
    获取客户群详情若群主的互通帐号失效,则无法获取该群的详情,此时接口返回错误码701008
    微信客服添加接待人员若成员的互通帐号失效,则无法将其添加到微信客服的接待人员里,此时接口返回的结果里相应的userid错误码为701008
    微信客服变更会话状态若成员的互通帐号失效,则无法为其分配客服会话,此时接口返回错误码701008
    微信客服为客户升级为专员或客户群服务若成员的互通帐号失效,则无法将该成员作为专员或客户群群主推荐给客户,此时接口返回错误码701008
    回调失效的表现
    添加企业客户事件若成员的互通帐号失效,则该成员有新添加的客户时,不回调事件

    测试指引

    由于企业授权安装服务商的应用之后,会有90天的免费试用期,服务商难以测试到接口不可调用的表现,企业微信发布了测试企业的功能,服务商可在 服务商管理端-应用管理-开发配置 或者 服务商助手-工具-通用配置-开发配置 配置测试企业。配置为测试的企业,有以下特点:

    1. 为测试企业购买的订单支付金额为0元,即服务商无须支付费用。
    2. 安装的应用将立即不可调用接口,也即没有免费试用期,应用类型包括第三方应用和代开发应用。
    3. 为测试企业购买时长和续期时长最长一个月。
    4. 测试企业安装的应用将在安装90天后自动删除。
    5. 服务商最多可以配置10个测试企业。

    通过测试企业,服务商可以方便地调试到有许可帐号和无许可帐号的不同表现。

     

    FAQ

    1. 自建应用代开发也需要接入接口调用许可吗?
      答:需要的。代开发应用与第三方应用都需要接入。

    2. 应用安装之后,如果未购买接口许可,企业成员就立即不可使用吗?
      答:每个应用授权安装之后,有90天的免费试用期,试用期内即使未购买接口许可,也可正常使用。需要注意的是:免费试用期从该应用的首次安装开始计起,将应用删除重装,试用期不变。

    3. 为测试企业通过接口下单之后,还需要到服务商管理端支付吗?
      答:不需要,为测试企业下的订单都是0元免支付单,下单后立即为“已支付”状态。

    4. 帐号继承时,转移成员与接收成员必须是在第三方应用的可见范围之内吗?
      答:不需要是在第三方应用的可见范围。

    5. 帐号继承时,如果接收成员已经有相同类型的许可帐号了,能成功继承吗?
      答:不能,接口返回错误码701018。

    6. 帐号的有效期从什么时候开始计起?什么时候结束?
      答:帐号有效期从激活时计起,到帐号时长之后的结束日第二天0点结束。帐号时长每个月按31天计算,每年按12*31共372天计算。举个例子:购买的帐号是1年,在2022年5月17号 12:30激活,那该帐号从激活时开始生效,372天之后是2023年5月24号 12:30,实际失效是在5月25号0点失效。

    7. 企业安装了服务商的多个应用,需要为同一个成员购买多个接口调用许可吗?
      答:不需要,无论安装多少个应用,一个成员都只需要购买一个接口调用许可。

    8. 何时应该为一个企业成员激活帐号
      答:企业授权安装应用之后,或者将新的成员加入到应用可见范围之内,企业微信会为每个成员回调成员关注事件,此时服务商先在本地存储查询该成员是否有开通许可,如未开通,即可调用激活帐号接口进行激活。

    9. 代开发应用拿到的corpid跟userid如果是明文的,如何将明文的corpid跟userid转换成密文?
      答:参考corpid转换以及userid的转换
      注:目前相关接口的请求参数的corpid或者userid已经同时支持明文跟密文。但是接口返回的参数还是统一返回的密文。

     

    上一篇
    获取「客户数据统计」接待人员明细数据
    下一篇
    下单购买帐号