把云打印接入你的业务系统

打印任务

用企业模板编码（template_code）和打印机编码（printer_code）提交打印任务，并查询、重试或取消。上传模式、状态流转和计费规则见「打印任务对接指南」。

• •POST /print-jobs 暂不幂等：idempotency_key 还没有实现，传了会返回 400。请求超时或返回 500 时不要直接重新提交，先查询确认任务是否已经创建，否则可能重复打印。
• •job_no 是平台生成的任务编号，不是你的业务单号。它在提交响应里返回，可以用 by-job-no 查询。请求体里没有业务单号字段，多传的字段会被忽略。
• •status 是字符串。partial（部分完成）表示有行打印失败，不能当作 completed 处理。
• •打印任务接口中没有值的字段会被省略，不会返回 null。

• GET/print-jobsprint_job:read

  分页查询打印任务列表

  参数与响应

  参数

  名称	位置	类型	说明
  status	Query	string	按状态筛选：pending / dispatching / queued / printing / completed / partial / failed / cancelled / retrying。也兼容数字状态值，其他值返回 400
  source	Query	string	按来源筛选：api / web / batch
  job_no	Query	string	按任务编号筛选
  virtual_printer_id	Query	string	按打印机 ID 筛选，必须是正整数
  template_id	Query	string	按内部模板 ID 筛选，必须是正整数
  terminal_id	Query	string	按终端 ID 筛选，必须是正整数
  page	Query	integer	页码，从 1 开始，默认 1
  page_size	Query	integer	每页条数，默认 20，最大 100

  响应 · 分页列表<PrintJob>

  {
    "items": [
      {
        "id": "1938475610293890001",
        "job_no": "<job-no>",
        "status": "completed",
        "source": "api",
        "template_id": "1938475610293800001",
        "template_version_id": "1938475610293810001",
        "template_release_id": "1938475610293850112",
        "virtual_printer_id": "1938475610293860001",
        "terminal_id": "1938475610293870001",
        "upload_mode": "inline",
        "data_sealed": true,
        "data_purged": false,
        "rows_total": 2,
        "rows_printed": 2,
        "rows_failed": 0,
        "total_pages": 3,
        "pages_printed": 3,
        "retry_count": 0,
        "max_retry": 3,
        "retryable": false,
        "created_at": "2025-01-01T10:00:00+08:00",
        "queued_at": "2025-01-01T10:00:01+08:00",
        "printed_at": "2025-01-01T10:00:05+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }

  错误

  • 400 invalid_request — status 不是已知状态，或 ID 类参数不是正整数
• GET/print-jobs/by-job-no/:job_noprint_job:read

  按任务编号查询任务

  job_no 来自提交响应。适合在业务系统里保存 job_no 后对账。

  参数与响应

  参数

  名称	位置	类型	说明
  job_no*	路径	string	平台生成的任务编号

  响应 · PrintJob

  {
    "id": "1938475610293890001",
    "job_no": "<job-no>",
    "status": "completed",
    "source": "api",
    "template_id": "1938475610293800001",
    "template_version_id": "1938475610293810001",
    "template_release_id": "1938475610293850112",
    "virtual_printer_id": "1938475610293860001",
    "terminal_id": "1938475610293870001",
    "upload_mode": "inline",
    "data_sealed": true,
    "data_purged": false,
    "rows_total": 2,
    "rows_printed": 2,
    "rows_failed": 0,
    "total_pages": 3,
    "pages_printed": 3,
    "retry_count": 0,
    "max_retry": 3,
    "retryable": false,
    "created_at": "2025-01-01T10:00:00+08:00",
    "queued_at": "2025-01-01T10:00:01+08:00",
    "printed_at": "2025-01-01T10:00:05+08:00"
  }

  错误

  • 404 not_found — 任务不存在
• GET/print-jobs/:idprint_job:read

  查询任务详情

  轮询任务状态用这个接口。GET 不计月度配额，但受 QPM 限速，建议轮询间隔不低于数秒。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  响应 · PrintJob

  {
    "id": "1938475610293890001",
    "job_no": "<job-no>",
    "status": "completed",
    "source": "api",
    "template_id": "1938475610293800001",
    "template_version_id": "1938475610293810001",
    "template_release_id": "1938475610293850112",
    "virtual_printer_id": "1938475610293860001",
    "terminal_id": "1938475610293870001",
    "upload_mode": "inline",
    "data_sealed": true,
    "data_purged": false,
    "rows_total": 2,
    "rows_printed": 2,
    "rows_failed": 0,
    "total_pages": 3,
    "pages_printed": 3,
    "retry_count": 0,
    "max_retry": 3,
    "retryable": false,
    "created_at": "2025-01-01T10:00:00+08:00",
    "queued_at": "2025-01-01T10:00:01+08:00",
    "printed_at": "2025-01-01T10:00:05+08:00"
  }

  错误

  • 400 invalid_parameter — id 不是正整数
  • 404 not_found — 任务不存在
• POST/print-jobsprint_job:create计配额

  提交打印任务

  upload_mode 必填。inline 示例见下；none 和 streaming 的请求体见「打印任务对接指南」。成功返回 201。

  参数与响应

  请求体 · SubmitRequest

  {
    "template_code": "S-7K2M9Q",
    "printer_code": "<printer-code>",
    "upload_mode": "inline",
    "params": {
      "copies": 1
    },
    "rows": [
      {
        "data": {
          "sku": "A001",
          "barcode": "690123456789012345"
        }
      },
      {
        "data": {
          "sku": "A002",
          "barcode": "690123456789012346"
        },
        "copies": 2
      }
    ]
  }

  响应 · 201 · PrintJob

  {
    "id": "1938475610293890001",
    "job_no": "<job-no>",
    "status": "pending",
    "source": "api",
    "template_id": "1938475610293800001",
    "template_version_id": "1938475610293810001",
    "template_release_id": "1938475610293850112",
    "virtual_printer_id": "1938475610293860001",
    "terminal_id": "1938475610293870001",
    "upload_mode": "inline",
    "data_sealed": true,
    "data_purged": false,
    "rows_total": 2,
    "rows_printed": 0,
    "rows_failed": 0,
    "total_pages": 3,
    "pages_printed": 0,
    "retry_count": 0,
    "max_retry": 3,
    "retryable": false,
    "created_at": "2025-01-01T10:00:00+08:00"
  }

  错误

  • 400 invalid_request — 缺少 template_code / printer_code，或 template_release_id 不合法
  • 400 idempotency_not_supported — 传了 idempotency_key（暂未实现）
  • 400 upload_mode_required — 没有传 upload_mode
  • 400 invalid_upload_mode — upload_mode 取值非法，或与 rows / rows_expected 的组合不匹配
  • 400 rows_expected_invalid — streaming 模式下 rows_expected 不在 1 ~ 2,000,000 之间
  • 400 rows_expected_mismatch — inline 模式下 rows_expected 与 rows 的长度不一致
  • 400 inline_rows_too_many — inline 行数超过 200，请改用 streaming
  • 413 inline_payload_too_large — inline 数据超过 512 KiB，请改用 streaming
  • 400 row_no_mixed — row_no 有的给了有的没给
  • 400 row_no_out_of_range — row_no 为负，或不在 1..N 范围内
  • 400 row_no_duplicated — row_no 重复
  • 400 copies_invalid — 份数为负
  • 400 copies_too_many — 份数超过 1,000
  • 400 total_pages_invalid — total_pages 不在 0 ~ 100,000 之间
  • 400 template_not_found — template_code 不存在、未上架，或当前凭证没有授权（不区分）
  • 400 template_release_not_found — template_release_id 不属于这个 template_code
  • 409 template_content_missing — 模板内容缺失，需要模板作者重新保存并发布
  • 409 template_content_corrupted — 模板内容指纹不一致，请联系模板分组管理员
  • 400 printer_not_found — printer_code 不存在
  • 400 printer_disabled — 打印机已禁用
  • 400 printer_not_bound — 打印机没有绑定终端
  • 400 terminal_unavailable — 终端没有激活或已被吊销
  • 400 source_file_not_found — source_file_id 不存在或无权使用
  • 400 source_file_not_ready — 文件还没有确认上传，请先调用 /storage/uploads/:id/confirm
  • 400 source_file_category_mismatch — 文件分类不是 print_data
  • 409 source_file_in_use — 文件已经绑定到其他任务（一个文件只能绑定一个任务）
  • 502 data_write_failed — 任务已创建，但数据行写入失败；任务已被标记失败并清理，直接重新提交即可。message 里带 job_no
• POST/print-jobs/:id/retryprint_job:create计配额

  重试失败或部分完成的任务

  只有 retryable=true 时才能重试。partial 任务只补打失败行，不会重打已经成功的行。重试复用提交时的模板快照，不会使用模板之后发布的新版本。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  响应 · { id, status }

  {
    "id": "1938475610293890001",
    "status": "pending"
  }

  错误

  • 404 not_found — 任务不存在
  • 409 not_retryable — 任务不是 failed / partial，或已达到 max_retry
  • 410 data_purged — 行数据已过保留期被清理，不能重打
• POST/print-jobs/:id/cancelprint_job:cancel计配额

  取消任务

  pending 和 queued 状态可以取消。queued 表示任务已经进入设备队列，取消时可能已经打出了部分标签，这部分照常计费。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  响应 · { id, status }

  {
    "id": "1938475610293890001",
    "status": "cancelled"
  }

  错误

  • 404 not_found — 任务不存在
  • 409 not_cancellable — 任务当前状态不允许取消（只能取消 pending / queued）

流式上传

只用于 upload_mode=streaming 的任务。提交后分批追加数据行，全部传完后封口，任务才会开始下发。单个任务最多 2,000,000 行。

• •row_no 是整个任务内的全局行号（1..rows_expected），不是每批都从 1 开始。每批从 1 开始的话，第二批会全部被当作重复行丢弃。
• •重传是安全的：已经写入的 row_no 会计入 duplicated，不会被覆盖。这也意味着已经写入的行不能再通过重传修改。
• •批次可以乱序上传，但封口时 1..rows_expected 必须完整、没有缺口。
• •/rows 不计月度配额，但和其他接口一起受凭证级 QPM 限速。按默认 60 次/分钟、每批 1,000 行计算，传满 2,000,000 行至少需要约 34 分钟。

• POST/print-jobs/:id/rowsprint_job:create不计配额

  追加数据行

  只对未封口的 streaming 任务有效。不计月度配额，但受 QPM 限速。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  请求体 · AppendRowsRequest

  {
    "rows": [
      {
        "row_no": 1001,
        "data": {
          "sku": "A001001"
        }
      },
      {
        "row_no": 1002,
        "data": {
          "sku": "A001002"
        },
        "copies": 2
      }
    ]
  }

  响应 · AppendResult

  {
    "inserted": 2,
    "duplicated": 0,
    "next_row_no": 1003,
    "rows_uploaded": 1002
  }

  错误

  • 400 invalid_request — rows 为空
  • 400 append_rows_too_many — 单批超过 1,000 行
  • 400 row_no_required — 有行没有给 row_no，或 row_no ≤ 0
  • 400 row_no_duplicated — 同一批内 row_no 重复
  • 400 row_no_out_of_range — row_no 不在 [1, rows_expected] 范围内
  • 400 copies_invalid — 份数为负
  • 400 copies_too_many — 份数超过 1,000
  • 409 rows_exceed_expected — 累计行数会超过提交时声明的 rows_expected
  • 409 job_not_streaming — 任务不是 streaming 模式
  • 409 no_data_expected — 任务以 upload_mode=none 提交，不接受数据行
  • 409 job_not_appendable — 任务已取消、已失败或已封口，不再接受数据
  • 409 job_already_sealed — 任务已封口
• POST/print-jobs/:id/sealprint_job:create计配额

  封口任务，开始下发打印

  服务端校验实际行数等于 rows_expected，且 row_no 连续没有缺口，通过后立即尝试下发。对已封口的任务重复调用返回 200。响应是任务的最新状态。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  请求体（可省略） · SealRequest（可选）

  {
    "checksum": "<optional-checksum>"
  }

  响应 · PrintJob

  {
    "id": "1938475610293890001",
    "job_no": "<job-no>",
    "status": "pending",
    "source": "api",
    "template_id": "1938475610293800001",
    "template_version_id": "1938475610293810001",
    "template_release_id": "1938475610293850112",
    "virtual_printer_id": "1938475610293860001",
    "terminal_id": "1938475610293870001",
    "upload_mode": "streaming",
    "data_sealed": true,
    "data_purged": false,
    "rows_total": 2000000,
    "rows_printed": 0,
    "rows_failed": 0,
    "total_pages": 2000000,
    "pages_printed": 0,
    "retry_count": 0,
    "max_retry": 3,
    "retryable": false,
    "created_at": "2025-01-01T10:00:00+08:00"
  }

  错误

  • 409 rows_mismatch — 已上传行数不等于 rows_expected。先查 upload-progress，补齐缺少的行后再封口
  • 409 rows_not_continuous — row_no 有缺口（如 1..99、101）
  • 409 job_not_streaming — 任务不是 streaming 模式
  • 404 not_found — 任务不存在
• GET/print-jobs/:id/upload-progressprint_job:read

  查询上传进度

  网络中断后，用它确认数据已经写入到哪一行，再从断点续传。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	任务 ID

  响应 · UploadProgress

  {
    "id": "1938475610293890001",
    "rows_expected": 2000000,
    "rows_uploaded": 1002,
    "max_row_no": 1002,
    "sealed": false
  }

  错误

  • 404 not_found — 任务不存在

模板

企业侧按「条目」（template share）寻址模板，可以用 share_id，也可以用槽位编码 share_code（S-XXXXXX）。所有展示字段和内容都来自已生效的发布记录。概念和推荐流程见「模板对接指南」。

• GET/templatestemplate:read

  查询当前凭证可访问的全部模板条目

  包括按分组授权和按单个条目授权的条目。同一模板发布到两个分组时，会返回两个条目，它们的版本可能不同。

  参数与响应

  参数

  名称	位置	类型	说明
  name	Query	string	按模板名称筛选
  tags	Query	string[]	按标签筛选，可以重复传：tags=a&tags=b
  status	Query	integer	已废弃只为兼容旧集成保留：不传或传 1 时正常返回，传其他值返回 400。include_inactive 会被忽略。
  page	Query	integer	页码，从 1 开始，默认 1
  page_size	Query	integer	每页条数，默认 20，最大 100

  响应 · 分页列表<TemplateItem>

  {
    "items": [
      {
        "share_id": "1938475610293847552",
        "group_id": "1938475610293840001",
        "share_code": "S-7K2M9Q",
        "release_id": "1938475610293850112",
        "version_no": 3,
        "name": "发货标签 100×150",
        "description": null,
        "width": 100,
        "height": 150,
        "size_unit": "mm",
        "source": 1,
        "released_at": "2025-01-01T10:00:00+08:00",
        "thumbnail": {
          "url": "https://<oss-domain>/<signed-path>",
          "expires_at": "2025-01-01T11:00:00+08:00"
        },
        "can_print": true
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }

  错误

  • 400 invalid_parameter — status 传了 1 以外的值
• GET/template-shares/by-code/:shareCodetemplate:read

  按槽位编码获取模板条目

  推荐：业务系统只保存 share_code。条目下架、重新上架、更新版本或回滚后，share_code 都不变。拿到 share_id 后，再用它调用发布记录和内容接口。

  参数与响应

  参数

  名称	位置	类型	说明
  shareCode*	路径	string	槽位编码，格式 S-XXXXXX，最长 16 个字符

  响应 · TemplateItem

  {
    "share_id": "1938475610293847552",
    "group_id": "1938475610293840001",
    "share_code": "S-7K2M9Q",
    "release_id": "1938475610293850112",
    "version_no": 3,
    "name": "发货标签 100×150",
    "description": null,
    "width": 100,
    "height": 150,
    "size_unit": "mm",
    "source": 1,
    "released_at": "2025-01-01T10:00:00+08:00",
    "thumbnail": {
      "url": "https://<oss-domain>/<signed-path>",
      "expires_at": "2025-01-01T11:00:00+08:00"
    },
    "can_print": true
  }

  错误

  • 400 invalid_parameter — share_code 为空或超过 16 个字符
  • 404 not_found — 条目不存在、已下架或无权查看（不区分具体原因）
• GET/template-shares/:shareIdtemplate:read

  获取模板条目详情

  参数与响应

  参数

  名称	位置	类型	说明
  shareId*	路径	string	条目 ID（share_id）

  响应 · TemplateItem

  {
    "share_id": "1938475610293847552",
    "group_id": "1938475610293840001",
    "share_code": "S-7K2M9Q",
    "release_id": "1938475610293850112",
    "version_no": 3,
    "name": "发货标签 100×150",
    "description": null,
    "width": 100,
    "height": 150,
    "size_unit": "mm",
    "source": 1,
    "released_at": "2025-01-01T10:00:00+08:00",
    "thumbnail": {
      "url": "https://<oss-domain>/<signed-path>",
      "expires_at": "2025-01-01T11:00:00+08:00"
    },
    "can_print": true
  }

  错误

  • 404 not_found — 条目不存在、已下架或无权查看
• GET/template-shares/:shareId/releasestemplate:read

  列出条目的发布记录

  企业侧只公开发布台账，不公开作者的草稿版本。用于追溯和历史补打。

  参数与响应

  参数

  名称	位置	类型	说明
  shareId*	路径	string	条目 ID（share_id）
  page	Query	integer	页码，从 1 开始，默认 1
  page_size	Query	integer	每页条数，默认 20，最大 100

  响应 · 分页列表<ReleaseItem>

  {
    "items": [
      {
        "id": "1938475610293850112",
        "version_no": 3,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "name": "发货标签 100×150",
        "width": 100,
        "height": 150,
        "size_unit": "mm",
        "source": 1,
        "released_at": "2025-01-01T10:00:00+08:00",
        "superseded_at": null,
        "is_current": true
      },
      {
        "id": "1938475610293849001",
        "version_no": 2,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "name": "发货标签 100×150",
        "width": 100,
        "height": 150,
        "size_unit": "mm",
        "source": 2,
        "released_at": "2024-12-01T09:30:00+08:00",
        "superseded_at": "2025-01-01T10:00:00+08:00",
        "is_current": false
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }

  错误

  • 404 not_found — 条目不存在或无权查看
• GET/template-shares/:shareId/contenttemplate:read

  获取模板内容

  不传 release_id 时返回当前生效的内容；传入时返回该发布记录的内容（历史补打）。

  参数与响应

  参数

  名称	位置	类型	说明
  shareId*	路径	string	条目 ID（share_id）
  release_id	Query	string	发布记录 ID，可选。必须是正整数，非法值直接返回 400，不会当作不传处理。

  响应 · ContentResponse

  {
    "version_no": 3,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "width": 100,
    "height": 150,
    "size_unit": "mm",
    "title": "发货标签 100×150",
    "content": {
      "...": "模板设计内容（JSON 对象）"
    }
  }

  错误

  • 400 invalid_parameter — release_id 不是正整数
  • 404 not_found — 条目或发布记录不存在
  • 409 share_not_listed — 条目当前没有上架
  • 409 content_hash_mismatch — 内容指纹校验失败，请求被拒绝
  • 409 template_content_missing — 模板内容缺失
• GET/template-groupstemplate:read

  列出模板分组

  参数与响应

  响应 · { groups: GroupItem[] }

  {
    "groups": [
      {
        "id": "1938475610293840001",
        "name": "物流标签",
        "description": "仓库发货使用",
        "sort_order": 0
      }
    ]
  }

• GET/template-groups/:groupId/templatestemplate:read

  列出分组下的模板条目

  参数与响应

  参数

  名称	位置	类型	说明
  groupId*	路径	string	分组 ID
  name	Query	string	按模板名称筛选
  tags	Query	string[]	按标签筛选，可以重复传：tags=a&tags=b
  status	Query	integer	已废弃只为兼容旧集成保留：不传或传 1 时正常返回，传其他值返回 400。include_inactive 会被忽略。
  page	Query	integer	页码，从 1 开始，默认 1
  page_size	Query	integer	每页条数，默认 20，最大 100

  响应 · 分页列表<TemplateItem>

  {
    "items": [
      {
        "share_id": "1938475610293847552",
        "group_id": "1938475610293840001",
        "share_code": "S-7K2M9Q",
        "release_id": "1938475610293850112",
        "version_no": 3,
        "name": "发货标签 100×150",
        "description": null,
        "width": 100,
        "height": 150,
        "size_unit": "mm",
        "source": 1,
        "released_at": "2025-01-01T10:00:00+08:00",
        "thumbnail": {
          "url": "https://<oss-domain>/<signed-path>",
          "expires_at": "2025-01-01T11:00:00+08:00"
        },
        "can_print": true
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }

  错误

  • 400 invalid_parameter — status 传了 1 以外的值
  • 403 forbidden — 无权访问该分组
  • 404 not_found — 分组不存在

打印机

查询打印机及其运行状态。提交打印任务前，可以用 for-print 拿到已绑定且已启用的打印机，以及它们的在线状态。

• •提交打印任务使用打印机的 code（printer_code），不是 id。for-print 不返回 code，请用 GET /printers 或 /printers/:id 获取；code 为空的打印机不能通过 OpenAPI 提交任务。
• •GET /printers 默认只返回 status=active 且 bind_status=bound 的打印机。要查看全部，请传 include_unusable=true。
• •GET /printers/:id 不按状态过滤，可能返回已禁用或已解绑的打印机。使用前请检查 status 和 bind_status。
• •online 由服务端根据 last_reported_at 计算；runtime_status 是打印机最后一次上报的值。打印机掉线后，runtime_status 可能仍停留在 READY，判断是否可用时请同时看这两个字段。
• •打印机接口中没有值的字段会被省略，不会返回 null，请按字段可能不存在处理。

• GET/printers/for-printprinter:read

  列出可用于打印的打印机（按终端分组）

  只返回已绑定且已启用的打印机，附带在线状态。不分页。

  参数与响应

  响应 · ListForPrintResponse

  {
    "groups": [
      {
        "terminal_id": "1938475610293870001",
        "terminal_name": "仓库前台电脑",
        "terminal_code": "<terminal-code>",
        "terminal_online": true,
        "printers": [
          {
            "id": "1938475610293860001",
            "name": "仓库 1 号机",
            "device_key": "<device-key>",
            "conn_type": "USB_DIRECT",
            "model_name": "ZD421",
            "default_dpi": 203,
            "default_lang": "ZPL",
            "print_width_mm": 104,
            "print_height_mm": 150,
            "runtime_status": "READY",
            "online": true,
            "last_reported_at": "2025-01-01T10:00:00+08:00"
          }
        ]
      }
    ],
    "total_count": 1,
    "online_count": 1
  }

• GET/printersprinter:read

  分页查询打印机列表

  默认只返回已启用且已绑定的打印机。

  参数与响应

  参数

  名称	位置	类型	说明
  name	Query	string	按名称筛选
  device_key	Query	string	按设备标识筛选
  tag	Query	string	按标签筛选（单个）
  conn_type	Query	string	按连接类型筛选：USB_DIRECT / WINDOWS_SPOOLER / CUPS / NETWORK
  include_unusable	Query	string	传 true（小写）时返回所有状态的打印机，其他值都按不传处理
  status	Query	integer	业务状态：1 启用，2 禁用。只在 include_unusable=true 时生效，否则会被忽略
  bind_status	Query	integer	绑定状态：0 已发现，1 已绑定，2 已解绑。只在 include_unusable=true 时生效，否则会被忽略
  page	Query	integer	页码，从 1 开始，默认 1
  page_size	Query	integer	每页条数，默认 20，最大 100

  响应 · 分页列表<Printer>

  {
    "items": [
      {
        "id": "1938475610293860001",
        "code": "<printer-code>",
        "name": "仓库 1 号机",
        "device_key": "<device-key>",
        "conn_type": "USB_DIRECT",
        "terminal_id": "1938475610293870001",
        "group_id": "1938475610293880001",
        "status": "active",
        "bind_status": "bound",
        "model_name": "ZD421",
        "manufacturer": "Zebra",
        "default_dpi": 203,
        "default_lang": "ZPL",
        "print_width_mm": 104,
        "print_height_mm": 150,
        "runtime_status": "READY",
        "online": true,
        "last_reported_at": "2025-01-01T10:00:00+08:00",
        "capabilities": {
          "max_width_mm": 104,
          "supported_dpi": [203, 300],
          "supported_langs": ["ZPL", "EPL"],
          "has_cutter": true
        },
        "tags": ["仓库A"],
        "firmware_version": "V84.20.21Z",
        "bound_at": "2024-12-01T09:00:00+08:00",
        "updated_at": "2025-01-01T10:00:00+08:00",
        "created_at": "2024-12-01T09:00:00+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }

  错误

  • 400 invalid_parameter — status 或 bind_status 不是整数
• GET/printers/:idprinter:read

  查询打印机详情

  不按状态过滤，可能返回已禁用或已解绑的打印机。

  参数与响应

  参数

  名称	位置	类型	说明
  id*	路径	string	打印机 ID

  响应 · Printer

  {
    "id": "1938475610293860001",
    "code": "<printer-code>",
    "name": "仓库 1 号机",
    "device_key": "<device-key>",
    "conn_type": "USB_DIRECT",
    "terminal_id": "1938475610293870001",
    "group_id": "1938475610293880001",
    "status": "active",
    "bind_status": "bound",
    "model_name": "ZD421",
    "manufacturer": "Zebra",
    "default_dpi": 203,
    "default_lang": "ZPL",
    "print_width_mm": 104,
    "print_height_mm": 150,
    "runtime_status": "READY",
    "online": true,
    "last_reported_at": "2025-01-01T10:00:00+08:00",
    "capabilities": {
      "max_width_mm": 104,
      "supported_dpi": [203, 300],
      "supported_langs": ["ZPL", "EPL"],
      "has_cutter": true
    },
    "tags": ["仓库A"],
    "firmware_version": "V84.20.21Z",
    "bound_at": "2024-12-01T09:00:00+08:00",
    "updated_at": "2025-01-01T10:00:00+08:00",
    "created_at": "2024-12-01T09:00:00+08:00"
  }

  错误

  • 400 invalid_parameter — id 不是正整数
  • 404 not_found — 打印机不存在或不属于当前企业

存储

上传模板会用到的图片、字体等文件。流程分三步：申请上传 → 直传 → 确认。

• GET/storage/usagestorage:read

  查询存储用量

• POST/storage/uploadsstorage:write计配额

  申请上传，获取直传地址

• POST/storage/uploads/:id/confirmstorage:write计配额

  确认上传完成

• GET/storage/filesstorage:read

  分页查询文件列表

• GET/storage/files/:idstorage:read

  查询文件详情

• GET/storage/files/:id/urlstorage:read

  获取临时下载地址

• DELETE/storage/files/:idstorage:write计配额

  删除文件