가입 양식용 API

이 페이지에서는 도매 고객이 제출하는 가입 양식인 Registration Form을 관리하는 공개 API를 설명해요. 4가지 작업 모두 공개 API에 설명된 것과 같은 기본 URL, 헤더, 인증을 사용해요.

참고

Registration Form의 필드 레이아웃(elements)은 복잡해질 수 있어요. 요청을 처음부터 만들기 전에 앱에서 만든 기존 양식에 GET을 사용해 예상되는 구조의 실제 예시를 확인한 다음, 필요한 부분만 조정하는 것을 권장해요.

가입 양식 생성

엔드포인트

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

요청 헤더

헤더	설명	필수
X-SAMITA-API-KEY	Wholesale 앱에서 제공하는 API 키	예
X-SAMITA-SHOP-URL	xxx.myshopify.com 형식의 Shopify 스토어 도메인	예
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는 생성된 레코드를 반환해요. 응답 구조는 아래 가입 양식 조회의 예시를 참고하세요.

가입 양식 업데이트

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

헤더는 생성과 같아요. 변경하려는 필드만 보내세요. title, status, secret_configs(GET이 반환하는 것과 같은 구조의 전체 구성 객체이며 configs 키 아래에 있음)는 모두 선택 사항이에요. 지정하지 않은 필드는 현재 값이 유지돼요. 이 API를 사용하려면 Update 권한이 필요해요.

가입 양식 조회

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 }
    ]
  }
}

가입 양식 삭제

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

헤더는 생성과 같아요. 삭제할 양식 ID를 쉼표로 구분한 목록인 ids 파라미터를 쿼리 문자열 파라미터 또는 JSON 본문 필드로 전달하세요(예: ids=1,2,3). 이 API를 사용하려면 Delete 권한이 필요해요.

200 – Success:

{
  "success": true
}

오류 응답

4개 엔드포인트 모두 나머지 공개 API와 같은 오류 응답을 사용해요. 401 Unauthorized, 403 Forbidden, 429 Too Many Requests는 공개 API를 참고하세요.