공개 API

1. API 사용 범위

a. API로 지원되는 기능

공개 API를 사용하면 Wholesale 앱의 주요 기능과 상호 작용할 수 있어요. 지원되는 기능은 다음과 같아요.

• 핵심 기능: Wholesale Pricing, Volume Pricing, Registration form, Quick Order Form, Quick Buy Collection, Quick Buy Variant
• 부가 기능: Order Limit, Shipping Rate, Extra Fee, Payment Term(출시 예정)

b. 지원되는 메서드

API는 다음 HTTP 메서드로 전체 CRUD 작업을 지원해요.

• GET – 데이터 조회
• POST – 새 데이터 생성
• PUT – 기존 데이터 업데이트
• DELETE – 데이터 삭제

API 키에는 다음 권한 수준을 부여할 수 있어요. Read Only/Write Only, Read & Write

지원되는 작업은 다음과 같아요. Get list - Get item - Create item - Update item - Delete item

c. 지원되는 Shopify 요금제:

Wholesale 애플리케이션의 공개 API는 다음 요건을 충족하는 Shopify 스토어에서 사용할 수 있어요.

• 프로덕션 스토어여야 해요(개발 스토어나 테스트 스토어에는 해당되지 않아요)
• Gold 요금제를 구독해야 해요

---

2. 인증

모든 API 요청은 처리되기 전에 올바르게 인증되어야 해요.

a. 필수 파라미터

각 API 요청에는 다음 필수 파라미터가 포함되어야 해요.

파라미터	설명
shop	Shopify 스토어 도메인(예: mystore.myshopify.com)
api_key	Wholesale 앱에서 생성한 API 키

이 파라미터 중 하나라도 누락되면 요청이 거부돼요.

b. API 키 관리

API 키는 Wholesale 앱 관리 화면에서 직접 생성하고 관리해요.
스토어 소유자는 각 API 키에 Read only/Write only, Read & Write 등의 권한을 설정할 수 있어요.

---

3. API 구조 및 응답 형식

a. API 엔드포인트

모든 API 요청은 다음 기본 URL을 사용해야 해요.

https://wholesale.samita.io/v1/

b. 기능별 엔드포인트

각 기능 그룹에는 고유한 엔드포인트가 있어요. 예를 들면 다음과 같아요.

• Wholesale 기능:

  https://wholesale.samita.io/v1/wholesale/

• Volume Pricing 기능:

  https://wholesale.samita.io/v1/volume/

(실제 엔드포인트는 특정 기능에 따라 다를 수 있어요.)

c. 지원되는 쿼리 파라미터

API는 여러 공통 쿼리 파라미터를 지원해요.

파라미터	설명
status	레코드의 상태
page	페이지 매김용 페이지 번호
limit	페이지당 레코드 수
sort	정렬 기준
query	검색 또는 필터 조건

요청 예시:

GET /wholesale?page=1&limit=20&sort=created_at

---

4. 응답 코드

각 API 요청은 다음 상태 코드 중 하나를 반환해요.

a. 일반적인 오류 응답

401 – Unauthorized

가능한 원인:

• 스토어 URL 누락
• API 키 누락
• 잘못된 스토어 URL
• 잘못된 API 키
• API 키가 스토어와 일치하지 않음

---

403 – This action is unauthorized

• API 키에 요청한 작업을 수행할 권한이 없음
• View / Create / Update / Delete 권한이 부족함

---

429 – Too Many Requests

• 요청 한도를 초과함
• API 호출 빈도가 허용된 속도 제한을 초과함

---

b. 성공 응답

200 – Success

• 요청이 유효해요
• API 작업이 성공적으로 실행되었어요
• 데이터가 올바른 형식으로 반환돼요

---

5. 속도 제한

시스템 성능과 안정성을 보장하기 위해 API 사용에는 일일 요청 한도가 적용돼요. 요청별/단기 간격 제한은 더 이상 없으며, 요금제의 일일 할당량 내에서라면 필요한 만큼 API를 호출할 수 있어요.

일일 한도는 스토어의 요금제에 따라 달라요.

요금제	일일 요청 한도
Free	하루 5회 요청
Starter	하루 50회 요청
Growth	하루 250회 요청
Enterprise	하루 500회 요청

일일 카운터는 매일 자정(서버 시간)에 초기화돼요.

일일 한도를 초과하면 시스템이 다음을 반환해요.

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}