供应商
维护供应商档案并记录沟通与业务进展。
档案与权限
仅管理员和主管可访问供应商。税号在空间内不能重复，删除供应商及删除跟进沿用管理员限制。
跟进 type 支持 CALL、MEETING、FOLLOW_UP、CONTRACT、PAYMENT、INVOICE、ISSUE、OTHER。PAYMENT 是业务记录类型，不会发起付款。
创建或修改档案提交完整字段；可选字段省略时会按网页表单规则清空。
接口参考
查询供应商列表
/api/v1/workspaces/{workspaceId}/suppliers
响应 data 字段（列表元素）
- id
- 供应商 ID
- name
- 供应商名称
- taxId
- 税号，可为空
- bankAccount
- 银行账号，可为空
- bankName
- 银行名称，可为空
- contactPerson
- 联系人，可为空
- contactPhone
- 联系电话，可为空
- address
- 地址，可为空
- remark
- 备注，可为空
- createdById
- 创建者 ID
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询供应商详情
/api/v1/workspaces/{workspaceId}/suppliers/{id}
响应 data 字段
- id
- 供应商 ID
- name
- 供应商名称
- taxId
- 税号，可为空
- bankAccount
- 银行账号，可为空
- bankName
- 银行名称，可为空
- contactPerson
- 联系人，可为空
- contactPhone
- 联系电话，可为空
- address
- 地址，可为空
- remark
- 备注，可为空
- createdById
- 创建者 ID
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询跟进记录
/api/v1/workspaces/{workspaceId}/suppliers/{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/suppliers/{id}/activities" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
添加跟进记录
/api/v1/workspaces/{workspaceId}/suppliers/{id}/activities
| 参数 | 类型 | 说明 |
|---|---|---|
| type* | string | CALL / MEETING / FOLLOW_UP / CONTRACT / PAYMENT / INVOICE / ISSUE / OTHER |
| title* | string | 沿用业务表单规则 |
| content | string | 沿用业务表单规则 |
| occurredAt* | string | 上海时区本地时间 YYYY-MM-DDTHH:mm |
| attachmentKey | string | 沿用业务表单规则 |
| attachmentName | string | 沿用业务表单规则 |
| attachmentSize | string | 沿用业务表单规则 |
| attachmentMimeType | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers/{id}/activities" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"type":"CALL","title":"<title>","content":"请跟进首页文案调整","occurredAt":"2026-11-03T10:00"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
编辑跟进记录
/api/v1/workspaces/{workspaceId}/suppliers/{id}/activities/{activityId}
| 参数 | 类型 | 说明 |
|---|---|---|
| type* | string | CALL / MEETING / FOLLOW_UP / CONTRACT / PAYMENT / INVOICE / ISSUE / 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/suppliers/{id}/activities/{activityId}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"type":"CALL","title":"<title>","content":"请跟进首页文案调整","occurredAt":"2026-11-03T10:00"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
删除跟进记录
/api/v1/workspaces/{workspaceId}/suppliers/{id}/activities/{activityId}
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request DELETE "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers/{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}/suppliers
| 参数 | 类型 | 说明 |
|---|---|---|
| name* | string | 沿用业务表单规则 |
| taxId | string | 沿用业务表单规则 |
| bankAccount | string | 沿用业务表单规则 |
| bankName | string | 沿用业务表单规则 |
| contactPerson | string | 沿用业务表单规则 |
| contactPhone | string | 沿用业务表单规则 |
| address | string | 沿用业务表单规则 |
| remark | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"服务费用"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
修改供应商
/api/v1/workspaces/{workspaceId}/suppliers/{id}
| 参数 | 类型 | 说明 |
|---|---|---|
| name* | string | 沿用业务表单规则 |
| taxId | string | 沿用业务表单规则 |
| bankAccount | string | 沿用业务表单规则 |
| bankName | string | 沿用业务表单规则 |
| contactPerson | string | 沿用业务表单规则 |
| contactPhone | string | 沿用业务表单规则 |
| address | string | 沿用业务表单规则 |
| remark | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"服务费用"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
删除供应商
/api/v1/workspaces/{workspaceId}/suppliers/{id}
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request DELETE "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/suppliers/{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}/suppliers/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/suppliers/attachments" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--form "file=@./example.png"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。