版本：v2.0

获取订单导入模版

按营种 pid 返回订单导入模版字段清单，包含 base_fields（订单级基础字段）与 form_fields（报名表字段，分 child / big 两组），可用于生成 Excel 表头、渲染动态表单或做前置校验。数据口径与后台报名 Excel 导入校验同源。

POST/api/importTemplate

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由获取访问令牌获得
pid	Number	营种 ID（商品 ID）	必填	-	大于 0，见获取营种列表

CURL

V1

curl --location --request POST 'https://open.xinduobang.cn/api/importTemplate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'pid=1001'

V2（appid 为 `V2` 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/importTemplate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Timestamp: 1770000000' \
--header 'X-Nonce: 3f9c1a7b2e6d4058' \
--header 'X-Signature: <computed_hmac_sha256>' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'pid=1001'

信息

V2 签名算法及 X-Signature 计算方式见 V2 接入示例。下方接口 V2 示例均遵循相同规则，不再重复注释。

成功响应

{
  "code": 0,
  "msg": "",
  "data": {
    "base_fields": [
      { "type": "text", "title": "外部订单号",           "name": "out_order_sn", "isMust": 1, "options": [] },
      { "type": "text", "title": "营种PLU",              "name": "plu",          "isMust": 1, "options": [] },
      { "type": "text", "title": "儿童人数",             "name": "small_number", "isMust": 1, "options": [] },
      { "type": "text", "title": "成人人数（亲子有效）", "name": "big_number",   "isMust": 1, "options": [] },
      { "type": "text", "title": "会员手机号",           "name": "user_phone",   "isMust": 1, "options": [] },
      { "type": "text", "title": "订单备注",             "name": "remark",       "isMust": 0, "options": [] },
      { "type": "text", "title": "订单价格",             "name": "price",        "isMust": 0, "options": [] },
      { "type": "text", "title": "已支付",               "name": "paid",         "isMust": 0, "options": [] }
    ],
    "form_fields": {
      "child_form_id": 88,
      "big_form_id": 90,
      "child": [
        { "type": "text",   "title": "姓名",       "name": "name",        "isMust": 1, "options": [] },
        { "type": "radio",  "title": "性别",       "name": "gender",      "isMust": 0, "options": ["男", "女"] },
        { "type": "text",   "title": "手机号",     "name": "phone",       "isMust": 0, "options": [] },
        { "type": "date",   "title": "出生日期",   "name": "birthday",    "isMust": 0, "options": [] },
        { "type": "select", "title": "证件类型",   "name": "idcard_type", "isMust": 0, "options": ["身份证", "护照", "其他", "台胞证", "回乡证", "港澳通行证", "港澳居民居住证", "旅行证"] },
        { "type": "text",   "title": "有效证件号", "name": "idcard",      "isMust": 0, "options": [] }
      ],
      "big": [
        { "type": "text",   "title": "姓名",       "name": "name",        "isMust": 1, "options": [] },
        { "type": "radio",  "title": "性别",       "name": "gender",      "isMust": 0, "options": ["男", "女"] },
        { "type": "text",   "title": "手机号",     "name": "phone",       "isMust": 0, "options": [] },
        { "type": "date",   "title": "出生日期",   "name": "birthday",    "isMust": 0, "options": [] },
        { "type": "select", "title": "证件类型",   "name": "idcard_type", "isMust": 0, "options": ["身份证", "护照", "其他", "台胞证", "回乡证", "港澳通行证", "港澳居民居住证", "旅行证"] },
        { "type": "text",   "title": "有效证件号", "name": "idcard",      "isMust": 0, "options": [] }
      ]
    }
  }
}

响应字段说明

字段对象通用结构

base_fields、form_fields.child、form_fields.big 均为字段对象数组，每个字段对象结构一致：

字段	类型	说明
type	String	字段类型，见下方"type 枚举"
title	String	字段中文名，原样透传表单配置，不加"成人"等前缀
name	String	字段英文键，原样透传；`child` 与 `big` 组内可能出现同名 `name`，靠分组区分
isMust	Number	是否必填：`1` 必填，`0` 非必填
options	Array	可选项列表；仅 `type ∈ {select, radio, checkbox}` 时非空，其它类型恒为 `[]`

type 枚举

type	含义	是否输出	options 是否有值
text	单行文本	是	否
textarea	多行文本	是	否
number	数字	是	否
date	日期	是	否
radio	单选	是	是（来自 `itemName` 逗号拆分）
select	下拉单选	是	是
checkbox	多选	是	是
file	附件上传(图片地址)	否，过滤	—
other	分组标记（新版表单分节）	否，过滤	—
beizhushuoming	富文本备注 / 说明块	否，过滤	—

base_fields（订单级基础字段，固定顺序）

顺序	title	name	isMust	触发条件
1	外部订单号	out_order_sn	1	恒定输出；上游自定义的订单唯一号，作为导入订单的幂等键（重复推送同一号不重复建单）
2	营种PLU	plu	1	恒定输出
3	儿童人数 / 人数	small_number	1	恒定输出；title 随 `product_type` 变化：亲子营(`product_type=1`) 显示"儿童人数"，其它类型（`0` 儿童单飞 / `3` 研学）显示"人数"
4	成人人数（亲子有效）	big_number	1	仅当 `product.product_type == 1`（亲子营）时输出
5	会员手机号	user_phone	1	恒定输出
6	订单备注	remark	0	恒定输出
7	订单价格	price	0	恒定输出
8	已支付	paid	0	恒定输出

out_order_sn 是接口幂等键，务必保证全局唯一。走导入订单接口时，未声明名额则默认由 students / big_students 数量推断；也可按最新接口参数声明 number / small_number / big_number，先建订单后补营员。字段优先级与限制以导入接口文档为准。

plu 未内嵌候选项。同一 pid 下可能有多个营期 × 多个规格，plu 集合规模大且随营期变动，请按需从获取营种详情的 spec_period.period_list[].sku_plu 拉取。

form_fields（报名表字段）

字段	类型	说明
child_form_id	Number	儿童报名表 ID，来源 `product.form_id`；未配置时为 `0`
big_form_id	Number	成人报名表 ID，来源 `product.big_form_id`；非亲子营(`product_type != 1`) 强制为 `0`（即使 DB 有历史值也不返回，避免上游误用），亲子营且未配置时同样为 `0`
child	Array	儿童报名表字段数组，数据源 `product.form_id → form.value`
big	Array	成人报名表字段数组，数据源 `product.big_form_id → form.value`；非亲子营时恒为 `[]`

form_fields.child 输出规则：

按表单 value 原顺序遍历；
过滤 type ∈ {file, other, beizhushuoming}；
select / radio / checkbox 展开 itemName（逗号分隔）到 options，trim 后过滤空串；
name == idcard_type 时，options 强制覆盖为标准 8 项：身份证 / 护照 / 其他 / 台胞证 / 回乡证 / 港澳通行证 / 港澳居民居住证 / 旅行证；
name ∈ {medicine_forbid, food_forbid, medical_history}（药物过敏 / 饮食禁忌 / 疾病史）时，强制按 text 输出且 options 为 []（详见下方"带补充选项的特殊字段"）；
isMust 统一转 int，缺失按 0；title / name 缺失按空串；
老版模板兜底：若 JSON 中不含任何 type == other 分组标记，视为老版模板，自动前置内置 6 项（姓名 / 性别 / 手机号 / 出生日期 / 证件类型 / 有效证件号），再拼接原表单剩余项。

带补充选项的特殊字段（medicine_forbid / food_forbid / medical_history）

这 3 个字段（药物过敏 / 饮食禁忌 / 疾病史）底层表单其实是 radio + "其他"补充项：选"有"时才需填写补充文本。为简化上游对接，导入模版将其统一暴露为 text 类型（options 恒为 []），约定：

填入文本 → 视为"有"该情况，所填内容即补充说明（如 medicine_forbid 填"青霉素过敏"）；
留空（或填"无"）→ 视为"无"。

落库时服务端会把该文本写入扩展数据的 other{字段名}（othermedicine_forbid / otherfood_forbid / othermedical_history），并把标记位 {字段名} 置 2（有）/ 1（无），与后台既有一致。上游只需按 text 传一列即可，无需再单独传"有 / 无"与 otherxxx。

form_fields.big 输出规则：

触发条件：product.product_type == 1（亲子营）；否则整个 big 直接为 []；
解析规则与 form_fields.child 完全一致；
不做任何 title / name 前缀改写，靠外层分组键 big 区分；
因此当儿童表与成人表存在同名字段（如 name / gender / idcard）时，需按 form_fields.child[*] 与 form_fields.big[*] 分别处理，不能扁平合并。

失败响应

{
  "code": 1,
  "msg": "缺少必要参数"
}

{
  "code": 0,
  "msg": "营种不存在或已删除",
  "data": []
}

HTTP状态码	错误码	描述	排查建议
200	1	缺少必要参数	请检查 `pid` 是否传入且大于 0
200	0	`msg` 非空时为业务错误	`data` 为空数组，根据 `msg` 提示排查（如 `pid不能为空`、`营种不存在或已删除`）

补充说明

表头生成：按 base_fields → form_fields.child →（若亲子营）form_fields.big 顺序拼接 Excel 表头。同名字段（如 name / gender / idcard）建议在实际表头文案上自行加"儿童 / 成人"前缀以便人工填写，但字段 name 保留原样以便回传时按分组归档。
校验规则：isMust == 1 的字段做非空校验；options 非空的字段做枚举校验（多选 checkbox 允许多值，用逗号分隔）。
plu 候选：需要下拉选 plu 时请调用获取营种详情取 spec_period.period_list[].sku_plu。
非亲子营：base_fields 中不含 big_number，form_fields.big_form_id 为 0、form_fields.big 为 []，前端应据此隐藏"成人"分组。
老版模板兼容：接口已内置兜底，无需上游处理；表现为 child 数组前 6 项固定为姓名 / 性别 / 手机号 / 出生日期 / 证件类型 / 有效证件号。
幂等键：base_fields 首项 out_order_sn 为上游自定义的订单唯一号，回传导入订单时需全局唯一，重复推送同一号不会重复建单。

变更记录

日期	变更
2026-10-09	首次发布：支持按 `pid` 返回 `base_fields` + `form_fields.{child,big}` 三段结构；`select / radio / checkbox` 展开 `options`；过滤 `file / other / beizhushuoming`；`idcard_type` 强制标准 8 项；老版模板自动补内置 6 项
2026-10-09	`base_fields` 首项新增外部订单号 `out_order_sn`（恒定输出，作为 `importOrder` 幂等键）；人数字段 `small_number` 的 title 动态化：亲子营为"儿童人数"，其它类型为"人数"
2026-10-09	`form_fields` 新增 `child_form_id / big_form_id` 两个 int 键，暴露表单来源 ID；`big_form_id` 在非亲子营时强制为 `0`（与 `big=[]` 保持一致），未配置时也为 `0`
2026-10-19	特殊字段 `medicine_forbid / food_forbid / medical_history`（药物过敏 / 饮食禁忌 / 疾病史）由 `radio` 改按 `text` 输出（`options` 为 `[]`）：上游填入文本即代表"有"并作为补充说明，留空 /"无"代表"无"；落库路由到 `other{字段名}` 并复算标记 `2 / 1`（详见"带补充选项的特殊字段"）

请求参数​

CURL​

V1​

V2（appid 为 V2 版本）​

成功响应​

响应字段说明​

字段对象通用结构​

type 枚举​

base_fields（订单级基础字段，固定顺序）​

form_fields（报名表字段）​

带补充选项的特殊字段（medicine_forbid / food_forbid / medical_history）​

失败响应​

补充说明​

变更记录​

相关接口​