雄韬 XTOCN · OpenCRM

Base URL：https://my.xtocn.com/api | 认证：Authorization: Bearer $OPENCRM_KEY

决策表

新增客户工作流

用户粘贴了原始文本（企查查/天眼查等）

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