===== CRM提供的接口 =====
----
如[[帮我吧文档:crm接口:概述#APIChart|概述中的API交互图]]所示，CRM系统需要提供如下三个接口供帮我吧客服端调用，其中CRM_API_1和CRM_API_2都通过帮我吧配置界面所配置的**CRM回调URL**来实现，通过不同的URL参数来实现功能区分。CRM_API_3即[[帮我吧文档:crm接口:系统配置|系统配置]]中的**CRM内嵌URL**。

下面接口描述中假设[[帮我吧文档:crm接口:系统配置|系统配置]]中配置的CRM回调URL为：https://www.crm.com/bangwo8crmApi.php，配置的CRM内嵌URL为：https://www.crm.com/bangwo8crm.php。<wrap em>这两个URL及其域名并不存在，仅供举例，具体接口实现时，这部分URL路径请用您具体配置在[[帮我吧文档:crm接口:系统配置|系统配置]]中的URL取代。</wrap>

<BOOKMARK:CRM_API_1>
==== 1. CRM_API_1：查询客户的公司信息 ====
帮我吧客服端调用此接口来查询当前请求服务的用户的相关信息，比如公司名称、联系人名称、联系方式等，具体接口说明如下：

**回调地址：**
<WRAP prewrap>
  https://www.crm.com/bangwo8crmApi.php/companyinfo?supportname={supportname}&authcode={authcode}
</WRAP>
**请求方法：**POST\\
**参数说明：**\\
^  参数  ^  是否必填  ^  说明  ^  示例  ^
| authcode  |  是  | 用于接口保护的共享密钥，具体参见[[帮我吧文档:crm接口:接口的安全保护|接口的安全保护]]  | |
| supportname  |  否  | 帮我吧客服账号  | |

**POST数据说明：**\\
POST数据体为JSON数据，具体格式类似如下任何一行示例字符串：\\
<code>
{"type":"get", "companyid":"12"}
{"type":"get","companyid":"12,13,14"} 
{"type":"querycompany", "querycontent":"北京金万维"} 
{"type":"querycontact", "querycontent":"李四"} 
{"type":"querymobile", "querycontent":"138888"} 
{"type":"querynote", "querycontent":"评价内容"} 
</code>

JSON数据的每个字段的取值说明如下：
^  变量名  ^  说明  ^  示例  ^
| type | type可以取值如下字符串：\\ **get**：获取指定公司ID的联系人信息，可以给一个ID或者一个逗号分隔的多个ID；\\ **querycompany**：按客户公司名称在CRM系统中进行模糊查询；\\ **querycontact**：按客户的联系人名称在CRM系统中进行模糊查询；\\ **querymobile**：按客户的联系人手机号在CRM系统中进行模糊查询； \\ **querynote**：按客户的联系人备注信息在CRM系统中进行模糊查询； | |
| querycontent | 模糊查询时要查询的内容 | 张三，0106324 | |
| companyid  | 第三方系统客户的唯一ID，如果有多个ID，则以逗号分割  | 4,6,8  |

**请求成功返回结果**\\
<WRAP prewrap>
  APIResult;00;
  {
    "12":
    {
        "company":{"companyid":"12","companyname":"公司名","updatetime":"2016-04-27 22:17:05"},
        "contactor":
        [
            {"cid":"1103451","crealname":"联系人","cmobile":"125xxx","cremark":""},
            {"cid":"1103452","crealname":"联系人","cmobile":"125xxx","cremark":""},
            {"cid":"1103453","crealname":"联系人","cmobile":"125xxx","cremark":""}
         ]
    },
    "13":
    {
        "company":{"companyid":"13","companyname":"公司名","updatetime":"2016-04-27 22:17:05"},
        "contactor":
        [
            {"cid":"1103454","crealname":"联系人","cmobile":"125xxx","cremark":""},
            {"cid":"1103455","crealname":"联系人","cmobile":"125xxx","cremark":""},
            {"cid":"1103456","crealname":"联系人","cmobile":"125xxx","cremark":""}
         ]
    },
  }
</WRAP>
**返回结果说明**\\
^  参数  ^  是否必填  ^  说明  ^  示例  ^
| companyid  |  是  | 公司Id  | |
| companyname  |  是  | 公司名称  | 1,2,3,15  |
| updatetime  |  是  | 上次修改时间  | 2016-04-27 22:17:05  |
| cid  |  否  | 联系人在crm中的唯一id  | 	|
| crealname  |  否  | 联系人姓名  | |
| cmobile  |  否  | 联系人电话  | |
| cremark  |  否  | 联系人备注  | |
**请求失败**\\
  APIResult;01;companyid为空
  APIResult;02;companyid重复
  APIResult;03;querycontent为空
  APIResult;04;未查到数据
  
  说明：其他错误可以自定义除上之外的其他错误码与提示信息
  
  



<BOOKMARK:CRM_API_2>
==== 2. CRM_API_2：添加/修改联系人信息 ====
帮我吧客服端会调用此接口来给一个公司名下添加一个联系人，或者修改一个公司名下已有的联系人信息。

**请求方式:** POST\\
**回调地址：**
<WRAP prewrap>
  https://www.crm.com/bangwo8crmApi.php/contact?supportname={supportname}&authcode={authcode}
</WRAP>
**参数说明：**
^  参数  ^  说明  ^  示例  ^
| supportname  | 帮我吧客服账号  | supportname  |
| authcode  | 用于接口保护的共享密钥，具体参见[[帮我吧文档:crm接口:接口的安全保护|接口的安全保护]]  | |
**POST数据说明：**\\
POST数据体为如下格式的JSON数据，示例如下：\\
<code>
{
    "companyid":"12",
    "cid":"19",
    "contactname":"李四",
    "contactmobile":"13888888888"，
    "contactremark":"联系人备注",
    "uniquenumber":"999999999"
}
</code>
JSON数据的每个字段的取值说明如下：
^  变量名  ^  说明  ^  示例  ^
| companyid  | CRM里的公司ID  | 12  |
| cid  | 联系人在CRM中的唯一ID\\  (<wrap em>注意：如果调用者给的cid为空，则是添加新的联系人</wrap>)  | 19  |
| contactname  | 联系人姓名  | 李四  |
| contactmobile  | 联系人手机号  | 13888888888  |
| contactremark  | 联系人备注  | 备注  |
| uniquenumber  | 帮我吧客户端9位ID号  | 8562xxxxx  |

**返回值：**

请求成功
  APIResult;00;{"cid":"联系人ID"}
//注意：一定要返回添加/修改成功的联系人ID给调用者//

请求失败
  APIResult;01;提示信息


<BOOKMARK:CRM_API_3>
==== 3. CRM_API_3：添加/绑定公司页面 ====
**调用地址：**
<WRAP prewrap>
  https://www.crm.com/bangwo8crm.php?supportname={supportname}&authcode={authcode}
</WRAP>
**请求方法：**GET\\
**参数说明：**\\
^  参数  ^  是否必填  ^  说明  ^  示例  ^
| supportname  |  否  | 帮我吧客服账号  | |
| authcode  |  是  | 用于接口保护的共享密钥，具体参见[[帮我吧文档:crm接口:接口的安全保护|接口的安全保护]]  | |

**页面说明：**\\
当客服端收到一个新客户的客服请求的时候，它会调用此接口在CRM系统中查找或者新建一个对应的客户公司，然后在客服系统中将该公司和客户绑定起来。\\
不同于前文所述的回调接口，**此接口本身需要有一个网页界面**。在访问此接口时，帮我吧客服端会根据[[帮我吧文档:crm接口:系统配置|系统配置]]中配置的内嵌窗口尺寸(如下图所示)，创建一个内嵌的浏览器窗口打开此接口地址（之所以要求CRM接口本身提供界面是因为不同CRM系统可能有不同的添加公司的UI界面，帮我吧客服端无法做一个通用界面来添加公司）。
{{ :帮我吧文档:crm接口:crmembedwinsize.png?nolink |}}

CRM系统在此内嵌URL中实现的页面如下图所示，需要在此接口页面中提供**搜索、选择一个已有公司**，以及**创建新公司**的功能。此外，此页面需要能够**把搜索的时候匹配选中的公司ID、公司名称，或者新创建的公司ID返回给帮我吧客服端**。具体返回信息给帮我吧客服端的方式是调用帮我吧客服端给内嵌浏览器窗口提供的扩展JavaScript函数。
{{ :帮我吧文档:crm接口:crmembedwin.png?nolink |}}

**返回选中公司信息：**\\
当用户在此页面中找到一个已有的公司，那么在用户点确定关闭窗口的时候，此页面可以调用下面的JavaScript扩展函数将该公司ID和公司名称返回给帮我吧客服端：
<code>
window.external.JSSearchCompany(CompanyID, CompanyName);
</code>
  * JSSearchCompany：Javascript 函数名
  * CompanyID：函数参数，可以为字符串或整型数
  * CompanyName：函数参数，字符串
<wrap em>注：参数顺序固定不能变</wrap>

示例：
<code javascript>
<script language="javascript">
function CallCpp()
{
    var nID = 123456789;
    var sName = ‘我的公司名’;
    window.external.JSSearchCompany(nID, sName);
}
</script>
</code>
**返回新建公司信息：**\\
当用户在页面中新创建一个公司的时候，此页面可以调用下面的JavaScript扩展函数将新建的公司ID返回给帮我吧客服端：\\
<code>
   window.external.JSCreateCompany(CompanyID);
</code>
  * JSCreateCompany：Javascript 函数名
  * CompanyID：函数参数，可以为字符串或整型数
示例：
<code javascript>
<script language="javascript">
function CallCpp()
{
    var nID = 123456789;
    window.external.JSCreateCompany(nID);
}
</script>
</code>