查询下单模板

API文档最后更新: 2026-08-31

6.4 查询下单模板

  • 请求方式：GET

  • 请求地址：/goods/tpl

在第三方平台创建本地商品或新增规格时调用一次。productRef 必须填写；多规格商品还必须填写商品详情返回的 variantRef，单规格商品不填写时自动使用默认规格。接口返回：

多规格充值商品不在商品或规格记录中保存自定义模板。平台按该规格已配置购买通道的固定顺序取第一份有效下单模板和数量规则；购买通道存在多级关系时逐级使用相同规则。创建 OpenAPI 订单时固定使用与查询结果相同的购买通道，不会切换到其他模板。前台购买规则不受此约束。

请求字段：

字段

位置

JSON 类型

必填

含义

productRef

Query

integer

是

商品编号

variantRef

Query

integer

多规格是

规格编号；单规格商品不填时自动使用数字 0

返回字段：

字段

JSON 类型

必填

含义

code

integer

是

固定为 0，表示请求成功

message

string

是

本次请求的处理说明

data

object

是

指定商品规格的下单模板

data.productRef

integer

是

模板所属商品编号

data.variantRef

integer

是

模板所属规格编号

data.purchaseSchemaRevision

integer

是

下单模板版本；值变化时重新获取模板

data.unitRule

object

是

购买数量规则

data.unitRule.mode

string

是

range 按范围和步长选择；fixedSet 只能选择固定数量

data.unitRule.minimum

integer

是

最少购买数量

data.unitRule.maximum

integer

是

最多购买数量

data.unitRule.increment

integer

是

range 模式的数量步长

data.unitRule.allowedValues

integer[]

是

fixedSet 模式允许的数量；range 模式为空数组

data.entryMode

string

是

singleEntry 提交一组资料；oneEntryPerUnit 每件商品提交一组资料

data.purchaseFields

object[]

是

第三方下单页面需要展示的字段；没有字段时为空数组

data.purchaseFields[].fieldRef

string

是

下单字段编号；创建订单时原样作为字段名

data.purchaseFields[].control

string

是

singleLine 单行文本；numeric 数字；multiLine 多行文本；dropdown 下拉；singleChoice 单选；multipleChoice 多选；qrText 二维码文本；imageUrl 公网图片地址

data.purchaseFields[].title

string

是

下单字段名称

data.purchaseFields[].mandatory

boolean

是

true 表示创建订单时必须填写

data.purchaseFields[].placeholder

string

是

输入框提示文字；没有提示时为空字符串

data.purchaseFields[].description

string

是

字段补充说明；没有说明时为空字符串

data.purchaseFields[].constraints

object

是

输入值校验规则

data.purchaseFields[].constraints.pattern

string

否

输入值需要匹配的正则表达式

data.purchaseFields[].constraints.patternDialect

string

否

返回正则时固定为 ECMAScript

data.purchaseFields[].constraints.serverValidationOnly

boolean

是

true 表示第三方只做基础校验，提交后由平台完成完整校验

data.purchaseFields[].constraints.minLength

integer

否

文本最少字符数

data.purchaseFields[].constraints.maxLength

integer

否

文本最多字符数

data.purchaseFields[].constraints.min

number

否

数字最小值

data.purchaseFields[].constraints.max

number

否

数字最大值

data.purchaseFields[].choices

object[]

是

下拉、单选或多选的可选项；其他控件为空数组

data.purchaseFields[].choices[].text

string

是

展示给用户的选项名称

data.purchaseFields[].choices[].code

string

是

创建订单时提交的选项值

data.needsOtp

boolean

是

true 表示订单处理过程中会要求提交验证码

requestId

string

是

本次请求编号，排查问题时提供给平台

返回示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "productRef": 1001,
    "variantRef": 0,
    "purchaseSchemaRevision": 1753776000,
    "unitRule": {
      "mode": "range",
      "minimum": 1,
      "maximum": 1,
      "increment": 1,
      "allowedValues": []
    },
    "entryMode": "singleEntry",
    "purchaseFields": [
      {
        "fieldRef": "account",
        "control": "singleLine",
        "title": "充值手机号",
        "mandatory": true,
        "placeholder": "请输入 11 位手机号",
        "description": "请确认号码正确，提交后无法修改",
        "constraints": {
          "serverValidationOnly": true,
          "minLength": 11,
          "maxLength": 11
        },
        "choices": []
      },
      {
        "fieldRef": "region",
        "control": "dropdown",
        "title": "号码归属省份",
        "mandatory": true,
        "placeholder": "请选择省份",
        "description": "提交选项的 code",
        "constraints": {
          "serverValidationOnly": false
        },
        "choices": [
          {
            "text": "广东",
            "code": "guangdong"
          },
          {
            "text": "浙江",
            "code": "zhejiang"
          }
        ]
      }
    ],
    "needsOtp": false
  },
  "requestId": "req_01K0EXAMPLE"
}

数量规则：

  • 商品未配置最高购买数量时，maximum 默认为 100；商品可明确配置为 101～200，任何订单的绝对上限均为 200。

  • range：数量必须在 minimum 和 maximum 之间，并且符合 increment 步长。例如最小值为 1、步长为 2 时，可以购买 1、3、5 件。

  • fixedSet：数量只能使用 allowedValues 中列出的值。

control 与下单页面控件的对应关系：

control

页面控件和提交要求

singleLine

单行文本框，提交字符串

numeric

数字输入框，提交数字字符串

multiLine

多行文本框，提交字符串

dropdown

下拉选择，提交选项的 code

singleChoice

单选，提交选项的 code

multipleChoice

多选，提交选项 code 组成的字符串数组

qrText

已识别的二维码文本，提交识别结果字符串

imageUrl

公网 HTTPS 图片地址，提交 URL 字符串

fieldRef 必须原样作为 purchaseEntries[] 对象中的字段名。不要自行生成字段编号，也不要继续使用其他模板版本中的字段编号。

imageUrl 不需要上传文件，只提交公网可访问的 HTTPS 图片 URL。URL 最长 2048 个字符，可以包含查询参数，但不能提交 data:、Base64、本地路径、IP 地址、内网地址或回环地址；订单处理完成前必须保持图片可以访问。

第三方应保存完整返回结果并据此生成本地下单表单。正常创建订单直接使用本地保存的模板，不需要再次查询商品详情或下单模板。

product.changed 的 changedProperties 包含 purchaseSchemaRevision，并且 productSnapshot 中的版本与本地版本不同时，重新调用本接口并更新本地下单表单。

上一篇下一篇