Quick Order Form용 API

공개 API를 사용해 Quick Order Form, Quick Buy Collection, Quick Buy Variant 테이블을 생성, 업데이트, 조회, 삭제하세요.

이 페이지에서는 Quick Order Form 기능군의 공개 API를 설명해요. 하나의 엔드포인트가 관련된 세 가지 레코드 유형을 모두 처리하며, type 필드로 구분해요.

quick_order_page — 독립형 Quick Order Form 페이지.
quick_buy_collection — 컬렉션/제품 카드 페이지의 Quick Buy 기능.
quick_buy_variant — 제품 페이지의 옵션 테이블(Variant Table).

4가지 작업 모두 공개 API에 설명된 것과 같은 기본 URL, 헤더, 인증을 사용해요.

레코드 생성

엔드포인트

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

요청 헤더

헤더	설명	필수
`X-SAMITA-API-KEY`	Wholesale 앱에서 제공하는 API 키	예
`X-SAMITA-SHOP-URL`	xxx.myshopify.com 형식의 Shopify 스토어 도메인	예
`CONTENT-TYPE`	`application/json`이어야 해요	예

이 API를 사용하려면 생성하려는 특정 type에 대해 API 키에 Create 권한이 있어야 해요.

공통 필드(모든 유형)

필드	유형	필수	설명
`title`	string, 최대 255자	예	앱에 표시되는 레코드 이름.
`status`	boolean	예	활성 여부.
`type`	string	예	`quick_order_page`, `quick_buy_collection` 또는 `quick_buy_variant`.

나머지 필수 필드는 type에 따라 달라요.

필드	유형	참고
`apply_product`	object (필수)	`type`: `products` 또는 `collections`.
`apply_product.product_ids`	array	`type`이 `products`일 때 필수.
`apply_product.collection_ids`	array	`type`이 `collections`일 때 필수.
`display_on_page`	string (필수)	이 양식이 표시되는 Shopify 페이지의 핸들.
`pagination`	object (필수)	`type`: `pagination` 또는 `load_more_button`, `per_page`: 1~50 사이의 숫자.
`columns`	object (필수)	`product_stock`: boolean — 재고 열을 표시하거나 숨겨요.

예시:

{
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product_stock": true
  }
}

필드	유형	참고
`apply_product`	object (필수)	`type`: `all`, `products`, `collections` 또는 `product-tags`, 그리고 이에 맞는 `product_ids` / `collection_ids` / `product_tags`.
`exclude_product`	object (필수)	`type`: `none`, `products` 또는 `collections`, 그리고 이에 맞는 ID.
`apply_customer`	object (필수)	`type`: `all`, `logged`, `non-logged` 또는 `customer-tags`, 해당하는 경우 `tags`와 함께 사용.
`exclude_customer`	object (필수)	`type`: `none` 또는 `customer-tags`, 해당하는 경우 `tags`와 함께 사용.
`display_on_pages`	array (필수)	`index`, `collection`, `search`, `another_page` 중 하나 이상.
`columns`	object (필수)	Boolean 값: `stock_status`, `quantity`, `variant`, `volume_discount`, `add_to_cart`.

예시:

{
  "title": "Quick Buy on Collections",
  "status": true,
  "type": "quick_buy_collection",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "customer-tags", "tags": ["wholesale"] },
  "exclude_customer": { "type": "none", "tags": [] },
  "display_on_pages": ["collection", "index"],
  "columns": {
    "stock_status": true,
    "quantity": true,
    "variant": true,
    "volume_discount": true,
    "add_to_cart": true
  }
}

필드	유형	참고
`apply_product`	object (필수)	`quick_buy_collection`과 같은 구조.
`exclude_product`	object (필수)	`quick_buy_collection`과 같은 구조.
`apply_customer`	object (필수)	`quick_buy_collection`과 같은 구조.
`exclude_customer`	object (필수)	`quick_buy_collection`과 같은 구조.
`template`	string (필수)	`default` 또는 `matrix-column`.
`columns`	object (필수)	`stock`: boolean — 재고 열을 표시하거나 숨겨요.

예시:

{
  "title": "Variant Table",
  "status": true,
  "type": "quick_buy_variant",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "logged", "tags": [] },
  "exclude_customer": { "type": "none", "tags": [] },
  "template": "default",
  "columns": {
    "stock": true
  }
}

응답

200 – Success는 생성된 레코드를 반환해요. 아래 레코드 조회의 예시를 참고하세요.

레코드 업데이트

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

헤더는 생성과 같아요. 변경하려는 필드만 보내세요. title, status, configs, product_configs는 모두 선택 사항이며, 지정하지 않은 필드는 현재 값이 유지돼요. 이 API를 사용하려면 Update 권한이 필요해요.

레코드 조회

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

헤더는 생성과 같으며 요청 본문은 없어요. 이 API를 사용하려면 View 권한이 필요해요.

200 – Success 예시(type: quick_order_page):

{
  "id": 1,
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "product_ids": [],
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product": true,
    "product_stock": true,
    "quantity": true,
    "action": true
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

레코드 삭제

DELETE https://wholesale.samita.io/api/v1/quick-order-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를 참고하세요.

도움이 되었나요?