Ecommerce platforms
面向 Shopify app 和后端工作流的 PDF API
从 Shopify app 或后端工作流调用 gPdf，基于映射后的 Shopify 数据生成订单 PDF、发票、装箱单、退货文档和标签。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 Shopify app 后端 / 电商后端 / OMS / 履约工作流
要解决的问题
使用 Shopify app 或电商后端，把订单、客户、商品、履约和退货数据映射成 gPdf JSON 或模板数据，然后返回确定性 PDF，同时不宣称原生 Shopify app-store 集成。
什么时候用这个 API
- 你正在构建可以调用外部 API 的 Shopify app、私有后端或履约流程。
- 你的 app 已经接收 Shopify 订单、履约、客户或商品数据。
- 你需要发票、装箱单、退货文档、仓库标签或 PDF 附件。
- 你希望为商家专属文档版式提供稳定的 template_id 合同。
它不替代什么
- 你期待 gPdf 是官方 Shopify app 或 app-store listing。
- 你需要 gPdf 安装到商家店铺、处理 OAuth 或直接订阅 webhooks。
- 你需要 gPdf 提供运费、邮资购买、库存管理或商家 UI 功能。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/template-render - app 后端将映射后的 Shopify 订单数据发送到已发布模板。
{
"template_id": "packing_list",
"data": [
{
"order_number": "#1042",
"customer_name": "Example Buyer",
"ship_to": "1200 Market St, San Francisco, CA",
"items": [
{ "sku": "TSHIRT-BLK-M", "name": "Black T-shirt", "quantity": 2 },
{ "sku": "MUG-WHT", "name": "White mug", "quantity": 1 }
]
}
]
}
gPdf 负责什么
- 基于你的 app 后端映射出的 Shopify-derived JSON 渲染 PDF。
- 为商家或品牌专属文档版式提供 Template Render。
- 处理条码、QR code、表格、合计、图片、标签和装箱单结构。
- 通过公开 gPdf API 进行无状态 PDF 生成。
你的系统负责什么
- Shopify app 代码、OAuth、webhooks、商家 UI 和 app-store 分发。
- 订单、履约、客户、退货、商品和税务数据映射。
- 商家配置、模板选择、交付、存储和重试。
上线前检查
- 把 Shopify 凭证和 gPdf API tokens 放在后端，不要放进浏览器代码。
- 把 Shopify 数据映射成显式 render payload 或 template data schema。
- 商家专属版式批准后使用 Template Render。
- 按商家工作流保存生成的 PDF 或源数据。
- 明确说明这是你的 app 调用 gPdf，而不是官方 gPdf Shopify app。
能力边界
- 除非确实存在公开官方 Shopify app，否则不要这样宣称。
- gPdf 不运行 Shopify OAuth、app 安装、webhooks 或商家设置。
- 调用方负责 Shopify 数据映射和电商业务规则。
集成模型
清晰的 Shopify 集成模型是后端到后端。你的 app 接收或拉取 Shopify 数据，把它映射成 gPdf DocumentRequest 或 template data object，调用 gPdf，然后按商家工作流返回或存储 PDF。
这样公开表述才准确：gPdf 是你的 Shopify app 可以调用的 PDF 生成 API。除非存在单独的公开官方 Shopify app 产品，否则它不是官方 Shopify app。
Template Render 适合商家版式
电商 PDF 往往会变成商家专属：品牌、商品表格、退货说明、标签区块、礼品备注和本地化文本。Template Render 让你的 app 把这些版式保留在已发布模板中，而 app 只发送映射后的订单数据。
把平台逻辑留在 app 中
OAuth、webhooks、商家设置、履约状态、库存、退货规则和 app-store 分发都留在你的 Shopify app 中。gPdf 应接收最终渲染数据并生成 PDF。
常见问题
- gPdf 是官方 Shopify app 吗？
- 不是。这个页面面向调用 gPdf 的 app 和后端。除非对应产品存在，否则不要把 gPdf 表述为官方 Shopify app-store 集成。
- gPdf API 调用应该发生在哪里？
- 请从你的后端或 app server 调用 gPdf，这样 Shopify 凭证和 gPdf API token 才能被保护。
- Shopify PDF 应该用 JSON Render 还是 Template Render？
- 自定义生成版式使用 JSON Render。商家或品牌版式批准、调用方只应发送数据时，使用 Template Render。
- gPdf 会处理 Shopify webhooks 吗？
- 不会。你的 app 接收 webhooks、映射数据并决定何时渲染。gPdf 只渲染它收到的 PDF 请求。