**温馨提示：**小红书新版电子面单已上线，11.30开始按照比例灰度商家。新对接的自研商家建议直接接入新版电子面单，在小红书千帆系统电子面单页面的顶部可以点击新版电子面单进入新版。如需查阅旧版打印组件协议，请查看文档：小红书电子面单打印组件协议（旧）

一、简介

云打印客户端是以独立进程和打印机交互（非作为浏览器插件进行打印）。

浏览器或其他客户端需要通过 WebSocket，协议与云打印客户端进行通信，支持javascript，java，c/c++，python等常用的语言（建议使用对应开发与语言支持的 Websockt 库）。

小红书打印组件的端口是10818，连接本机打印组件地址：ws://localhost:10818，暂时不支持wss协议

若 ISV 的 ERP 系统是B/S结构，建议使用如下版本浏览器:

chrome 45及以上（建议使用chrome的最新版本）；

二、协议格式说明

请求协议头：

{
"cmd": "command",
"requestID": "unique requestID",
"version": "1.0"
}

字段说明：

字段名	类型	说明	是否必须
cmd	string	请求的命令名称	是
requestID	string	请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID	是
version	string	协议当前版本，当前为“1.0”	是

响应协议头：

{
"cmd": "command",
"requestID": "unique requestID"
}

字段说明:

字段名	类型	说明
cmd	string	请求的命令名称
requestID	string	发送请求中的ID,原封不动返回，使客户端能识别出哪个请求对应的响应

三、协议详解

1. 获取打印机列表(getPrinters)

请求协议格式如下:

{
    "cmd": "getPrinters",
    "requestID": "123458976",
    "version": "1.0"
}

响应协议格式如下:

{
    "cmd": "getPrinters",
    "requestID": "123458976",
    "defaultPrinter": "XX快递打印机",
    "printers": [
        {
            "name": "XX快递打印机"
        },
        {
            "name": "YY物流打印机"
        }
    ]
}

字段名	类型	说明
defaultPrinter	string	默认打印机
name	string	打印机的名字

2. 发送打印/预览数据协议(print)

注：因为打印机质量乘次不齐，建议 1 个 task 使用一个 document，可以有效避免重打问题；

预览流程：

打印流程：

请求协议格式（明文数据）如下:

{
    "cmd": "print",
    "requestID": "123456789",
    "version": "1.0",
    "task": {
        "taskID": "1",
        "preview": false,
        "printer": "HPRT_N41BT",
        "previewType": "pdf",
        "documents": [
            {
                "documentID": "10000001",
                "contents": [
                    {
                        "data": {
                            "cpCode": "yunda",
                            "packageInfo": {
                                "goodValue": 0,
                                "height": 0,
                                "id": "137108374937707333",
                                "items": [
                                    {
                                        "count": 1,
                                        "name": "M&M's 潮流盲盒商品类目"
                                    }
                                ],
                                "length": 0,
                                "totalPackagesCount": 0,
                                "volume": 0,
                                "weight": 0,
                                "width": 0
                            },
                            "recipient": {
                                "address": {
                                    "city": "上海市",
                                    "detail": "徐家汇路268号LUONE凯德晶萃广场21楼（小红书公司E栋）",
                                    "district": "黄浦区",
                                    "province": "上海",
                                    "town": "淮海中路街道"
                                },
                                "mobile": "",
                                "name": "郑*",
                                "phone": "130***9667"
                            },
                            "routingInfo": {
                                "endCode": "",
                                "endName": "LuOne凯德晶萃广场",
                                "endType": 3,
                                "firstCode": "300B",
                                "fullCode": "300B R039-01 16",
                                "packageCenterCode": "20000001",
                                "packageCenterName": "上海-同城-省内件",
                                "secondCode": "R039-01",
                                "thirdCode": "16"
                            },
                            "sender": {
                                "address": {
                                    "city": "上海市",
                                    "detail": "徐家汇路218号LuOne凯德晶萃广场办公楼",
                                    "district": "黄浦区",
                                    "province": "上海",
                                    "town": "打浦桥街道"
                                },
                                "mobile": "",
                                "name": "测试",
                                "phone": "18100000001"
                            },
                            "shippingOption": {
 
                            },
                            "waybillCode": "312531852577718"
                        },
                        "templateURL": "https://cloudprint.xiaohongshu.com/template/standard/15/1"
                    },
                    {
                        "data": {
                            "item": [
                                "iphone14 红色 256G/1",
                                "iphone14 黑色 256G/1"
                            ],
                            "order": [
                                "P680942792256239451"
                            ],
                            "buyerMemo": [
                                "买家：打包注意点,尽快送达"
                            ],
                            "sellerMemo": [
                                "卖家：请及时签收"
                            ]
                        },
                        "templateURL": "https://cloudprint.xiaohongshu.com/template/standard/7/2"
                    }
                ]
            }
        ]
    }
}

请求协议格式（密文数据）如下，温馨提示：如果想要更改面单发件人信息可以参考文档后面的addData模式:

{
    "cmd": "print",
    "requestID": "123456789",
    "version": "1.0",
    "task": {
        "taskID": "1",
        "preview": false,
        "printer": "PDFwriter",
        "previewType": "pdf",
        "documents": [
            {
                "documentID": "10000001",
                "contents": [
                    {
"encryptedData":"AES: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",
                        "ver":"waybill_print_xiaohongshu_secret",
                        "templateURL": "https://cloudprint.xiaohongshu.com/template/standard/15/1"
                    },
                    {
                        "data": {
                            "item": [
                                "iphone14 红色 256G/1",
                                "iphone14 黑色 256G/1"
                            ],
                            "order": [
                                "P680942792256239451"
                            ],
                            "buyerMemo": [
                                "买家：打包注意点,尽快送达"
                            ],
                            "sellerMemo": [
                                "卖家：请及时签收"
                            ]
                        },
                        "templateURL": "https://cloudprint.xiaohongshu.com/template/standard/7/2"
                    }
                ]
            }
        ]
    }
}

字段说明：

字段名	类型	说明	是否必须
taskID	string	打印机任务ID，每个打印任务会分配不同的且唯一的ID	是
preview	bool	是否预览.true为预览,false为打印	是
printer	string	打印机名，如果为空，会使用默认打印机	否
templateURL	string	模板文件url 支持http和https网络文件支持本地文件，需要加上file://前缀，如果在windows下还要对/加上转义，例如file://E:/template.json	是
documents	array	文档数组，每个数据表示一页	是
documentID	string	文档的唯一ID，对于小红书标准面单来讲，就是面单号;如果是自定义模板，需要保证唯一	是
firstDocumentNumber	int	task 起始 document 序号	否
totalDocumentCount	int	task document 总数	否
forceNoPaging	bool	task下的任务是否强制不分页	否
data	Json Object	模板需要的打印数据	否
encryptedData	string	模板需要的打印密文数据	否

响应协议格式如下:

开启 preview的情况：
 {"cmd":"print","status":"success","previewURL":"/var/folders/f4/ldmpclhs71n9bsnzyqtmsp740000gn/T/25950796_1726837889660.pdf"}
 
不开启preview的情况：【成功 下发打印任务】
 {"cmd":"print","requestID":"123456789","taskID":"1","status":"success","previewURL":"","msg":""}
 
失败情况：【失败 没有传递打印机名称】
 {"cmd":"print","requestID":"123456789","taskID":"1","status":"failed","previewURL":"","msg":"请选择打印机"}

字段名	类型	说明
taskID	string	打印机任务ID，每个打印任务会分配不同的且唯一的ID
status	string	如果是打印，表示打印任务提交成功，如果是预览，表示预览PDF文件生成成功
previewURL	string	可预览的PDF文件URL路径
previewImage	string[]	预览image的URL路径，是一个字符串数组

注:
* 如果是打印命令，只是表示将打印任务提交到打印队列，会快速返回。
* 如果是预览命令，需要将预览文件生成，才会返回，需要一段等待时间。

3.打印通知(notifyPrintResult)

打印任务完成后，由打印组件主动推送消息，响应协议格式如下:

{
  "cmd":"notifyPrintResult",
  "printer":"PDFwriter",
  "taskID":"1",
  "taskStatus":"printed",
  "allDocumentsFinished": true,
  "printStatus":[
    {
      "documentID":"9890000112011",
      "status":"success",
      "msg":"if failed,some tips, if success ,nothing",
      "detail":"错误信息的补充描述"
    }
  ]
}

字段名	类型	说明
requestID	string	请求ID
documentID	string	文档的唯一ID
taskID	string	打印机任务ID，每个打印任务会分配不同的且唯一的ID
taskStatus	string	任务打印状态printed：打印成功failed：打印失败
allDocumentsFinished	bool	true：task下所有文档已完成，最后一个document完成后会标记为true false：还有部分文档未完成
status	string	任务状态:success成功;failed 失败,canceled 取消
msg	string	如果任务状态为成功或挂起为空，如果任务状态为失败，则为失败原因概要。
detail	string	错误信息的补充描述
printer	string	负责打印的打印机名

4.获取客户端版本信息(getAgentInfo)

请求协议格式如下:

{
    "cmd":"getAgentInfo",
    "requestID":"12345678901",
    "version":"1.0"
}

响应协议格式如下:

{
    "cmd":"getAgentInfo",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "version":"0.0.1" 
}

字段解释:

字段名	类型	说明
status	string	表示命令成功或失败，取值“success”或者“failed”
msg	string	如果出错，错误原因
version	string	版本号

四、注意事项

Websocket 建议使用长连接，不要每次发送交互请求去创建一个对象。

在同打印组件交互过程中的json报文，如果文本中包含了特殊字符，比如常见的回车，引号等，需要对特殊字符做转义，详细请参考: http://www.json.org/json-zh.html 。

五、addData更换发件人地址

参考代码：

{
  "cmd":"print",
  "task":{
    "printer":"PDFwriter",
    "documents":[
      {
        "documentID":"10000001",
        "contents":[
          {   "encryptedData":"AES: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",
            "templateURL":"https://cloudprint.xiaohongshu.com/template/standard/15/1",
            "ver":"waybill_print_xiaohongshu_secret",
            "addData":{
              "sender":{
                "address":{
                  "province":"北京",
                  "city":"北京市",
                  "district":"海淀区",
                  "town":"小镇",
                  "detail":"测试地址"
                },
                "name":"小红书",
                "mobile":"181****0000",
                "phone":""
              }
            }
          }
        ]
      }
    ]
  }
}

六、使用示例

1 JavaScript使用示例

2 JAVA使用示例

java使用websocket需要引入第三方库下载地址。

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.3.0</version>
</dependency>

自己创建一个websocket管理类，需要继承自第三方类库的WebSocketClient:

import java.net.URI;
import java.net.URISyntaxException;
 
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.drafts.Draft;
import org.java_websocket.drafts.Draft_17;
import org.java_websocket.handshake.ServerHandshake;
 
public class WebSocketClientManager extends WebSocketClient {
 
    static WebSocketClientManager webSocket = null;
 
    public static void main(String[] args) throws URISyntaxException {
        String uri = "ws://127.0.0.1:10818";
        webSocket = new WebSocketClientManager(new URI(uri), new Draft_17());
        //建立连接
        webSocket.connect();
 
    }
 
    public WebSocketClientManager(URI serverUri, Draft draft) {
        super(serverUri, draft);
    }
 
    @Override
    public void onOpen(ServerHandshake serverHandshake) {
        //获取打印机列表
        String getPrinterListCmd = "{\"requestID\":\"12345678901234567890\",\"verson\":\"1.0\",\"cmd\":\"getPrinters\"}";
        webSocket.send(getPrinterListCmd);
 
        //发送打印任务
        String printCmd = "打印任务报文，内容过长此处不粘贴";
        webSocket.send(printCmd);
    }
 
    //WebSocket回调函数
    @Override
    public void onMessage(String message) {
        //TODO 对打印服务返回的数据进行处理
        System.out.println(message);
    }
 
    @Override
    public void onClose(int i, String s, boolean b) {
 
    }
 
    @Override
    public void onError(Exception e) {
 
    }
}

电子面单打印组件协议（新）

一、简介#

二、协议格式说明#

三、协议详解#

1. 获取打印机列表(getPrinters)#

2. 发送打印/预览数据协议(print)#

3.打印通知(notifyPrintResult)#

4.获取客户端版本信息(getAgentInfo)#

四、注意事项#

五、addData更换发件人地址#

六、使用示例#

1 JavaScript使用示例#

2 JAVA使用示例#

一、简介

二、协议格式说明

三、协议详解

1. 获取打印机列表(getPrinters)

2. 发送打印/预览数据协议(print)

3.打印通知(notifyPrintResult)

4.获取客户端版本信息(getAgentInfo)

四、注意事项

五、addData更换发件人地址

六、使用示例

1 JavaScript使用示例

2 JAVA使用示例