Registration Form 的 API

本頁介紹用於管理 Registration Form 的 Public API，也就是批發顧客提交的註冊表單。這 4 種操作使用相同的基礎 URL、標頭和驗證方式，詳見 Public APIs。

注意

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 個端點與 Public API 的其他部分使用相同的錯誤回應，401 Unauthorized、403 Forbidden 和 429 Too Many Requests 請參閱 Public APIs。