# 10 工单接口

注意: 工单接口对应 CJ 客户端「My CJ > 工单」的全部功能。典型流程是：先用「工单类型」拿到问题类型与必填项 → 「提交工单」建单 → 用「工单列表」「工单详情」「留言记录」跟进 → 「回复工单」补充信息 → 「标记完成」结单。带附件时必须先调「上传附件」把文件转存到 CJ，再把返回的地址填进提单/回复。

状态说明（重要）: 本组接口的 status 只使用下面这套语义化取值，入参和出参是同一套，不要传数字：

取值含义能否用于列表筛选

AWAITING_CJ_REPLY 等待 CJ 处理是

AWAITING_YOUR_REPLY 等待你回复/确认是

COMPLETED 已完成是

EXPIRED 已失效是

REVIEWED 已评价是

ON_HOLD 已挂起否（仅出现在返回值中）

COLLABORATING 协作处理中否（仅出现在返回值中）

传 ON_HOLD / COLLABORATING / 数字 / 其它值筛选会返回参数错误，不会被当作"不筛选"处理。

取值	含义	能否用于列表筛选
`AWAITING_CJ_REPLY`	等待 CJ 处理	是
`AWAITING_YOUR_REPLY`	等待你回复/确认	是
`COMPLETED`	已完成	是
`EXPIRED`	已失效	是
`REVIEWED`	已评价	是
`ON_HOLD`	已挂起	否（仅出现在返回值中）
`COLLABORATING`	协作处理中	否（仅出现在返回值中）

调用频率（重要）：本组接口的限流为 1 次/秒。连续调用会返回 1600200 Too Many Requests, QPS limit is 1 time/1second。请串行调用并在两次请求之间留出间隔，不要按并发设计——批量拉取请用分页（pageSize 最大 100），而不是并发打多个请求。

# 1 工单列表（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/list

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/ticket/list' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data '{"pageNum":1,"pageSize":20,"status":"AWAITING_YOUR_REPLY"}'

参数名称	参数意义	参数类型	是否必传	长度	备注
pageNum	页码	integer	否		从 1 开始，默认 1
pageSize	每页条数	integer	否		默认 20，最大 100，超出返回参数错误
searchType	搜索维度	string	否		`TICKET_NO` / `CJ_ORDER_NO` / `YOUR_ORDER_NO`，与 search 配对使用
search	搜索值	string	否	100
ticketTypeId	工单类型 id	long	否		取自「工单类型」接口
status	工单状态	string	否		见上方状态说明
shopIds	店铺 id 列表	string[]	否		取自店铺接口 `/shop/getShops`

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "pageNum": 1,
        "pageSize": 20,
        "total": 1,
        "list": [
            {
                "ticketId": "9001",
                "ticketNo": "T202609050001",
                "ticketType": "Service Consultation",
                "issueType": "Fulfillment Service Consultation",
                "status": "AWAITING_YOUR_REPLY",
                "createTime": 1788500000000,
                "lastUpdateTime": 1788500100000,
                "cjOrderNo": ["CJ2026090400001"],
                "yourOrderNo": ["#1024"],
                "shopName": ["my-shop"],
                "canRemind": true,
                "hasReminded": false,
                "createdByCj": false,
                "unread": true
            }
        ]
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

返回字段	字段意思	字段类型	备注
ticketId	工单 id	string	其它接口用它定位工单
ticketNo	工单编号	string	展示用
ticketType	工单类型名	string
issueType	问题类型名	string
status	工单状态	string	见状态说明；极少数历史状态可能为 null
createTime	创建时间	long	UTC 毫秒时间戳
lastUpdateTime	最后更新时间	long	UTC 毫秒时间戳
cjOrderNo	关联 CJ 订单号	string[]	无关联时为空数组
yourOrderNo	你的订单号	string[]	无关联时为空数组
shopName	关联店铺名	string[]	无关联时为空数组
canRemind	当前是否可催单	boolean
hasReminded	是否已催过单	boolean	一张工单只能催一次
createdByCj	是否 CJ 客服代提	boolean
unread	是否有未读回复	boolean

# 2 工单详情（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/detail?ticketId=9001

参数名称	参数意义	参数类型	是否必传	备注
ticketId	工单 id	string	是	取自工单列表

# 返回字段（在列表字段基础上补充）

返回字段	字段意思	字段类型	备注
message	首条问题描述	string
expectResult	期望结果	string
sku	关联 SKU	string
sourcingId	关联搜品 id	string
canReply	当前是否可回复	boolean	调用回复接口前请先看它
canComplete	当前是否可标记完成	boolean	后勤类工单恒为 false
attachments	附件列表	Object[]	`fileName` / `url`
formList	提交时填写的表单	Object[]	`fieldName` / `value`
evaluation	客户评价	Object	未评价时为 null；`level` / `comment` / `evaluateTime`

提示: 工单不存在、或不属于当前 API 账号，都返回 1609005 Ticket not found（两种情况不作区分）。

# 3 留言记录（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/messages?ticketId=9001&pageNum=1&pageSize=20

参数名称	参数意义	参数类型	是否必传	备注
ticketId	工单 id	string	是
pageNum	页码	integer	否	默认 1
pageSize	每页条数	integer	否	默认 20，最大 100

返回字段	字段意思	字段类型	备注
messageId	留言 id	string
sender	发送方	string	`CJ` 或 `CUSTOMER`
senderName	发送人显示名	string
messageTime	留言时间	long	UTC 毫秒时间戳
messageHtml	留言正文	string	HTML 格式，按 HTML 渲染
messageText	留言纯文本	string	已去标签，供不做 HTML 渲染的场景使用
action	消息动作	string	如 Reply / Resubmit，可能为空
attachments	附件列表	Object[]	`fileName` / `url`

# 4 工单类型（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/types

无入参。返回三层结构：工单类型 → 问题类型 → 表单范式。

{
    "code": 200,
    "data": [
        {
            "ticketTypeId": "1001",
            "ticketTypeName": "Order Issue",
            "questionTypes": [
                {
                    "questionTypeId": "2001",
                    "questionTypeName": "Logistics Issue",
                    "formFields": [
                        {"fieldName": "Order Number", "required": true}
                    ]
                }
            ]
        }
    ],
    "success": true
}

提交工单前必须先调本接口：formFields 中 required=true 的项在提交时必填，且 formList 里只能出现本接口给出的 fieldName——传范式之外的字段会返回参数错误（不会被静默丢弃）。

# 5 提交工单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/create

参数名称	参数意义	参数类型	是否必传	长度	备注
ticketTypeId	工单类型 id	long	是		取自「工单类型」
questionTypeId	问题类型 id	long	是		取自「工单类型」第二层
message	问题描述	string	是	1000
expectResult	期望结果	string	是	1000
formList	表单填写项	Object[]	视范式		`fieldName` / `value`，见「工单类型」
cjOrderNo	关联 CJ 订单号	string	否	100
yourOrderNo	你的订单号	string	否	100
sku	关联 SKU	string	否	100
attachments	附件	Object[]	否		`fileName` / `url`，最多 10 个，url 必须来自「上传附件」接口
requestNo	重复提交保护键	string	否	64	见下方说明，注意它不是幂等键

# 返回

{
    "code": 200,
    "data": {"estimatedHandleTime": 1788600000000},
    "success": true
}

返回字段	字段意思	字段类型	备注
estimatedHandleTime	CJ 预计处理完成时间	long	UTC 毫秒时间戳；CJ 未给出时为 null，属正常情况

⚠️ 关于 requestNo 的保护范围（2026-09-07 生产实测修正）：

它只能挡住 5 秒内用同一 requestNo 的重复提交（返回 1609006 Duplicate submit）——这是一把 5 秒过期的并发锁，不是幂等键。

超过 5 秒后用同一个 requestNo 再提交，会新建一张工单。 实测：两次提交间隔 5.7 秒，建出了两张内容相同的工单。

所以网络超时后不能直接重试。正确做法是：先调 POST /ticket/list（按创建时间倒序）确认上一次是否已经建单成功，再决定是否重提。requestNo 的价值只在于挡住"用户连点两次"这类几秒内的重复。

本接口不返回 ticketId。需要拿到刚创建的工单时，请随后调用「工单列表」按创建时间倒序取第一条。

# 6 回复工单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/reply

参数名称	参数意义	参数类型	是否必传	长度	备注
ticketId	工单 id	string	是
message	回复内容	string	是	5~1000
attachments	附件	Object[]	否		同提交工单

调用前请先看「工单详情」的 canReply：并非所有状态都允许回复，状态不允许时返回 1609009。

本接口没有幂等保护：重复调用会产生多条留言，超时后请先用「留言记录」确认是否已经回复成功。

# 7 标记完成（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/complete

参数名称	参数意义	参数类型	是否必传
ticketId	工单 id	string	是

后勤类工单不允许自助结单，会返回 1609009；请先看「工单详情」的 canComplete。

# 8 催单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/remind

参数名称	参数意义	参数类型	是否必传
ticketId	工单 id	string	是

两条限制：一张工单只能催一次（已催过返回 1609010）；距创建时间不足时暂不能催（返回 1609011，稍后可再试）。调用前先看「工单列表/详情」的 canRemind 与 hasReminded，可以省掉一次必然失败的调用。

# 9 工单评价（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/evaluate

参数名称	参数意义	参数类型	是否必传	长度	备注
ticketId	工单 id	string	是
level	评价等级	string	是		`GOOD` / `AVERAGE` / `POOR`
comment	评价说明	string	否	1000

# 10 待处理工单数（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/pendingCount

无入参。

返回字段	字段意思	字段类型	备注
pendingCount	待你处理的工单数	integer	没有待办时为 0
updateTime	统计时间	long	UTC 毫秒时间戳

# 11 上传附件（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/attachment/upload

参数名称	参数意义	参数类型	是否必传	备注
fileName	目标文件名	string	是	必须带扩展名，不能含 `/` `\` `..` 及尖括号引号
sourceUrl	源文件地址	string	是	需可公网下载的 http/https 地址

返回字段	字段意思	字段类型	备注
fileName	文件名	string
url	CJ 附件地址	string	直接填进提交工单/回复的 `attachments`

限制: 单个文件 ≤5MB；扩展名需在 jpg / jpeg / png / bmp / gif / txt / rar / zip / doc / docx / xls / xlsx / pdf / ini / conf / eml 之内；sourceUrl 必须是公网地址（内网、回环地址会被拒绝）。

返回的 url 形如 https://cj-commodity.oss-accelerate.aliyuncs.com/cj-openapi-rest/<日期路径>/<uuid>.png（2026-09-07 生产实测），直接原样填进 attachments 即可，不要自行拼接或改写。

# 12 订单/搜品问题类型（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/order/questionTypes?type=ORDER_ISSUE

参数名称	参数意义	参数类型	是否必传	备注
type	业务类型	string	是	`ORDER_ISSUE` / `PRODUCT_ISSUE`

返回字段	字段意思	字段类型
questionTypeId	问题类型 id	string
questionTypeName	问题类型名	string

本接口与「工单类型」不是同一套数据：针对具体订单/搜品提单时，请用本接口返回的 id。

# 13 针对订单/搜品提交工单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/ticket/order/create

参数名称	参数意义	参数类型	是否必传	长度	备注
businessNo	订单号或搜品 id	string	是	100	type=ORDER_ISSUE 传 CJ 订单号；PRODUCT_ISSUE 传 Sourcing ID
type	业务类型	string	是		`ORDER_ISSUE` / `PRODUCT_ISSUE`
questionTypeId	问题类型 id	long	是		取自「订单/搜品问题类型」
message	问题描述	string	是	1000
expectResult	期望结果	string	是	1000
yourOrderNo	你的订单号	string	否	100
attachments	附件	Object[]	否		同提交工单

本接口没有幂等保护，重复调用会建出多张工单。超时后请先用「工单列表」按订单号确认再决定是否重试。

# 错误码

错误码	说明	处理建议
1609000	不支持的工单状态	检查 status 取值，见开头的状态说明
1609001	该状态不支持筛选	改用可筛选的 5 个状态之一
1609002	pageSize 超过上限	改为 ≤100
1609003	工单查询失败	稍后重试
1609004	不支持的搜索类型	检查 searchType 取值
1609005	工单不存在	工单不存在或不属于当前账号
1609006	重复提交	相同 requestNo 已提交过，无需重试
1609007	工单/问题类型不存在	重新获取问题类型列表
1609008	提交工单失败	稍后重试
1609009	当前状态不允许该操作	先看详情的 canReply / canComplete
1609010	该工单已催单	无需重试
1609011	该工单暂不可催单	稍后再试
1609012	缺少必填表单项 / 传了范式外的字段	对照「工单类型」的 formFields
1609013	不支持的评价等级	使用 GOOD / AVERAGE / POOR
1609014	操作失败	稍后重试
1609015	附件不合法	检查文件名、地址来源与数量
1609016	附件转存失败	确认源地址可公网访问且 ≤5MB
1600200	超过调用频率限制	限流 1 次/秒，请串行调用并留出间隔

← 9 店铺 11 AI 取数 →