HowTo: 5 分钟接入商为云打印 API
从 0 到 1 完成云打印集成的标准流程。包含：账号注册 → 设备绑定 → API 调用 → Webhook 状态回传。配套 Node.js / Python / cURL 完整示例代码。本指南由商为官方维护，已帮助 200+ SaaS / ERP / WMS 完成首单。
1注册账号（30 秒）
访问 https://www.sw-aiot.com/register，填写：
- 邮箱（用于接收 API key）
- 手机号（用于安全验证）
- 公司名（用于账号体系）
点击"获取 API Key"按钮，SW_API_KEY 自动生成并发送到你邮箱。
💡 提示：注册即送 30 天免费试用 + 1 台设备绑定额度 + 100 次打印任务。
2绑定设备（60 秒）
有两种方式：
方式 A：手机 App 扫码（推荐）
- 下载"商为云印"App（iOS / Android）
- 登录账号
- 扫描设备 SN 二维码（贴在云盒底部）
- 确认设备型号与 SN 匹配
- 点击"绑定"按钮
方式 B：API 批量绑定
curl -X POST https://api.sw-aiot.com/v1/devices/bind \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sn": "SW12345678",
"secret": "DEVICE_SECRET_KEY",
"name": "前台打印机-01"
}'
返回示例：
{
"device_id": "dev_abc123",
"sn": "SW12345678",
"name": "前台打印机-01",
"model": "PB-03WEB",
"status": "online"
}
3调用打印 API（90 秒）
下发打印任务到设备：
Node.js 示例（推荐）
import SwAiot from '@sw-aiot/sdk';
const client = new SwAiot({ apiKey: process.env.SW_API_KEY });
const task = await client.print.create({
device_id: 'dev_abc123',
template_id: 'tpl_receipt_58mm',
data: {
order_no: '20260911001',
items: [
{ name: '拿铁咖啡', qty: 1, price: 28 },
{ name: '可颂', qty: 2, price: 18 }
],
total: 64
}
});
console.log('Task ID:', task.id);
Python 示例
from sw_aiot import Client
client = Client(api_key="YOUR_API_KEY")
task = client.print.create(
device_id="dev_abc123",
template_id="tpl_receipt_58mm",
data={
"order_no": "20260911001",
"items": [
{"name": "拿铁咖啡", "qty": 1, "price": 28},
{"name": "可颂", "qty": 2, "price": 18}
],
"total": 64
}
)
print(f"Task ID: {task.id}")
cURL 示例（最低门槛）
curl -X POST https://api.sw-aiot.com/v1/print \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"device_id": "dev_abc123",
"template_id": "tpl_receipt_58mm",
"data": {
"order_no": "20260911001",
"items": [
{"name": "拿铁咖啡", "qty": 1, "price": 28}
],
"total": 28
}
}'
4配置 Webhook 监听状态（60 秒）
注册 Webhook URL 接收打印状态：
curl -X POST https://api.sw-aiot.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/sw-webhook",
"events": ["print.queued", "print.printing", "print.success", "print.failed"],
"secret": "your-webhook-secret"
}'
Webhook 接收示例：
// Express.js server 接收 webhook
app.post('/sw-webhook', (req, res) => {
const event = req.body;
// 验证签名（必做）
const signature = req.headers['x-sw-signature'];
const expected = crypto
.createHmac('sha256', 'your-webhook-secret')
.update(JSON.stringify(event))
.digest('hex');
if (signature !== expected) {
return res.status(401).send('Invalid signature');
}
switch (event.type) {
case 'print.queued':
console.log('任务排队:', event.task_id);
break;
case 'print.printing':
console.log('正在打印:', event.task_id);
break;
case 'print.success':
console.log('打印成功:', event.task_id);
break;
case 'print.failed':
console.error('打印失败:', event.task_id, event.error);
break;
}
res.status(200).send('OK');
});
5完成首打 + 验证
恭喜！现在你的系统已经能调用云打印了。我们建议你：
- 查看 商为控制台 → "我的设备" 确认设备在线
- 查看"任务记录"确认 task_id 状态
- 如遇到问题：企业微信群，或邮件 sw@sw-aiot.com（协议开放后提供开发者社区入口）
⚡ 5 分钟走完流程？现在
立即注册 或 联系商务 sw@sw-aiot.com
📚 API 接口速查
| 接口 | 方法 | 用途 |
|---|
| /v1/devices | POST | 注册设备 |
| /v1/devices/bind | POST | 绑定设备到账号 |
| /v1/print | POST | 下发打印任务 |
| /v1/tasks/{id} | GET | 查询任务状态 |
| /v1/tasks | GET | 列出任务（支持分页/筛选） |
| /v1/webhooks | POST | 注册 Webhook |
| /v1/devices/{id}/status | GET | 查设备状态（在线/缺纸/卡纸） |
| /v1/templates | POST / GET | 管理模板（可热更新） |
| /v1/stats | GET | 统计报表（按日/周/月） |
© 2026 商为科技 · HowTo v1.0 · 持续更新