Logistics and labels
面向电商逆向物流的退货面单 API
基于电商或客服数据生成退货面单和退货说明 PDF，支持标签尺寸页面、条码和模板化重打。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 电商后端 / 退货门户 / OMS / 3PL 后端
要解决的问题
基于 RMA、客户、商品、目的地和条码数据渲染退货面单 PDF 或退货说明，让退货门户能向客户提供确定性的文档。
什么时候用这个 API
- 你的系统已经创建 RMA 和退货授权。
- 承运商或退货系统已经提供面单 payload 或追踪数据。
- 你需要客户可下载、邮件发送或重打的 PDF 面单或说明页。
- 你希望同一退货面单版式通过 Template Render 复用。
它不替代什么
- 你需要 gPdf 审批退货、购买邮资或创建承运商货件。
- 你需要直接编排承运商 API。
- 你需要 ZPL 这类打印机命令输出。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带 RMA 条码的退货面单。
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 5,
"y": 8,
"content": "RETURN TO",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 5,
"y": 18,
"content": "Acme Returns\n500 Dock Door 4\nColumbus OH 43215",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "RMA-2026-77881",
"x": 5,
"y": 70,
"width": 88,
"height": 20,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf 负责什么
- 为标签尺寸退货面单和说明页渲染 PDF。
- 处理条码、文本、地址、RMA 和服务区块。
- 为已批准的退货面单或说明版式绑定模板。
- 为客户重复下载和客服重打提供确定性输出。
你的系统负责什么
- 退货资格、RMA 状态、承运商账号、邮资、追踪号和客户沟通。
- 正确的条码 payload、目的地地址、商品引用和退货窗口规则。
- 邮件投递、门户下载和客服审计链路。
上线前检查
- 渲染前先向承运商或退货服务商验证退货 payload。
- 使用客户或门店实际会用的标签纸打印并扫码。
- 传入 X-Request-Id，并在客服日志中保存 RMA 到 PDF 的追踪关系。
- 从客户视角让重复下载保持幂等。
- 把面单渲染和退款审批逻辑分离。
能力边界
- gPdf 渲染退货面单 PDF；不授权退货，也不购买邮资。
- 承运商验收和条码 payload 正确性由你负责。
- 公开 API 返回 PDF，不返回 ZPL 或直接打印机命令。
逆向物流需要清晰所有权
退货面单同时涉及客户体验和承运商规则。gPdf 负责 PDF 渲染。你的退货系统负责资格判断、RMA 状态、追踪、承运商 payload 和客户沟通。
在集成中保持这个边界可见。先生成退货决策，再用最终数据渲染文档。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 退货面单 API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 会创建退货货件吗？
- 不会。你的承运商或退货平台创建货件和 payload。gPdf 把这些数据渲染成 PDF。
- 退货面单可以用模板生成吗？
- 可以。退货面单或说明版式批准后，使用 Template Render。
- PDF 可以包含退货说明吗？
- 可以。同一个 render 请求可以根据你的版式生成面单页、说明页，或两者都生成。
- gPdf 可以替代承运商认证吗？
- 不可以。承运商验收、扫码测试和 payload 规则仍由你负责。