创建自定义表单定义

接口说明

创建自定义表单定义接口用于为商户配置可复用的自定义表单字段。开发者可以通过此接口定义用户扫码时需要填写的字段信息，创建后可被多个二维码终端复用。

设计优势

一次创建，多次复用：同一套表单定义可绑定到多个二维码终端
集中管理：修改表单定义只需一处，所有绑定的终端自动生效
避免冗余：不会因为创建多个终端而重复存储表单定义数据

请求地址

【POST】/pay/applyment/custom_form_create

业务参数

参数	必填	类型	说明	示例值
merchant_no	是	String(32)	商户号（审核通过后获取）	1234567890
form_name	是	String(64)	表单名称（用于商户内部管理识别）	用户信息登记表
form_fields	是	Array[Object]	表单字段定义数组，最多支持 20 个字段	见下方说明

form_fields 字段说明

参数	必填	类型	说明	示例值
field	是	String(32)	字段名称（英文标识，用于数据存储）	user_name
label	是	String(64)	字段显示名称（用户看到的标签）	您的姓名
type	是	String	字段类型，支持：TEXT（单行文本）、TEXTAREA（多行文本）、NUMBER（数字）、PHONE（手机号）、EMAIL（邮箱）、SELECT（下拉选择）、RADIO（单选框）、CHECKBOX（多选框）、DATE（日期）	TEXT
required	是	Boolean	是否必填 `true` 必填 `false` 非必填	true
placeholder	否	String(128)	输入提示语	请输入您的姓名
options	条件	Array[String]	选项列表，当 type 为 SELECT、RADIO、CHECKBOX 时必填	["选项1", "选项2", "选项3"]
min_length	否	Integer	最小长度/最小值（文本为字符数，数字为数值）	1
max_length	否	Integer	最大长度/最大值（文本为字符数，数字为数值）	50
default_value	否	String(256)	默认值	默认选项1
sort_order	否	Integer	排序序号，数字越小越靠前，默认按传入顺序	1

字段类型详细说明

类型	说明	适用场景	特殊要求	示例
TEXT	单行文本输入框	姓名、地址、编号等短文本	-	用户姓名
TEXTAREA	多行文本输入框	备注、描述、详细地址等长文本	-	详细地址信息
NUMBER	数字输入框	金额、数量、年龄等数值	支持 min_length（最小值）和 max_length（最大值）	订单数量
PHONE	手机号输入框	联系电话、手机号码	自动校验11位手机号格式	13800138000
EMAIL	邮箱输入框	电子邮箱地址	自动校验邮箱格式	example@email.com
SELECT	下拉选择框	从预定义选项中单选	必须提供 options 参数	付款方式选择
RADIO	单选框组	从预定义选项中单选（直观展示）	必须提供 options 参数	性别选择
CHECKBOX	多选框组	从预定义选项中多选	必须提供 options 参数	兴趣爱好选择
DATE	日期选择器	日期选择（年-月-日）	自动校验日期格式 YYYY-MM-DD	2024-01-15

请求示例

示例1：创建用户信息收集表单

{
  "merchant_no": "1234567890",
  "form_name": "用户信息登记",
  "form_fields": [
    {
      "field": "user_name",
      "label": "您的姓名",
      "type": "TEXT",
      "required": true,
      "placeholder": "请输入您的真实姓名",
      "min_length": 2,
      "max_length": 20,
      "sort_order": 1
    },
    {
      "field": "user_phone",
      "label": "联系电话",
      "type": "PHONE",
      "required": true,
      "placeholder": "请输入11位手机号",
      "sort_order": 2
    },
    {
      "field": "payment_purpose",
      "label": "付款用途",
      "type": "SELECT",
      "required": false,
      "options": ["商品购买", "服务费用", "捐赠", "其他"],
      "default_value": "商品购买",
      "sort_order": 3
    },
    {
      "field": "remark",
      "label": "备注信息",
      "type": "TEXTAREA",
      "required": false,
      "placeholder": "如有特殊说明请填写",
      "max_length": 200,
      "sort_order": 4
    }
  ]
}

示例2：创建项目信息收集表单

{
  "merchant_no": "1234567890",
  "form_name": "项目付款信息",
  "form_fields": [
    {
      "field": "project_name",
      "label": "项目名称",
      "type": "TEXT",
      "required": true,
      "placeholder": "请输入项目名称",
      "max_length": 50,
      "sort_order": 1
    },
    {
      "field": "project_code",
      "label": "项目编号",
      "type": "TEXT",
      "required": true,
      "placeholder": "如：PRJ2024001",
      "sort_order": 2
    },
    {
      "field": "department",
      "label": "所属部门",
      "type": "RADIO",
      "required": true,
      "options": ["技术部", "市场部", "财务部", "人事部", "其他"],
      "sort_order": 3
    },
    {
      "field": "budget_amount",
      "label": "预算金额",
      "type": "NUMBER",
      "required": false,
      "placeholder": "请输入预算金额（元）",
      "min_length": 0,
      "max_length": 1000000,
      "sort_order": 4
    }
  ]
}

返回结果

参数	必填	类型	说明	示例值
code	是	String(32)	返回码，000000 表示成功	000000
message	是	String(128)	返回信息	创建成功
form_id	是	String(32)	表单定义ID（用于申请二维码时绑定）	FORM_20231201103000001

返回示例

{
  "code": "000000",
  "message": "创建成功",
  "form_id": "FORM_20231201103000001"
}

错误码

错误码	说明
000000	成功
FAIL	失败
PARAM_ERROR	参数错误
MERCHANT_NOT_FOUND	商户号不存在
MERCHANT_NOT_APPROVED	商户未审核通过
FORM_NAME_DUPLICATE	表单名称已存在
FIELD_COUNT_EXCEEDED	字段数量超过限制（最多20个）
FIELD_NAME_DUPLICATE	字段名称重复
FIELD_TYPE_INVALID	字段类型无效
OPTIONS_REQUIRED	选项列表不能为空（SELECT/RADIO/CHECKBOX类型）
FORM_CREATE_LIMIT_EXCEEDED	表单创建数量超限（每个商户最多50个）

注意事项

商户必须已通过进件审核（状态为 APPROVED）才能创建自定义表单
每个商户最多可创建 50 个自定义表单定义
每个表单最多支持 20 个字段
字段名称（field）在同一表单内必须唯一，建议使用英文和下划线
字段名称创建后不可修改，请谨慎设置
当字段类型为 SELECT、RADIO、CHECKBOX 时，必须提供 options 参数
创建的表单定义可通过 form_id 在申请固定二维码时绑定到终端
同一套表单定义可被多个二维码终端复用，避免数据冗余
表单定义创建后可以修改，但已被二维码终端引用的表单不能删除