POST 新建服务工单

POST 新建售后服务工单。body 为 JSON：必填 title（工单标题）、type（工单类型名称，须为启用中的类型）；正式建单（asDraft 不传或 false）还必填 customerId（服务客户ID）、usageLocation（产品使用地）、contactPhone（联系电话）、serviceAddress（服务地点）、faultDescription（客户问题或服务诉求）、serviceMode（服务方式：远程支持/上门服务/客户自处理指导/备件寄送/定期巡检）、serviceScopeLines（服务项目数组，至少1行，每行必填 name 名称、qty 数量>0、unit 单位；可选 disposition 费用判定 PENDING/IN_CONTRACT/IN_WARRANTY/EXTRA_CHARGE、basis 判定依据、unitPrice 额外收费单价、description）；可选 asDraft（true 存为「待提交」草稿，此时只需 title/type）、urgency（紧急/高/中/低，默认中）、customerName、contactPerson、primarySourceType（SALES_ORDER/SALES_CONTRACT/SERVICE_CONTRACT/PROJECT/CUSTOMER_ONLY）与 primarySourceId/primarySourceNo（非 CUSTOMER_ONLY 时需指定来源单据）、acceptanceChannel、salesOrderId/contractId/projectId、symptom、impact、expectedTime（客户期望时间）、serviceLiability（free/quote/pending）、items（设备明细：productName、productModel、sn、qty、unit）、attachments、customFields（自定义字段，key=fieldName）。建成后状态为「待受理」（草稿为「待提交」），单号由服务端生成。

接口编码	所需范围	后端接口
sales.service-order.create	sales:write	POST /v1/service-orders/create（comap-sales）

必填字段

字段	依据
title	参数说明、接口规格
type	参数说明、接口规格
customerId	参数说明
usageLocation	参数说明、接口规格
contactPhone	参数说明
serviceAddress	参数说明
faultDescription	参数说明
serviceMode	参数说明
serviceScopeLines	参数说明
serviceScopeLines[].name	参数说明、接口规格
serviceScopeLines[].qty	参数说明
serviceScopeLines[].unit	参数说明
items[].productName	接口规格
attachments[].fileId	接口规格

条件必填（如「某状态时必填」）不在此表，以上方参数说明为准。 判定规则见必填字段的判定。

请求体字段（body）

字段	类型	必填	说明
title	string	是	工单标题
type	string	是	工单类型名称，取值来自启用中的 t_service_order_type.name
source	string	—	报修来源：客户来电/客户门户/内部创建/销售订单/项目/邮件
urgency	string	—	紧急程度：紧急/高/中/低，留空默认「中」
isShutdown	integer(int32)	—	是否停机：0否 1是
customerId	integer(int64)	—	客户ID
customerName	string	—	客户名称快照。后端不反查回填 —— 前端从客户选择器带出，留空则列表页客户列为空且搜不到
primarySourceType	string	—	主要关联来源类型：SALES_ORDER/SALES_CONTRACT/SERVICE_CONTRACT/PROJECT/CUSTOMER_ONLY
primarySourceId	integer(int64)	—	主要关联来源ID
primarySourceNo	string	—	主要关联来源单号
primarySourceStorageType	string	—	主要关联来源存储类型
acceptanceChannel	string	—	受理渠道
serviceCustomerId	integer(int64)	—	服务客户ID（Q2 三类客户一致，前端三字段填同值）
serviceCustomerName	string	—	服务客户名称
contractCustomerId	integer(int64)	—	合同客户ID
contractCustomerName	string	—	合同客户名称
settlementCustomerId	integer(int64)	—	结算客户ID
settlementCustomerName	string	—	结算客户名称
contactPerson	string	—	联系人
contactPhone	string	—	联系电话
serviceAddress	string	—	服务地址
usageLocation	string	是	产品使用地
usageLocationCorrected	integer(int32)	—	使用地是否由现场提交人纠正：0否 1是
repairTicketId	integer(int64)	—	来源报修单ID；从报修池转单时传入
productName	string	—	主产品名称；多产品时取 items 第一条
productModel	string	—	主产品型号
sn	string	—	主产品SN
salesOrderId	integer(int64)	—	关联销售订单ID
salesOrderNo	string	—	关联销售订单号
contractId	integer(int64)	—	关联合同ID
contractNo	string	—	关联合同号
projectId	integer(int64)	—	关联项目ID
projectName	string	—	关联项目名称
faultDescription	string	—	问题描述 / 服务内容
symptom	string	—	故障现象
impact	string	—	影响范围
expectedTime	string(date-time)	—	客户期望时间
serviceMode	string	—	服务方式：远程支持/上门服务/客户自处理指导/备件寄送/定期巡检
needAppointment	integer(int32)	—	是否需要预约：0否 1是
submittedDevice	string	—	提交渠道设备，如 移动端·iOS / Web
isChargeable	integer(int32)	—	是否有偿服务：0否 1是
serviceLiability	string	—	服务责任：free免费服务 / quote需要报价 / pending待人工判定
warrantyStatus	string	—	手填质保状态：质保内/已过保/未配置质保/需人工判断（仅自动匹配不到时生效）
warrantyStart	string(date-time)	—	手填质保起始日期（仅自动匹配不到时生效）
warrantyEnd	string(date-time)	—	手填质保截止日期（仅自动匹配不到时生效）
warrantyCardId	integer(int64)	—	手填/选定的质保卡ID（一般手填场景为空）
asDraft	boolean	—	是否存为草稿：true 建成待提交，缺省建成待受理
items17	ServiceOrderItemDTO[]	—	涉及产品明细
serviceScopeLines10	ServiceOrderServiceLineDTO[]	—	服务项目（服务/收费行）
attachments6	ServiceAttachmentDTO[]	—	建单附件
customFields	object	—	自定义字段值，key=fieldName

「必填」仅反映接口规格声明的部分。服务内还有未体现在规格里的校验， 标「—」不等于可以不传；租户在主站配置的字段必填不约束本接口。 详见必填字段的判定与字段清单与自定义字段。

请求示例

curl -X POST https://open.risemap.cn/v1/api/invoke \
  -H "Authorization: Bearer <访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiCode": "sales.service-order.create",
    "body": {
      "title": "string",
      "type": "string",
      "usageLocation": "string"
    }
  }'

响应 data 字段

字段	类型	必填	说明
id	integer(int64)	—	工单ID
orderNo	string	—	工单编号
title	string	—	工单标题
type	string	—	工单类型
source	string	—	报修来源
primarySourceType	string	—	主要关联来源类型
primarySourceNo	string	—	主要关联来源单号
status	string	—	工单状态（原始值）
canonicalStatus	string	—	归一后的规范状态
derivedView	string	—	派生视图码：appointment（待预约），其余为空
urgency	string	—	紧急程度
isShutdown	integer(int32)	—	是否停机：0否 1是
customerId	integer(int64)	—	客户ID
customerName	string	—	客户名称
contactPerson	string	—	联系人
contactPhone	string	—	联系电话
usageLocation	string	—	产品使用地
usageLocationCorrected	integer(int32)	—	使用地是否由现场提交人纠正：0否 1是
repairTicketId	integer(int64)	—	来源报修单ID
repairTicketNo	string	—	来源报修单号
productName	string	—	主产品名称
productModel	string	—	主产品型号
sn	string	—	主产品SN
warrantyStatus	string	—	质保状态：质保内/已过保/未配置质保/需人工判断
assigneeId	integer(int64)	—	负责工程师ID
assignee	string	—	负责工程师姓名
dept	string	—	所属服务团队
serviceMode	string	—	服务方式
needAppointment	integer(int32)	—	是否需要预约：0否 1是
planStart	string(date-time)	—	计划上门时间
isOvertime	integer(int32)	—	是否超时：0否 1是
slaDeadlineAt	string(date-time)	—	响应截止时间
slaPausedAt	string(date-time)	—	当前暂停开始时间
slaBreachedAt	string(date-time)	—	实际超时时间点
responseMins	integer(int32)	—	响应时长（分钟）
mergedIntoId	integer(int64)	—	被合并到的目标工单ID
splitFromId	integer(int64)	—	拆分来源父工单ID
isChargeable	integer(int32)	—	是否有偿服务：0否 1是
serviceLiability	string	—	服务责任：free免费服务 / quote需要报价 / pending待人工判定
chargeStatus	string	—	商业状态
partRequestCount	integer(int32)	—	关联备件申请数量
unreconciledPartQty	number	—	备件未闭环数量合计
confirmStatus	string	—	客户确认状态
createdBy	string	—	创建人
createTime	string(date-time)	—	创建时间
customFields	object	—	自定义字段值，key 为字段名；无读权限的字段不会出现
serviceAddress	string	—	服务地址
salesOrderId	integer(int64)	—	关联销售订单ID
salesOrderNo	string	—	关联销售订单号
contractId	integer(int64)	—	关联合同ID
contractNo	string	—	关联合同号
projectId	integer(int64)	—	关联项目ID
projectName	string	—	关联项目名称
warrantyStart	string(date-time)	—	质保起始（快照）
warrantyEnd	string(date-time)	—	质保截止（快照）
warrantyCardId	integer(int64)	—	主质保卡ID
warrantyCardIds	string	—	全部匹配到的质保卡ID，逗号分隔
faultDescription	string	—	问题描述 / 服务内容
symptom	string	—	故障现象
impact	string	—	影响范围
expectedTime	string(date-time)	—	客户期望时间
planEnd	string(date-time)	—	预计结束时间
handleHours	number	—	处理时长（小时）
submittedDevice	string	—	提交渠道设备
rejectReason	string	—	驳回/拒单原因
slaLevel	string	—	SLA 等级
slaTotalPausedMins	integer(int32)	—	累计暂停分钟数
slaPauseReason	string	—	暂停原因
splitNote	string	—	拆分说明
mergedFromIds	integer(int64)[]	—	合并进来的源工单ID列表
childIds	integer(int64)[]	—	拆分出的子工单ID列表
items30	ServiceOrderItemVO[]	—	涉及产品明细
primarySourceId	integer(int64)	—	主要关联来源ID
primarySourceStorageType	string	—	主要关联来源存储类型
acceptanceChannel	string	—	受理渠道
serviceCustomerId	integer(int64)	—	服务客户ID
serviceCustomerName	string	—	服务客户名称
contractCustomerId	integer(int64)	—	合同客户ID
contractCustomerName	string	—	合同客户名称
settlementCustomerId	integer(int64)	—	结算客户ID
settlementCustomerName	string	—	结算客户名称
sourceVersion	integer(int32)	—	来源版本（来源重确认乐观锁，重确认时需原样回传）
fees27	ServiceOrderFeeVO[]	—	费用行（含五态收费责任，逐项核定用）
attachments8	ServiceAttachmentVO[]	—	工单附件
allowedActions	string[]	—	当前允许的操作动作码
closeType	string	—	关闭类型
closeReason	string	—	关闭原因
closedAt	string(date-time)	—	关闭时间
closedBy	string	—	关闭操作人
closedFromStatus	string	—	关闭前的工单状态
serviceCycleNo	integer(int32)	—	服务周期号
updateTime	string(date-time)	—	更新时间
version	integer(int32)	—	乐观锁版本，编辑时需原样回传

错误处理

响应统一信封 { code, message, data }，code == 200 为成功。以下是本接口可能返回的开放平台层错误：

错误码	说明	可重试
92101	访问凭证无效	否
92201	接口未登记或已停用	否
92202	超出凭证授权范围——本接口需 sales:write	否
92204	绑定员工无此接口的功能权限	否
92203	上游服务调用失败	先查询处理结果，禁止盲目重试
92301	请求过于频繁	是
92205	写操作处理超时，结果未知（下游可能仍在执行）	否，先查询确认结果
92302	有参数相同的写请求正在处理中	等待并确认前一次结果，勿重复提交

除此之外，comap-sales 自身的业务校验失败会原样透传其业务码与提示 （如字段校验、状态不允许、数据不存在），这类码不在开放平台的号段内， 以响应里的 message 为准。完整的平台层错误码见错误码说明。

← 返回服务工单