# 联系人架构介绍

<p>为了帮助您更加顺利地接入OpenAPI，本文档将向您展示联系人与各模块之间的业务关系以及核心对接参数解惑</p>

## 二、联系人

### 1、联系人&好友&企业基本业务关系图

#### 核心说明
- 尘锋<span style="color:red;">联系人与好友</span>(员工通过企业微信添加)之间是<span style="color:red;">可选的关联关系</span>，不作强制绑定
- 联系人、<span style="color:red;">企业</span>均为<span style="color:red;">尘锋自研</span>系统模块，<span style="color:red;">与企业微信好友的"企业"字段并无关联</span>
- 尘锋单独设计了员工id(uid),并已处理好与企微员工id(user_id)的映射关系，通常情况下您将<span style="color:red;">主要使用uid</span>
- <span style="color:red;">unionId</span>是通过微信用户与微信公众平台(服务号、小程序)交互获取，<span style="color:red;">并非企微官方返回</span>

![联系人业务图.jpeg](https://cdn-sales.dustess.com/W00000000082/sales/q/g/n/l/qgnl6i2w7d81681366386999.jpeg)

### 2、联系人字段拆解

#### 核心字段

| 字段id      | 类型     | 字段名称   | 字段名称                                                                                       |
| ----------- | -------- | ---------- | ---------------------------------------------------------------------------------------------- |
| customer_id | string   | 联系人主键 | 尘锋联系人主键                                                                                 |
| external_id | string   | 外部系统id | 尘锋支持存储外部系统的客户id,并允许您通过此id完成增删改查                                      |
| mobiles     | object[] | 联系方式   | 联系人唯一去重元素,尘锋默认不允许录入相同的联系方式，<br/>您可以根据业务需求在管理后台自行控制 |

#### 资源归属字段

<span style="color:red;"><b>联系人入库必须有归属关系</b></span>，您可以根据业务需求同步至员工私海(关联跟进人)或公海(关联公海)

| 字段id     | 类型     | 字段名称 | 备注                                                                                                                                                                    |
| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| owner      | string   | 主跟进人 | 联系人的主跟进人，只允许有1个，[查询员工信息](https://open.dustess.com/doc-5158538.md)        |
| share_uids | string[] | 共享人   | 联系人的共享人，支持有多个，[查询员工信息](https://open.dustess.com/doc-5158538.md)           |
| pool       | string   | 公海id   | 联系人公海，与联系人是1对1关系，[查询联系人公海列表](https://open.dustess.com/doc-5147968.md) |

#### 业务关系关联字段

| 字段id          | 类型   | 字段名称         | 备注                                                                                                                                                                                                                                                                                                                                                       |
| --------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| corp_full_name  | string | 企业全称         | 联系人所关联的企业全称，多个企业的全称不会重复，[查询企业列表](https://open.dustess.com/doc-5158676.md)                                                                                                                                                                          |
| corp_id         | string | 企业id           | 联系人所关联的企业id，一般与企业全称是对应的，[查询企业列表](https://open.dustess.com/doc-5158676.md)                                                                                                                                                                             |
| external_userid | string | 外部联系人id     | 联系人所关联的企微好友id，未关联好友则为空，[查询好友列表](https://open.dustess.com/doc-5158543.md)                                                                                                                                                                              |
| unionId         | string | 微信用户唯一标识 | 联系人或好友都可以关联unionId。已关联的情况下可通过unionId查询对应联系人、好友数据 [查询联系人](https://open.dustess.com/doc-5147939.md)、[查询好友列表](https://open.dustess.com/doc-5158543.md) |

#### 预设字段/自定义字段

| 字段id        | 类型     | 字段名称   | 备注                                                                                                                                                                      |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prov_city     | string   | 省市县字段 | 系统预设字段，有固定格式，如"四川省-成都市-武侯区"，数据源来自[腾讯地图](https://lbs.qq.com/service/webService/webServiceGuide/webServiceDistrict)                        |
| custom_fields | object[] | 自定义字段 | 可根据需求自行定义字段类型、名称、内容。[查询字段模版](https://open.dustess.com/doc-5147965.md) |

#### 标签/来源/状态/类型字段

<span style="color:red;"><b>您需要在尘锋管理后台维护所需内容后，才可通过相关接口操作数据</b></span>

| 字段id     | 类型     | 字段名称   | 备注                                                                                                                                                                                                   |
| ---------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| tags       | string[] | 好友标签   | 支持给联系人打好友标签，[查询好友标签列表](https://open.dustess.com/doc-5147890.md)                                          |
| source     | string   | 来源       | 联系人来源标记，支持自定义，[来源列表查询（企业&联系人）](https://open.dustess.com/doc-5147962.md)                                          |
| status     | string   | 跟进状态   | 联系人跟进状态，支持自定义，[查询跟进状态列表](https://open.dustess.com/doc-5147964.md)                                      |
| categoryId | string   | 联系人类型 | 联系人类型，可选功能，支持给不同类型的联系人关联不同字段&好友标签，[联系人类型](https://open.dustess.com/doc-5147967.md)|

#### 去重逻辑说明

尘锋默认不允许录入相同的联系方式，您可以根据业务需求在管理后台自行控制

##### 受控制的接口

[新增联系人](https://open.dustess.com/doc-5147945.md)、[编辑联系人](https://open.dustess.com/doc-5147936.md)

![mobile.png](https://cdn-sales.dustess.com/W00000000082/sales/7/6/z/1/76z1lcbscyr1702278405104.png)

### 3.联系人在不同业务域的命名&角色

| 业务域    | 命名       | 角色                              |
| --------- | ---------- | --------------------------------- |
| 企业      | customerId | 企业所关联的联系人                |
| 好友      | contact_id | 好友所关联的联系人                |
| 销售机会  | cid        | 销售机会关联的联系人              |
| 商城-会员 | customerId | 会员(主键为unionId)所关联的联系人 |
| 商城-订单 | customerId | 订单所关联的联系人                |
| 终端能力  | cid        | 通话记录所关联的联系人            |