Registration Form 的 API

本页介绍用于管理 Registration Form（批发客户提交的注册表单）的公共 API。这 4 种操作使用相同的基础 URL、请求头和身份验证，详见公共 API。

注意

Registration Form 的字段布局（elements）可能比较复杂。在从头构建请求之前，建议先对您在应用中创建的现有表单使用 GET，查看所需结构的真实示例，然后只调整需要更改的部分。

创建 Registration Form

端点

POST https://wholesale.samita.io/api/v1/registration-forms

请求头

请求头	说明	必填
X-SAMITA-API-KEY	Wholesale 应用中提供的 API 密钥	是
X-SAMITA-SHOP-URL	Shopify 商店域名，格式为 xxx.myshopify.com	是
CONTENT-TYPE	必须为 application/json	是

此 API 要求 API 密钥具有 Create 权限。

请求正文

顶层字段：

字段	类型	必填	说明
title	string	建议填写	表单在应用中的名称。
status	boolean	建议填写	表单是否启用。
shopify_integration	object	是	控制提交内容如何与 Shopify 客户关联，详见下文。
elements	array	是	表单的字段，按显示顺序排列，详见下文。
header	object	否	显示在表单顶部的标题文本。
footer	object	否	显示在表单底部的按钮和文本。
general	object	否	审批方式和默认客户标签。
errorMessage	object	否	自定义验证错误文本。
reCaptcha	object	否	此表单是否需要 reCAPTCHA。
afterSubmit	object	否	客户提交后的处理方式。

shopify_integration

字段	类型	备注
ifExist	string（必填）	returnError、continueAndUpdate 或 continueAndIgnoreError：提交的邮箱已有客户账户时的处理方式。
showMessage	boolean	显示提示信息，引导客户改为登录。
messageRedirectToLogin	string	该提示信息的文本。
sendEmailInvite	boolean	发送 Shopify 的账户激活邮件。
acceptsMarketing	boolean	让新客户订阅营销邮件。

elements（字段对象数组）

每个元素都需要 type，常见类型包括 text、email、phone、password、number、name、url、checkbox、radio、country、datetime、file、hidden、heading、paragraph、devider 和 html。

字段	类型	适用于	备注
type	string（必填）	全部	元素类型。
columnWidth	number（除 devider 外必填）	全部	33.33、50 或 100。
label / placeholder / description	string	输入类型	字段标签。
required	boolean（heading、paragraph、devider、html 必填）	上述类型	该字段是否必须填写。
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	添加确认密码字段。
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	选项列表配置。
inlineOption	number（必填）	checkbox, radio	20、25、33.33、50 或 100。
heading / text	string	heading / paragraph	显示内容。
html	string	html	原始 HTML 块。
allowed-multiple	boolean	file	允许上传多个文件。
allowed-extension	array	file	可选：csv, pdf, jpg, jpeg, gif, svg, png, psd, ai, stl, stp, step, doc, docx, txt, ex2, dxf, gbr, eps, mov, mp4, xls, xlsx, ods, numbers, xlsm, zip, heic, heif。
format, date-format, time-format	string	datetime	format：date/time/date-and-time。date-format：Y-m-d/d-m-Y/m-d-Y/d-m/m-d。time-format：12h/24h。
integration	string	任意	将此字段映射到 Shopify 客户属性：email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[] 或 note[]。

header, footer, general, errorMessage, reCaptcha, afterSubmit

部分	字段	类型	备注
header	active	boolean	显示或隐藏标题。
header	title	string，最长 255
header	description	string
footer	description	string
footer	previousText, nextText, submitText, resetButtonText	string	按钮标签。
footer	resetButton, submitFullWidth	boolean
footer	submitAlignment	string	left、center 或 right。
general	customerTaxExempt	boolean
general	customerProcess	string	review-approving（人工审批）或 approving（自动审批）。
general	customerTags	array	应用于已批准客户的标签。
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	string	每种验证错误的自定义文本。
reCaptcha	enable	boolean
afterSubmit	action	string	clearForm、redirectToPage 或 hideForm。
afterSubmit	message, redirectUrl	string

响应

200 – Success 返回已创建的记录。响应结构请参阅下方 获取 Registration Form 中的示例。

更新 Registration Form

PUT https://wholesale.samita.io/api/v1/registration-forms/{id}

请求头与创建时相同。只需发送要更改的字段，title、status 和 secret_configs（完整的配置对象，结构与 GET 返回的相同，键名为 configs）均为可选。未指定的字段保持当前值。此 API 需要 Update 权限。

获取 Registration Form

GET https://wholesale.samita.io/api/v1/registration-forms/{id}

请求头与创建时相同，无需请求正文。此 API 需要 View 权限。

200 – Success 示例：

{
  "id": 1,
  "title": "Wholesale Registration",
  "status": true,
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00",
  "configs": {
    "header": {
      "active": true,
      "title": "Apply for a wholesale account",
      "description": ""
    },
    "footer": {
      "previousText": "Back",
      "nextText": "Next",
      "submitText": "Submit",
      "resetButton": false,
      "resetButtonText": "Reset",
      "submitFullWidth": false,
      "submitAlignment": "left"
    },
    "general": {
      "customerTaxExempt": false,
      "customerProcess": "review-approving",
      "customerTags": ["wholesale"]
    },
    "reCaptcha": {
      "enable": false
    },
    "afterSubmit": {
      "action": "clearForm",
      "message": "Thanks! We'll review your application shortly.",
      "redirectUrl": ""
    },
    "integration": {
      "shopify": {
        "ifExist": "returnError",
        "showMessage": true,
        "sendEmailInvite": true,
        "acceptsMarketing": false,
        "integrationElements": {
          "email": "email",
          "first_name": "first_name",
          "last_name": "last_name"
        }
      }
    },
    "elements": [
      { "id": "first_name", "type": "name", "label": "First name", "required": true, "columnWidth": 50 },
      { "id": "last_name", "type": "name", "label": "Last name", "required": true, "columnWidth": 50 },
      { "id": "email", "type": "email", "label": "Email", "required": true, "columnWidth": 100 }
    ]
  }
}

删除 Registration Form

DELETE https://wholesale.samita.io/api/v1/registration-forms/{id}

请求头与创建时相同。传入 ids 参数，即要删除的表单 ID 的逗号分隔列表（可作为查询字符串参数或 JSON 正文字段），例如 ids=1,2,3。此 API 需要 Delete 权限。

200 – Success：

{
  "success": true
}

错误响应

这 4 个端点与公共 API 的其他部分使用相同的错误响应。有关 401 Unauthorized、403 Forbidden 和 429 Too Many Requests，请参阅公共 API。