雄韬 XTOCN · OpenCRM
Base URL：https://my.xtocn.com/api | 认证：Authorization: Bearer $OPENCRM_KEY
决策表
| 用户意图 | 调用接口 | 关键参数 |
|---|---|---|
| 粘贴企查查/天眼查文本，新增客户 | POST /opencrm.parse/company → POST /opencrm.customer/add |
text → 解析结果确认 → customer_name 等字段 |
| 新增客户（已知字段） | POST /opencrm.customer/add |
customer_name（必填），其他字段详见 references/fields.md |
| 按公司全称查客户 | GET /opencrm.customer/detail?name=公司全称 |
name |
| 按信用代码查客户 | GET /opencrm.customer/detail?tax_number=统一社会信用代码 |
tax_number |
| 模糊搜索客户 | GET /opencrm.customer/list?keyword=关键词 |
keyword、page、limit |
| 浏览客户列表 | GET /opencrm.customer/list?page=1&limit=20 |
page、limit（最大 200） |
| 修改客户档案（工商信息/联系方式/地址等） | POST /opencrm.customer/edit |
id（必填），只传要改的字段 |
| 设置客户分组 | POST /opencrm.customer/setGroup |
id、customer_group |
| 设置客户等级 | POST /opencrm.customer/setLevel |
id、level_name |
| 设置客户行业 | POST /opencrm.customer/setIndustry |
id、industry |
| 设置客户来源 | POST /opencrm.customer/setSource |
id、source |
| 新增线索 | POST /opencrm.lead/add |
lead_name（必填） |
| 查线索列表 | GET /opencrm.lead/list |
page、limit |
| 新增拜访记录 | POST /opencrm.followUp/add |
customer_name 或 customer_id、follow_content（必填） |
| 查看拜访记录 | GET /opencrm.followUp/list |
customer_name 或 customer_id |
| 新增联系人 | POST /opencrm.contact/add |
customer_name、contact_name（必填） |
| 查看联系人 | GET /opencrm.contact/list |
customer_name 或 customer_id |
新增客户工作流
用户粘贴了原始文本（企查查/天眼查等）
GATE 1 [AI PARSE]
POST /opencrm.parse/company { text: "..." }
返回结构化字段 → 展示给用户确认，不要直接写入
GATE 2 [CONFIRM]
用户确认无误 → POST /opencrm.customer/add
用户要求修改 → 调整字段后再调用 add
公司已存在 → 返回"客户名称已存在"，提示用户用 detail 查询
用户给了明确字段
直接调 POST /opencrm.customer/add，传入已知字段。
修改客户工作流
工商信息 & 联系方式 → 用 edit
用户要求修改税号/法人/注册资金/电话/地址等 → POST /opencrm.customer/edit
只传要改的字段，未传字段保持原样（PATCH 语义）
edit 可修改字段详见 references/fields.md。
分组/等级/行业/来源 → 用独立端点
这四个是分类标签，高频修改，用专用端点更安全：
改分组 → POST /opencrm.customer/setGroup { id, customer_group }
改等级 → POST /opencrm.customer/setLevel { id, level_name }
改行业 → POST /opencrm.customer/setIndustry { id, industry }
改来源 → POST /opencrm.customer/setSource { id, source }
每个端点只做一件事，避免误操作。传名称即可，系统自动匹配字典 ID。
查询工作流
已知公司全称 → detail?name= 精确匹配，返回一条或空
已知信用代码 → detail?tax_number= 精确匹配
模糊搜索 → list?keyword= 分页返回
浏览全部 → list?page=1&limit=20 分页返回
响应处理
统一格式 {"status":200,"message":"success","data":{...}}。status=200 成功，status=500 失败（展示 message）。
列表返回 data.list.data（数组）+ data.list.total（总数），用 page/limit 分页。
显示规范
- 客户详情展示：公司名、法定代表人、注册资本、成立日期、信用代码、状态、地址、经营范围、行业
- 列表展示：公司名、行业、法定代表人、最后跟进时间
- 永远不要向用户暴露内部 ID，用公司名称代替
注意事项
- 行业/等级/来源/分组四个字典字段如果值不在系统字典中，API 会自动创建
- 公司名重复返回"客户名称已存在"，不要重试，引导用户查已有记录
- 请求前确认
$OPENCRM_KEY已设置 - 完整字段列表见
references/fields.md