客户
录入客户、维护公司资料、补充跟进与调整归属。
客户与跟进
录入使用 phone，从现有客户权益集成查询公司。该集成当前仅在默认空间提供，其他空间会返回未配置提示。
修改客户需要 externalCompanyId、companyName，可传 contactEmails 和 remark。externalCompanyId 来自客户详情的 companies。
跟进 occurredAt 使用上海时区的 YYYY-MM-DDTHH:mm。创建支持既有跟进类型；赠送权益、赔付和重置密码会调用现有外部服务，请在明确意图后使用。
客户转交、收回和删除沿用管理员权限。修改与删除跟进受既有角色和时间限制；activityId 必须属于路径中的客户。响应不返回重置密码等权益执行结果中的秘密。
接口参考
查询客户列表
/api/v1/workspaces/{workspaceId}/customers
响应 data 字段（列表元素）
- id
- 客户 ID
- name
- 客户名称
- phone
- 联系电话
- notes
- 备注，可为空
- managerId
- 客户经理 ID，可为空
- createdById
- 创建者 ID
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- companies
- 仅详情：externalCompanyId、name、contactEmails、remark
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询客户详情
/api/v1/workspaces/{workspaceId}/customers/{id}
响应 data 字段
- id
- 客户 ID
- name
- 客户名称
- phone
- 联系电话
- notes
- 备注，可为空
- managerId
- 客户经理 ID，可为空
- createdById
- 创建者 ID
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- companies
- 仅详情：externalCompanyId、name、contactEmails、remark
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
按手机号录入客户
/api/v1/workspaces/{workspaceId}/customers
| 参数 | 类型 | 说明 |
|---|---|---|
| phone* | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"phone":"13800000000"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
修改客户
/api/v1/workspaces/{workspaceId}/customers/{id}
| 参数 | 类型 | 说明 |
|---|---|---|
| externalCompanyId* | string | 沿用业务表单规则 |
| companyName* | string | 沿用业务表单规则 |
| contactEmails | string | 沿用业务表单规则 |
| remark | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"externalCompanyId":"1","companyName":"示例公司"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
删除客户
/api/v1/workspaces/{workspaceId}/customers/{id}
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request DELETE "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
转交客户
/api/v1/workspaces/{workspaceId}/customers/{id}/transfer
| 参数 | 类型 | 说明 |
|---|---|---|
| newManagerId* | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/transfer" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"newManagerId":"<newManagerId>"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
收回客户
/api/v1/workspaces/{workspaceId}/customers/{id}/reclaim
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/reclaim" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询跟进记录
/api/v1/workspaces/{workspaceId}/customers/{id}/activities
响应 data 字段（列表元素）
- id
- 跟进 ID
- type
- 跟进类型
- title
- 标题
- content
- 内容，可为空
- occurredAt
- 发生时间 ISO 8601
- createdById
- 记录者 ID
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- attachmentKey
- 附件引用，可为空
- attachmentName
- 附件名称，可为空
- attachmentSize
- 附件字节数，可为空
- attachmentMimeType
- 附件 MIME，可为空
- downloadUrl
- 有关联附件时返回的鉴权下载入口
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/activities" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
添加跟进记录
/api/v1/workspaces/{workspaceId}/customers/{id}/activities
| 参数 | 类型 | 说明 |
|---|---|---|
| type* | string | TRAINING / CALL / MEETING / ONBOARDING / NEW_USER_EXPERIENCE / GIFT_POINTS / COMPENSATION_POINTS / RESET_PASSWORD / ISSUE / FEEDBACK / FOLLOW_UP / INVOICE / OTHER |
| title* | string | 沿用业务表单规则 |
| content | string | 沿用业务表单规则 |
| occurredAt* | string | 上海时区本地时间 YYYY-MM-DDTHH:mm |
| attachmentKey | string | 沿用业务表单规则 |
| attachmentName | string | 沿用业务表单规则 |
| attachmentSize | string | 沿用业务表单规则 |
| attachmentMimeType | string | 沿用业务表单规则 |
| pointAmount | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/activities" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"type":"TRAINING","title":"<title>","content":"请跟进首页文案调整","occurredAt":"2026-11-03T10:00"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
编辑跟进记录
/api/v1/workspaces/{workspaceId}/customers/{id}/activities/{activityId}
| 参数 | 类型 | 说明 |
|---|---|---|
| type* | string | TRAINING / CALL / MEETING / ONBOARDING / NEW_USER_EXPERIENCE / GIFT_POINTS / COMPENSATION_POINTS / RESET_PASSWORD / ISSUE / FEEDBACK / FOLLOW_UP / INVOICE / OTHER |
| title* | string | 沿用业务表单规则 |
| content | string | 沿用业务表单规则 |
| occurredAt* | string | 上海时区本地时间 YYYY-MM-DDTHH:mm |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/activities/{activityId}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"type":"TRAINING","title":"<title>","content":"请跟进首页文案调整","occurredAt":"2026-11-03T10:00"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
删除跟进记录
/api/v1/workspaces/{workspaceId}/customers/{id}/activities/{activityId}
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request DELETE "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/{id}/activities/{activityId}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
上传附件
/api/v1/workspaces/{workspaceId}/customers/attachments
响应 data 字段
- id
- 附件 ID
- objectKey
- 存储引用
- name
- 文件名
- mimeType
- MIME 类型
- size
- 字节数
- downloadUrl
- 需要 Bearer Key 的相对下载地址
- attachmentKey
- 跟进或收支所用的附件引用
- attachmentName
- 附件名称
- attachmentSize
- 字节数字符串
- attachmentMimeType
- MIME 类型
- media
- 仅交流上传：用于发布时关联的媒体对象
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/customers/attachments" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--form "file=@./example.png"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。