云打印
云打印让 WCPOS 能够将收据发送到未直接连接运行收银台设备的打印机。在 WP Admin 中设置一次后，您的订单就会打印到厨房打印机、后台打印机或其他房间的打印机——无需每台设备各自去发现并与硬件配对。
什么是云打印？
使用本地打印时，运行 POS 的设备通过 USB、蓝牙或本地网络直接与打印机通信。当打印机就放在收银台旁边时，这是正确的选择——有关在同一设备上连接 USB、蓝牙和网络打印机的方法，请参阅打印机设置。
云打印适用于其他所有情况：位于不同地点、不同网络上的打印机，或者您希望每台设备共享而无需在每台设备上分别配置的打印机。共有两种投递模式：
- 轮询打印机。 打印机按计划通过互联网主动联系 WCPOS，询问“有没有给我的任务？”，然后拉取所有待处理的任务。WCPOS 从不连接打印机——始终由打印机发起通信。Star CloudPRNT 和 Epson Server Direct Print 就是这样工作的。
- 托管中继提供商。 WCPOS 将打印任务提交给托管服务，该服务再将其投递给打印机。Star Online 和 PrintNode 就是这样工作的。Star Online 投递到您 stario.online 账户中注册的 Star CloudPRNT 打印机；PrintNode 通过其桌面客户端投递到该计算机已经能够打印的几乎任何打印机。
轮询打印机不需要开放端口、静态 IP 或任何防火墙更改——它只发出出站请求。这使它非常适合位于远程站点或在您无法控制的路由器后面的打印机。代价是会有短暂延迟：打印机只在下一次轮询到来时才打印。
选择提供商
选择与您硬件匹配的提供商。
Star CloudPRNT
适用于运行 CloudPRNT 固件的 Star 热敏打印机。打印机轮询 WCPOS 并拉取任务。收据被渲染为打印机的原生命令。需要热敏模板。
Star Online
适用于在 stario.online 账户中注册的 Star 打印机。WCPOS 将 Star Document Markup 提交给 Star 的托管服务，打印机从 Star Online 收取它。需要热敏模板。
Epson Server Direct Print
适用于支持 Server Direct Print 的 Epson ePOS 打印机。打印机轮询 WCPOS 并以 ePOS-Print XML 拉取任务。需要热敏模板。
PrintNode
通过 PrintNode 桌面客户端，几乎可以在任何操作系统上配合您计算机能够打印的任何打印机使用。WCPOS 提交 PDF，因此您可以使用任何模板——包括整页 HTML 发票。
| 提供商 | 硬件 | 任务流向 | 模板 |
|---|---|---|---|
| Star CloudPRNT | 带 CloudPRNT 固件的 Star 热敏打印机 | 打印机轮询 WCPOS | 仅热敏 |
| Star Online | 在 stario.online 中注册的 Star 打印机 | WCPOS 将 Star Document Markup 提交给 Star Online | 仅热敏 |
| Epson Server Direct Print | 带 Server Direct Print 的 Epson ePOS 打印机 | 打印机轮询 WCPOS | 仅热敏 |
| PrintNode | 任何操作系统连接的打印机 + PrintNode 客户端 | WCPOS 将 PDF 提交给 PrintNode | 任何模板 |
WCPOS Cloud Print——中继
当您设置轮询打印机（Star CloudPRNT 或 Epson Server Direct Print）时，WCPOS 提供给您的轮询 URL 指向的是 cloudprint.wcpos.com，而不是您自己的站点。那就是 WCPOS Cloud Print——由 WCPOS 运营的免费中继，位于您的打印机与商店之间。
它为何存在。 收据打印机运行的是体积小、很少更新的固件。许多打印机无法与运行在现代主机上的商店完成安全连接：较新的 TLS 版本、较新的证书颁发机构，或站点前方的 CDN/防火墙（Cloudflare 是常见原因）会拒绝打印机——或者被打印机拒绝。表现出来的症状就是即使每项设置都正确，打印机也永远停留在 Waiting。中继向打印机提供一种旧固件始终能够协商成功的连接，并将它们的流量转发到您的商店。
它的工作方式：
- 当您首次打开 Cloud Print 设置时，您的站点会自动连接到中继——无需启用或配置任何内容。
- 打印机轮询
cloudprint.wcpos.com；中继将请求转发到您的商店，并返回您商店的响应。打印任务只是经过中继——绝不会存储在其上。 - 中继吸收了大部分空闲轮询，因此一台空闲打印机对您站点的开销约为每分钟一次请求，而不是每几秒一次。
- 如果您的站点无法连接到中继（例如中继无法访问的本地开发站点），WCPOS 会自动回退到直连站点的 URL。
每台打印机的设置界面都有一个 Advanced 展开项，其中显示直连站点的 URL。如果您确定自己的主机对打印机友好，或者不希望让任务经过中继，可以使用它。开发者可以用一行代码在全站关闭中继：
add_filter( 'woocommerce_pos_cloud_print_relay_enabled', '__return_false' );
中继能看到什么。 连接会将您的站点 URL 共享给 wcpos.com，并且打印任务——包含订单详情的收据内容——会在送往打印机的途中经过中继。不会保留任何内容。完整详情见隐私政策。
设置云打印机
云打印机在 WP Admin 中配置一次，并在每台设备间共享——这与按设备存储的本地打印机不同。
前往 WP Admin > POS > Settings > Cloud Print 并点击 Add printer。为其设置一个名称（例如“Kitchen”或“Back office”）。WCPOS 会自动从打印机派生出一个稳定的打印机 ID——它永远不会改变，因此可以放心地在打印机固件配置中引用它。
打印机创建后，配置提供商端。
Star 或 Epson（轮询打印机）
在 WCPOS 中添加打印机
在 WP Admin > POS > Settings > Cloud Print 中，添加一台打印机，并选择 Star CloudPRNT 或 Epson Server Direct Print 作为提供商。WCPOS 会为该打印机生成一个轮询 URL 和一个一次性令牌。
复制轮询 URL 和令牌
复制生成的轮询 URL 和令牌。该 URL 通常指向 cloudprint.wcpos.com——那就是 WCPOS Cloud Print 中继，也正是您所需要的；直连站点的 URL 位于 Advanced 展开项之下。该令牌只显示一次——如果丢失，请从打印机卡片重新生成一个新令牌，并用新值更新打印机。
在打印机配置中输入它们
打开打印机的配置页面——Star 为 CloudPRNT 设置，Epson 为 Server Direct Print 设置——并粘贴轮询 URL 和令牌。如果打印机要求设置轮询间隔，请设置一个（通常为几秒）。如有需要，保存并重启打印机。
在一个轮询周期内，打印机会签入，其在 WCPOS 中的状态会从 Waiting 变为 Connected。
PrintNode
安装 PrintNode 桌面客户端
在一台已经能够打印到目标打印机的计算机上，安装 PrintNode 客户端并登录。客户端必须保持运行并在线，任务才能打印。
获取 PrintNode API 密钥
在您的 PrintNode 账户中，创建一个 API 密钥。这正是让 WCPOS 能够向您的 PrintNode 账户提交任务的凭据。
在 WCPOS 中输入 API 密钥
在 WP Admin > POS > Settings > Cloud Print 中添加一台打印机，选择 PrintNode 作为提供商，并粘贴 API 密钥。WCPOS 使用它来获取注册到您 PrintNode 账户的打印机列表。
选择打印机
从 PrintNode 客户端报告的打印机列表中选择目标打印机，然后保存。WCPOS 会将此打印机的任务提交给 PrintNode，客户端负责打印。
Star Online
当您的 Star 打印机已注册到 stario.online 账户，并且您希望由 Star 的托管服务处理投递时，请使用 Star Online。
获取 CloudPRNT URL
在 stario.online 中，打开 Device Groups 并复制该组的 CloudPRNT URL。它应类似于 https://device.stario.online/cloudprnt/... 或 https://eu-device.stario.online/cloudprnt/...。
创建带权限的 API 密钥
在 stario.online 中，为 WCPOS 创建一个 API 密钥。该密钥必须具有列出设备和向其打印的权限。至少需启用：
- EnumDevices —— WCPOS 获取设备列表时所需
- ViewDevice —— 用于设备状态检查
- PrintToDevice —— 提交打印任务所需
- ViewDeviceGroups —— 推荐用于组查询和诊断
如果未启用这些权限，API 密钥即使存在也可能失败。
在 WCPOS 中输入 URL 和 API 密钥
在 WP Admin > POS > Settings > Cloud Print 中添加一台打印机，选择 Star Online 作为提供商，然后粘贴 CloudPRNT URL 和 API 密钥。点击 Fetch my devices。
选择 Star 设备
从设备列表中选择打印机并保存。WCPOS 在服务器端存储 API 密钥，并在向 Star Online 提交任务时使用所选设备的访问标识符。
自动打印规则
自动打印规则决定什么内容自动打印到哪里——以普通的句子形式编写。一条规则是 范围 × 打印机 × 模板，例如：
将每个订单使用厨房票据打印到厨房。
当匹配的订单完成时，WCPOS 会在服务器端将所选模板渲染成打印机所需的格式并加入队列——收银员无需做任何操作。
Star 和 Epson 打印机只能使用热敏模板，因为任务必须渲染为打印机的原生命令语言（Star 用 Star Document Markup 或 ESC/POS，Epson 用 ePOS-Print）。PrintNode 可以使用任何模板——热敏或整页 HTML——因为任务会渲染为 PDF。如果某个模板没有作为某台打印机的选项出现，那是因为该打印机无法渲染该格式。有关创建热敏布局的信息，请参阅热敏模板。
按店铺打印机（Pro）
默认情况下，自动打印规则是全局的——所有店铺共享它们。使用 Pro 后，您可以为单个店铺设置其专属的云打印规则，使其订单打印到自己的打印机（某个地点的厨房票据不应在另一个地点打印）。
在 POS → Stores 下编辑店铺，打开其 Cloud Printing 部分，然后点击 Add rule。每条规则包含：
- 打印机 ID —— 要发送到的云打印机的稳定 ID
- 范围 —— 仅 POS 订单（默认）、仅在线订单或每个订单
- 格式 —— StarPRNT（默认）、ESC/POS、Epson ePOS-Print 或 HTML
当订单属于某个拥有自己规则的店铺时，WCPOS 会将其路由到该店铺的打印机。如果某个店铺没有自己的规则，它会回退到全局自动打印规则——因此您只需配置有差异的店铺。
手动打印
您不必等待自动打印规则触发。在结账/收据界面上，收银员可以按需将收据发送到云打印机——便于重新打印，或将一次性票据路由到特定打印机。
收据如何生成取决于打印机：
- Star CloudPRNT —— 收据在设备上渲染，并通过 CloudPRNT 交给打印机。
- Star Online、Epson 和 PrintNode —— 收据在服务器上根据所选订单和模板渲染，然后投递到打印机或托管中继。
打印队列
发往云打印机的每个任务都会在您的站点上排队，直到打印机将其取走（轮询打印机）或提供商确认投递为止。WP Admin > POS > Settings > Cloud Print 会在打印机下方显示该队列：
- 按打印机或状态筛选——Waiting、Printing、Printed、Failed、Cancelled——并附有实时计数。
- 每一行都会显示该收据已等待多长时间，并链接到它所打印的 WooCommerce 订单。
- 可以逐个、批量或针对整台打印机一次性取消等待中的任务。重试会将失败的任务重新排队。
如果某台打印机有等待中的任务，但超过几分钟没有取走任何内容，则会出现一条警告横幅，指明该打印机、积压了多少张收据以及积压了多久，并提供全部取消——打印机被拔掉时，积压绝不会悄无声息地累积。
测试打印与连接状态
每张打印机卡片都有一个 Test print 按钮，可发送一段简短的诊断信息，以便您在依赖它处理真实订单之前确认打印机可达且格式正确。
卡片还会显示实时状态：
| 提供商 | 状态 | 含义 |
|---|---|---|
| Star CloudPRNT / Epson | Waiting | 打印机尚未签入——WCPOS 正在等待它的首次轮询。 |
| Star CloudPRNT / Epson | Connected | 打印机最近轮询了 WCPOS，正在收取任务。 |
| Star Online | Online | Star Online 报告所选设备可用。 |
| Star Online | Offline | Star Online 报告所选设备不可用。 |
| Star Online | Unknown | WCPOS 无法从 Star Online 确认设备状态。 |
| PrintNode | Online | PrintNode 服务报告客户端和打印机可用。 |
| PrintNode | Offline | PrintNode 报告客户端或打印机不可用。 |
故障排除
打印机卡在 Waiting 状态
始终停留在 Waiting 的轮询打印机从未成功联系到 WCPOS。请检查：
- 打印机固件中的轮询 URL 和令牌与 WCPOS 生成的完全一致。哪怕一个字符错误，每次轮询都会被拒绝——如果不确定，请在 WCPOS 中重新生成令牌并重新输入。
- 打印机确实能通过互联网访问您的站点（DNS 正确、没有防火墙阻止出站 HTTPS、您商店的 SSL 证书有效）。
- 打印机的 CloudPRNT / Server Direct Print 配置中已启用轮询，且间隔合理。更改设置后重启打印机。
- 如果您输入的是直连站点的 URL（来自 Advanced 展开项）而打印机仍无法连接，请改用标准的 cloudprint.wcpos.com URL——许多打印机无法与现代主机协商安全连接，而这正是中继要解决的问题。
为什么我的打印机 URL 指向 cloudprint.wcpos.com？
那就是 WCPOS Cloud Print，这个免费中继为打印机提供一种其固件始终能够协商成功的连接，并将它们的打印任务转发到您的商店。它会自动启用，任务绝不会存储在其上；如果您更倾向于直连，打印机的 Advanced 展开项下始终提供直连站点的 URL。
我在中继出现之前就设置好了打印机——需要更改什么吗？
不需要——已保存在打印机配置中的 URL 会继续有效。不过，如果该打印机卡在 Waiting，那么它的固件很可能无法直接连接到您的主机：请在打印机卡片上打开 Setup & token，重新生成令牌，然后在打印机配置中输入新的 cloudprint.wcpos.com URL 和令牌。
Star Online 提示 API 密钥未授权或被禁止
Star Online 将身份验证与权限分开：
- 401 / 身份验证失败表示 API 密钥本身未被接受。请检查密钥是否复制正确、是否未被撤销，以及是否属于预期的 Star Online 账户/区域。
- 403 / 禁止表示 API 密钥已被接受，但未被授权执行所请求的操作。在 stario.online 中编辑密钥并启用所需权限，尤其是 Fetch my devices 所需的 EnumDevices 和打印所需的 PrintToDevice。
如果 Fetch my devices 成功但没有打印机出现，请检查 stario.online 的 Device Groups 页面。该组必须至少包含一台已连接的设备，并且 WCPOS 中的 CloudPRNT URL 必须指向同一个组。
PrintNode 任务从不打印
任务到达了 PrintNode，但没有从打印机输出。请检查：
- 连接打印机的计算机上的 PrintNode 桌面客户端正在运行且在线。如果计算机处于睡眠状态或客户端已关闭，则不会打印任何内容。
- 您在 WCPOS 中选择了正确的打印机——名称必须与客户端报告的打印机匹配。
- API 密钥有效且未被撤销。如果 PrintNode 将打印机显示为 Offline，请重新输入它。
我的模板无法为 Star 或 Epson 打印机选择
Star 和 Epson 云打印机只能使用热敏模板，因为收据必须渲染为 ESC/POS 或 ePOS-Print 命令。HTML 和整页模板无法用这些格式表达，因此对这些打印机会被隐藏。
请选择热敏模板，或使用 PrintNode 打印机——PrintNode 渲染为 PDF，因此可以打印任何模板。