# 连接器接入指引

# 概述

# 架构一览

1. 架构一览

2. 接入流程

• 小程序应用

• erp应用

# 创建应用

1. 登陆服务平台应用管理，选择企业主页登陆。
2. 选择角色，这里分为两类，第三方账号和小程序，选择第三方账号可允许多个小程序接入，选择小程序只允许当前小程序接入，内测期间请使用第三方账号。第三方账号是根据企业主页的企业主体名称拉取同主体Open平台下的第三方账号。
3. 创建应用，依次填写应用名称、应用类型、测试小商店Appid（ERP和CRM需要填写），目前应用类型有"小程序"、"ERP"、"CRM"。 。

• 测试小商店AppId：主要用于自测，后面会详细讲到。
• 服务器地址：用于接收同步消息的地址，复用第三方平台的消息推送，配置教程点击这里。

4. 创建应用成功后，可以看到创建的应用列表。
5. 服务商需实现接口集的所有接口，每个接口都标识了接口的调用方和接收方，服务商需根据自己的应用类型，分别实现调用逻辑或接收逻辑。
6. ERP、CRM应用需自测，自测教程点击这里。
7. ERP、CRM应用自测完毕后，点击"完成自测"并上传“联调指引”。
8. 点击详情进入对接页面。
9. 小程序应用可点击“添加小程序”，将小程序申请接入到该连接器环境。详细小程序接入流程点此查看，结合ERP、CRM服务商提供的“联调指南”以及调用指引进行联调和调用。

# 消息推送配置

1. 登陆Open平台，进入第三方平台的管理后台，点击开发信息。
2. 下滑到开发资料，配置消息校验Token、消息加解密Key、消息与事件接收URL，开发资料全网发布不需要审核。 3.根据消息加解密文档开发消息推送。

# 自测教程

1. 在Open平台，配置“107连接器电商场景接入”权限集。 ，
2. 根据文档，将107权限集授权给测试小商店。
3. ERP、CRM创建应用后，会自动创建与小商店的环境（测试env_id），并把测试小商店接入到该环境中，服务商可用测试小商店进行自测。
4. 根据调用指引进行调用。

# 调用指引

1.调用前准备

• 在Open平台，配置“107连接器电商场景接入”权限集。
• 根据文档，将小程序授权给调用双方的第三方平台。
• 确保小程序已接入双方的连接器调用环境。

2. 发起调用，这里以删除商品接口为例，调用方用POST发送请求到 https://api.weixin.qq.com/wxa/servicemarket/connector/shop/product/del?access_token=xxxxxxxxx ，并在请求body里添加"connector"对象。

{
    "spu_id": "51514515",
    "connector":{
        "env_id":49,
        "ext_data":"xxx"
    }
}

• access_token：小程序的authorizer_access_token。
• env_id：环境env_id。
• ext_data：扩展字段

连接器识别env_id同步转发给接收方，接收方处理后，回包给连接器，连接器同步返回给调用方。 回包如下：

{
    "errcode": 0,
    "errmsg":"ok",
    "connector":{
        "ext_data":"xxx"
    }
}

• ext_data：扩展字段

3. 接收处理调用，当调用方发起调用后，连接器会通过同步消息推送的方式，将请求转发给接收方，格式如下（这里以xml举例）：

<xml>
    <FromUserName><![CDATA[o9AgO5GEcjNYkpQQ-03t_Ha8JYyI]]></FromUserName>
    <CreateTime>1629874885</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[connector_ts]]></Event>
    <api_path><![CDATA[/wxa/servicemarket/connector/shop/product/del]]></api_path>
    <appid><![CDATA[wx123]]></appid>
    <env_id>49</env_id>
    <ext_data><![CDATA[...]]></ext_data>
    <req><![CDATA[{"spu_id": "51514515"}]]></req>
</xml>

• api_path：api路径。
• appid：接入的小程序appid。
• env_id：正式环境id。
• ext_data：扩展字段。
• req：json格式，调用方的请求体。

接收方处理完成后，返回给连接器。 回包如下：

<xml>
  <ext_data>xxx</ext_data>
  <resp>{"errcode":0,"errmsg":"ok"}</resp>
</xml>

• ext_data：扩展字段。
• resp：回包，json格式。

调用链路图如下所示：

连接器错误码如下表：

# 小程序接入流程

1. 小程序应用在管理页面上”添加小程序“，添加完成后，连接器会通过消息推送发送接入请求给另一方应用。

<xml> 
  <appkey>1</appkey>  
  <env_id>1</env_id>  
  <appid>wx123</appid>  
  <apply_id>1</apply_id> 
</xml>

• appkey：代表哪个应用收到了申请接入的请求。
• env_id：代表该小程序申请接入哪个环境。
• appid：申请接入的小程序appid。
• apply_id：申请唯一id。

返回：

<xml> 
  <ResultCode>1</ResultCode>  
  <ResultMsg>ok</ResultMsg>
</xml>

• ResultCode：1代表允许接入，2代表不允许接入，其他值代表暂不处理。

还可以通过api调用的方式添加小程序：

POST https://api.weixin.qq.com/wxa/servicemarket/connector/batch_add_wxa?access_token=xxx
{
    "env_id":1,
    "appid_list":["wx12xxxxxx", "wx22xxxxx" ],
    "appkey":1
}

• access_token：第三方component_access_token。
• env_id：环境ID
• appkey：应用key 返回

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

2. 如果应用方暂不处理或者遗漏消息，还可通过“获取申请接入列表接口”获取申请接入的小程序列表。

POST https://api.weixin.qq.com/wxa/servicemarket/connector/get_apply_access_list?access_token=xxx
{
    "offset":0,
    "limit":10,
    "status_list":[1,2,3],
    "type":2
}

• access_token：第三方component_access_token。
• limit：最大为20。
• status_list：欲拉取的status列表，不填则不过滤，拉取所有的申请。1代表未处理，2代表已通过，3代表已拒绝。
• type：1代表发起方，2代表接收方。 连接器返回：

{
    "apply_access_list": [
        {
            "apply_id": 1997709095604207616,
            "appid": "wx123",
            "status": 1,
            "env_id": 3
        }
    ],
    "count": 9,
    "errcode": 0,
    "errmsg": "ok"
}

• count：总数
• apply_id：申请唯一id。
• appid：申请接入的小程序appid。
• status：1代表未处理，2代表已通过，3代表已拒绝。
• env_id：申请接入的环境id。

3. 获取到apply_id后，通过回复申请接口处理申请。

POST https://api.weixin.qq.com/wxa/servicemarket/connector/reply_apply_access?access_token=xxx
{
    "apply_id":1997709095604207616,
    "status":2
}

• access_token：第三方component_access_token。
• apply_id：申请唯一id。
• status：2代表通过，3代表拒绝。 返回：

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

4. 另一方同意后，该小程序正式接入了该环境。
5. 接入环境后，环境双方还需保证接入的小程序的107权限集授权给了两方的第三方平台。