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"
},
"TIMED-DELIVERY"
: {
|
最低0.47元/天 解锁文章
3280
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
