https://open.taobao.com/docs/doc.htm?spm=a219a.7629140.0.0.edQuIb&treeId=409&articleId=106976&docType=1
云打印交互协议
简介
- 菜鸟打印组件是以独立进程和打印机交互,而非作为浏览器插件进行打印。
- 浏览器或其他客户端需要通过WebSocket协议与菜鸟打印组件进行通信,支持javascript,java,c/c++,python等常用的语言。
- 若ISV的ERP系统是B/S结构,需要使用以下版本的浏览器来更好的支持WebSocket:
- chrome 45及以上(建议使用chrome的最新版本)
协议格式说明
- 请求协议头:通常,与菜鸟打印组件进行交互,需要发送如下格式的请求协议头:
1
2
3
4
5
|
{
"cmd"
:
"command"
,
"requestID"
:
" unique requestID "
,
"version"
:
"1.0"
}
|
字段说明:
字段名 | 类型 | 说明 | 是否必须 |
---|---|---|---|
cmd | string | 请求的命令名称 | 是 |
requestID | string | 请求的ID,用于唯一标识每个请求,每个客户端自己保证生成唯一ID,如UUID | 是 |
version | string | 协议当前版本,当前为“1.0” | 是 |
- 响应协议头:菜鸟打印组件会返回如下格式的响应头给请求方。
1
2
3
4
|
{
"cmd"
:
"command"
,
"requestID"
:
"unique requestID"
}
|
字段说明:
字段名 | 类型 | 说明 |
---|---|---|
cmd | string | 请求的命令名称 |
requestID | string | 发送请求中的ID,原封不动返回,使客户端能识别出哪个请求对应的响应 |
协议详解
1. 请求打印机列表协议(getPrinters)
请求协议格式如下:
1
2
3
4
5
|
{
"cmd"
:
"getPrinters"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
}
|
响应协议格式如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
{
"cmd"
:
"getPrinters"
,
//需要响应的命令名称,响应获取打印机列表的响应
"requestID"
:
"123458976"
,
"defaultPrinter"
:
"XX快递打印机"
,
"printers"
:[
{
"name"
:
"XX快递打印机"
,
"status"
:
"enable "
,
"type"
:
"thermal"
},
{
"name"
:
"YY物流打印机"
,
"status"
:
"disable"
,
"type"
:
"thermal"
}
]
}
|
字段名 | 类型 | 说明 |
---|---|---|
defaultPrinter | string | 默认打印机 |
name | string | 打印机的名字 |
status | string | 打印机状态 : enable可用; disable不可用 |
type | string | 打印机类型 : thermal为热敏打印机; other为除热敏打印机以外的其他类型 |
2. 请求打印机配置协议(getPrinterConfig)
请求协议格式如下:
1
2
3
4
5
6
|
{
"cmd"
:
"getPrinterConfig"
,
"printer"
:
"菜鸟打印机"
,
"version"
:
"1.0"
,
"requestID"
:
"123456789"
}
|
响应协议格式如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
{
"cmd"
:
"getPrinterConfig"
,
"requestID"
:
"123456789"
,
"status"
:
"success/failed"
,
"msg"
:
"如果出错,错误原因"
,
"printer"
:{
"name"
:
"打印机名称"
,
"needTopLogo"
:
false
,
"needBottomLogo"
:
false
,
"horizontalOffset"
:
1
,
"verticalOffset"
:
2
,
"forceNoPageMargins"
:
true
,
// v0.2.8.3 新增字段
"paperSize"
:{
"width"
:
100
,
"height"
:
180
}
}
}
|
字段名 | 类型 | 说明 |
---|---|---|
status | string | 标示命令成功或失败,取值“success”或者“failed” |
msg | string | 如果出错,错误原因 |
name | string | 打印机名称 |
needTopLogo | bool | 是否需要模板上联的快递logo,true为需要,false为不需要 |
needBottomLogo | bool | 是否需要模板下联的快递logo,true为需要,false为不需要 |
horizontalOffset | float | 水平偏移量 |
verticalOffset | float | 垂直偏移量 |
forceNoPageMargins | bool | 强制设置页面无空边,true为强制设置页面无空边,false为由打印机驱动决定 |
paperSize | object | 打印机纸张的宽度和高度,单位是毫米,整形值 |
3. 弹窗模式配置打印机协议(printerConfig)
请求协议格式如下:
1
2
3
4
5
6
|
{
"cmd"
:
"printerConfig"
,
"printer"
:
"中通专用打印机"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
}
|
响应协议格式如下:
1
2
3
4
5
6
7
|
{
"cmd"
:
"printerConfig"
,
"requestID"
:
"123458976"
,
"printer"
:
"中通专用打印机"
,
"status"
:
"success"
,
//配置成功还是失败
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
字段名 | 类型 | 说明 |
---|---|---|
printer | string | 要配置的打印机 |
status | string | 消息处理结果,success:成功; failed:失败 |
msg | string | 如果成功,则为空;如果失败,则为失败原因 |
4. 重置打印机配置协议(resetPrinterPreferences)
此协议是将当前用户的打印机设置重置为系统全局缺省值,如将打印机首选项配置的偏移、纸张尺寸等重置为系统全局缺省值。
此协议当前对奇锐系列的打印机无效。
请求协议格式如下:
1
2
3
4
5
6
|
{
"cmd"
:
"resetPrinterPreferences"
,
//重置打印机配置命令
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"printer"
:
"菜鸟专用打印机"
}
|
字段名 |类型 |说明 |是否必须
printer |string |打印机名 |是
响应协议格式如下:
1
2
3
4
5
6
|
{
"cmd"
:
"resetPrinterPreferences"
,
//需要响应的命令名称,响应重置打印机配置命令的响应
"requestID"
:
"123458976"
,
"status"
:
"success"
,
//重置打印机配置成功还是失败
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
字段名 | 类型 | 说明
printer | string | 打印机名称
status | string | 标示命令成功或失败,取值“success”或者“failed”
msg| string | 如果出错,错误原因
5. API模式配置打印机协议(setPrinterConfig)
请求协议格式如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
{
"cmd"
:
"setPrinterConfig"
,
"requestID"
:
"123458976"
,
"version"
:”
1.0
”,
"printer"
:
{
"name"
:
"菜鸟模板专用打印机"
"needTopLogo"
:
true
,
"needBottomLogo"
:
false
,
"horizontalOffset"
:
0.5
,
"verticalOffset"
:
0.7
,
"forceNoPageMargins"
:
true
,
// v0.2.8.3 新增字段
"paperSize"
:{
"width"
:
100
,
"height"
:
180
}
}
}
|
字段名 | 类型 | 说明 | 是否必须 |
---|---|---|---|
name | string | 打印机名 | 是 |
needTopLogo | bool | 是否需要模板上联的快递logo,true为需要,false为不需要;默认为true | 否 |
needBottomLogo | bool | 是否需要模板下联的快递logo,true为需要,false为不需要;默认为true | |
horizontalOffset | float | 设置水平偏移量 | 否 |
verticalOffset | float | 设置垂直偏移量 | 否 |
forceNoPageMargins | bool | 强制设置页面无空边,true为强制设置页面无空边,false为由打印机驱动决定 | |
paperSize | int | 设置打印机纸张的宽度和高度,单位是毫米 | 否 |
响应协议格式如下:
1
2
3
4
5
6
|
{
"cmd"
:
"setPrinterConfig"
,
"requestID"
:
"123458976"
,
"status"
:
"success"
,
"msg"
:
"if failed ,some tips, if success,nothing"
}
|
字段名 | 类型 | 说明 |
---|---|---|
status | string | 消息处理结果。success:成功;failed:失败 |
msg | string | 如果成功,则为空;如果失败,则为失败原因 |
注:如果要保持某个配置不变,应省略对应的配置字段。
6. 发送打印/预览数据协议(print)
注:因为打印机质量乘次不齐,建议 1 个 task 使用 一个 document,可以有效避免重打问题;
非加密请求协议格式如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
{
"cmd"
:
"print"
,
"requestID"
:
"123458976"
,
"version"
:
"1.0"
,
"task"
: {
"taskID"
:
"7293666"
,
"preview"
:
false
,
"printer"
:
""
,
"previewType"
:
"pdf"
,
"firstDocumentNumber"
:
10
,
"totalDocumentCount"
:
100
,
"documents"
: [{
"documentID"
:
"0123456789"
,
"contents"
: [{
"data"
: {
"recipient"
: {
"address"
: {
"city"
:
"杭州市"
,
"detail"
:
"良睦路999号乐佳国际大厦2号楼小邮局"
,
"district"
:
"余杭区"
,
"province"
:
"浙江省"
,
"town"
:
""
},
"mobile"
:
"13012345678"
,
"name"
:
"菜鸟网络"
,
"phone"
:
"057112345678"
},
"routingInfo"
: {
"consolidation"
: {
"name"
:
"杭州"
,
"code"
:
"hangzhou"
},
"origin"
: {
"name"
:
"杭州"
,
"code"
:
"POSTB"
},
"sortation"
: {
"name"
:
"杭州"
},
"routeCode"
:
"123A-456-789"
},
"sender"
: {
"address"
: {
"city"
:
"杭州市"
,
"detail"
:
"文一西路1001号阿里巴巴淘宝城5号小邮局"
,
"district"
:
"余杭区"
,
"province"
:
"浙江省"
,
"town"
:
""
},
"mobile"
:
"13012345678"
,
"name"
:
"阿里巴巴"
,
"phone"
:
"057112345678"
},
"shippingOption"
: {
"code"
:
"COD"
,
"services"
: {
"SVC-COD"
: {
"value"
:
"200"
},
|