Open API

스토어의 상품과 주문을 조회하고 지급·교환·환불을 처리할 수 있습니다. API 키를 발급하면 바로 사용할 수 있습니다.

첫 요청

대시보드의 연동·개발자 → API 키에서 키를 발급합니다. 아래 예제의 스토어 ID를 내 스토어 ID로 바꾸고, QUARTZ_API_KEY에 발급한 키를 설정합니다.

주문 목록 조회

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/orders?limit=30" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

인증 헤더 하나면 됩니다. 별도의 서명이나 인증 서버 연동은 필요하지 않습니다.

API 키

인증 헤더

Authorization: Bearer YOUR_API_KEY

키는 발급한 스토어에서 선택한 기능에만 사용할 수 있습니다. 서버에서만 사용하고, 웹 페이지나 앱에 넣지 않습니다. 키가 노출되면 대시보드에서 폐기하고 새로 발급합니다.

Node.js

fetch

const response = await fetch(
  "https://api.quartz-vend.com/v1/open/stores/202603290001/orders?limit=30",
  { headers: { Authorization: `Bearer ${process.env.QUARTZ_API_KEY}` } }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error?.code ?? "REQUEST_FAILED");
console.log(result.data);

사용 권한

키를 만들 때 사용할 기능만 선택합니다. 조회용 키로 지급이나 환불을 처리할 수는 없습니다.

기능별 권한 목록

사용자

권한	기능
`read:user`	사용자 조회
`write:user_profile`	사용자 메모 수정
`write:user_balance`	기존 잔액 조정
`write:user_point`	스토어 포인트 조정
`write:user_blacklist`	사용자 이용 제한
`write:user_grade`	구매 등급 변경

주문·지급

권한	기능
`read:order`	주문·지급·환불 내역 조회
`write:order_fulfillment`	주문 지급
`write:order_exchange`	주문 교환

환불

권한	기능
`write:order_refund`	환불 요청
`write:refund_completion`	환불 송금 완료 기록

상품·재고

권한	기능
`read:product`	상품·옵션 조회
`read:inventory`	재고 현황 조회
`write:inventory`	재고 추가·제거
`write:product_fulfillment`	외부 지급 실행 설정 변경

후기

권한	기능
`read:review`	후기 조회

쿠폰

권한	기능
`read:coupon`	쿠폰 조회
`write:coupon`	쿠폰 관리

일반 설정

권한	기능
`read:settings`	일반 설정 조회
`write:settings`	일반 설정 변경

보안

권한	기능
`read:security`	보안 설정 조회
`write:security`	보안 설정·신뢰 이메일 도메인 변경

Webhook

권한	기능
`write:webhook`	Webhook 관리

API 참조

사용할 API를 선택하면 필요한 값과 호출 예제를 볼 수 있습니다. * 표시가 있는 값은 필수입니다.

사용자

설명

스토어 고객을 검색하거나 다음 페이지를 조회할 때 호출합니다.

쿼리 파라미터

필드	형식	설명
`cursor`	`string`	이전 응답의 pageInfo.nextCursor. 첫 요청에서는 보내지 않습니다.
`limit`	`integer`	한 번에 받을 개수. 기본값 30, 최댓값 100입니다.
`search`	`string`	최대 160자 검색어. 리소스에 따라 ID, 이름 또는 본문을 검색합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/users" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

items에는 사용자 ID, 닉네임, 구매등급, 잔액, 스토어 포인트, 블랙리스트, 관리자 메모와 최근 활동이 들어갑니다. pageInfo.nextCursor로 다음 페이지를 요청합니다.

설명

잔액 조정이나 등급 변경 전에 현재 고객 상태를 다시 확인할 때 호출합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

목록의 사용자 객체와 같은 구조를 반환합니다. 해당 스토어 고객이 아니거나 탈퇴한 사용자면 404입니다.

설명

스토어 운영자가 보는 고객 메모를 교체합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

요청 본문

필드	형식	설명
`adminNote*`	`string`	새 관리자 메모. 빈 문자열로 지울 수 있으며 최대 2,000자입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002/profile" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "adminNote": "기업 구매 문의 고객",
  "reason": "상담 결과 반영"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경이 끝난 사용자 상세 객체를 반환합니다. 변경 전·후 값과 reason은 스토어 감사로그에 기록됩니다.

설명

계좌 충전과 별개로 관리 사유가 있는 구매 잔액을 증감합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

요청 본문

필드	형식	설명
`deltaAmount*`	`정수 문자열`	증가분 또는 감소분. 0은 허용하지 않으며 음수는 차감입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002/balance-adjustments" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "deltaAmount": "5000",
  "reason": "오입금 수동 반영"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

userId, 조정 후 amount, deltaAmount와 currency(KRW)를 반환합니다.

조정 후 잔액은 0 미만 또는 2,000,000,000 초과가 될 수 없습니다.
별칭 /users/{userId}/balance도 지원하지만 새 연동에서는 canonical 경로를 사용하세요.

설명

해당 스토어에서만 쓰는 고객 포인트를 증감합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

요청 본문

필드	형식	설명
`deltaAmount*`	`정수 문자열`	증가분 또는 감소분. 0은 허용하지 않으며 음수는 차감입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002/point-adjustments" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "deltaAmount": "-1000",
  "reason": "중복 지급 회수"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

userId, 조정 후 amount와 deltaAmount를 반환합니다. 구매 잔액과 달리 currency 필드는 없습니다.

조정 후 포인트는 0 미만 또는 2,000,000,000 초과가 될 수 없습니다.
별칭 /users/{userId}/point도 지원합니다.

설명

한 스토어 안에서 고객의 구매와 이용을 차단하거나 해제합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

요청 본문

필드	형식	설명
`active*`	`boolean`	true는 차단, false는 해제입니다.
`expiresAt`	`RFC 3339 \| null`	차단 종료 일시. null이면 별도 종료일이 없습니다. 해제할 때는 무시됩니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002/blacklist" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "active": true,
  "expiresAt": "2026-09-01T00:00:00+09:00",
  "reason": "반복적인 결제 악용"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경이 반영된 사용자 상세 객체를 반환합니다.

설명

자동 산정 결과 대신 특정 구매등급을 수동 지정합니다.

경로 변수

필드	형식	설명
`userId*`	`12자리 숫자`	스토어 고객의 Quartz 사용자 ID입니다.

요청 본문

필드	형식	설명
`gradeCode*`	`string`	스토어에 등록된 등급 코드. 영문, 숫자, _, -만 사용할 수 있습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/users/202607190002/grade-overrides" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "gradeCode": "vip",
  "reason": "기업 계약 등급 적용"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경이 반영된 사용자 상세 객체를 반환합니다.

존재하지 않거나 삭제된 등급 코드는 404입니다.
별칭 /users/{userId}/grade-override도 지원합니다.

주문·지급

설명

지급 대기 주문을 찾거나 주문 상태를 동기화할 때 호출합니다.

쿼리 파라미터

필드	형식	설명
`cursor`	`string`	이전 응답의 pageInfo.nextCursor. 첫 요청에서는 보내지 않습니다.
`limit`	`integer`	한 번에 받을 개수. 기본값 30, 최댓값 100입니다.
`search`	`string`	최대 160자 검색어. 리소스에 따라 ID, 이름 또는 본문을 검색합니다.
`status`	`enum`	pending, paid, fulfilled, cancelled, rejected, stock_shortage, refunded 중 하나입니다.
`orderNumber`	`string`	#을 제외한 주문 ID와 정확히 일치하는 주문을 찾아요.
`userId`	`12자리 숫자`	구매자 ID로 필터링합니다.
`productId`	`12자리 숫자`	상품 ID로 필터링합니다.
`from`	`RFC 3339`	이 시각 이후 생성된 주문만 조회합니다.
`to`	`RFC 3339`	이 시각까지 생성된 주문만 조회합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/orders" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

items에 주문 상태, 구매자 snapshot, 금액 문자열, 상품·옵션, 쿠폰·수량 할인과 처리 시각을 반환합니다. 다음 페이지는 pageInfo.nextCursor를 사용합니다.

설명

Webhook을 받은 뒤 실제 지급 전에 주문 상태와 수량을 서버에서 다시 확인합니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

주문 목록 item과 같은 주문 객체를 반환합니다. Webhook payload만 믿고 지급하지 말고 이 응답의 status와 lineItems를 확인하세요.

설명

외부 지급 서버가 준비를 끝낸 수량의 전달 내용을 Quartz Vend 주문에 기록합니다. 일부 수량만 먼저 지급할 수도 있습니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

요청 본문

필드	형식	설명
`deliveries*`	`{ index, generation, message }[]`	이번에 지급할 index와 조회한 generation을 지정합니다. index는 0부터 주문 수량 - 1까지이며 중복할 수 없습니다. message는 최대 10,000자입니다. generation 생략은 최초 지급(0)에만 호환됩니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/fulfillments" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "deliveries": [
    {
      "index": 0,
      "generation": 0,
      "message": "LICENSE-KEY-001"
    }
  ]
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

orderId, status, fulfilledQuantity, pendingQuantity, refundedQuantity, totalQuantity를 반환합니다. pendingQuantity가 0이 되면 status가 fulfilled로 바뀝니다.

장바구니는 상품별로 주문 ID가 나뉩니다. 각 orderId를 조회하고 orderId:index:generation을 외부 재고 예약 키로 사용하세요.
판매자 수동 지급이 먼저 끝난 수량은 ORDER_UNIT_ALREADY_FULFILLED(409), 환불된 수량은 ORDER_UNIT_ALREADY_REFUNDED(409)를 반환합니다. 이 응답은 재시도하지 마세요.
store.order.fulfillment_pending 수신 → 주문과 /fulfillment 재조회 → 외부 재고 임시 예약 → 이 요청 성공 확인 → 외부 재고 확정 순서로 처리하세요. 수동/API 지급은 먼저 확정된 쪽만 반영됩니다.
현재 지급 차수가 다르면 ORDER_FULFILLMENT_CYCLE_CHANGED(409)입니다. 미지급 수량은 72시간 이후 지급이 차단되고 환불 처리 대상으로 전환됩니다. 계좌이체 환불은 판매자의 송금이 필요합니다.

설명

지급·교환·환불 전에 현재 수량별 상태와 차수를 확인합니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/fulfillment" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

orderId, quantity, status, mode, dueAt, serverNow, units를 반환합니다. units에는 index, generation, status, source, fulfilledAt, refundedAt, dueAt, canFulfill, canExchange, canRefund가 있습니다. 재고 원문은 반환하지 않습니다.

canFulfill 등의 값은 조회 시점 기준이며, 변경 요청에서 현재 상태를 다시 검증합니다.

설명

이미 지급된 수량만 교환합니다. API·수동 지급 상품은 새 내용을 즉시 전달하거나 다시 지급 대기로 보낼 수 있습니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

요청 본문

필드	형식	설명
`units*`	`{ index, generation }[]`	현재 차수의 교환 대상. 1~1,000개이며 index는 중복할 수 없습니다.
`deliveries`	`{ index, message }[]`	API·수동 지급 상품의 즉시 교환 내용. units와 동일한 index를 모두 포함해야 합니다. 생략하면 현재 상품 설정에 따라 로컬 재고를 지급하거나 새 72시간 지급 대기를 시작합니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/exchanges" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "units": [
    {
      "index": 0,
      "generation": 0
    }
  ],
  "deliveries": [
    {
      "index": 0,
      "message": "REPLACEMENT-001"
    }
  ],
  "reason": "재고 교환"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

orderId, status, exchangeCount, unitIndexes, fulfillmentPending을 반환합니다. 교환된 수량의 generation은 1 증가합니다.

지급 대기·환불 수량은 교환할 수 없습니다. 교환 자체의 재시도는 같은 멱등 키와 본문으로 보내세요. 이후 지급에는 /fulfillment에서 다시 조회한 generation을 사용하세요.

환불

설명

판매자 권한으로 선택 수량을 환불 처리하고 이후 지급을 차단합니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

요청 본문

필드	형식	설명
`units*`	`{ index, generation }[]`	현재 차수의 환불 대상. 1~1,000개이며 index는 중복할 수 없습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/refunds" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "units": [
    {
      "index": 1,
      "generation": 0
    }
  ],
  "reason": "고객 요청 환불"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

환불 수량·금액·주문 상태와 refundMethod, cashRefund를 반환합니다. 계좌이체 주문은 cashRefund.status가 pending인 송금 대기 요청으로 접수되며 실제 은행송금을 수행하지 않습니다.

새 권한은 기존 키에 자동 부여하지 않습니다. 환불 권한을 부여하려면 고객 잔액 관리 권한도 필요합니다.
이미 지급된 재고는 보존하고 미지급 수량의 예약만 복구합니다. 신규 주문에 기존 고객 잔액을 사용하는 기능은 켜지지 않습니다.

설명

환불 요청 후 판매자가 송금을 완료 처리했는지 확인합니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/refunds" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

orderId와 refunds를 반환합니다. 각 환불의 id, quantity, amount, unitIndexes, createdAt, cashRefundId, cashRefundStatus, completedAt을 포함하며 계좌 정보는 반환하지 않습니다. cashRefundStatus가 null이면 은행송금 완료를 의미하지 않습니다.

설명

판매자가 실제 은행송금을 끝낸 뒤 환불 요청을 완료 처리합니다.

경로 변수

필드	형식	설명
`orderId*`	`12자리 숫자`	스토어에 속한 주문 ID입니다. orderNumber에서 #을 제외한 값과 같습니다.
`refundId*`	`UUID`	cashRefund.id에 반환된 계좌 환불 요청 ID입니다.

요청 본문

필드	형식	설명
`confirmedAmount*`	`integer`	실제로 송금한 금액. 환불 요청 금액과 정확히 같아야 합니다.
`transferReference*`	`string`	은행 이체내역을 확인할 식별정보. 1~160자이며 제어문자는 허용하지 않습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/orders/202607190001/refunds/6682e43e-8866-4691-b13f-58d53ca49965/complete" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "confirmedAmount": 12000,
  "transferReference": "bank-transfer-20261101-001",
  "reason": "판매자 송금 완료 확인"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

환불 id, 금액, status: completed와 completedAt을 반환합니다. 은행 송금을 실행하거나 검증한 결과가 아니라 판매자 측 완료 기록입니다.

별도의 write:refund_completion 권한이 필요합니다. 다른 주문의 환불 ID나 잘못된 금액은 거절합니다. 같은 키·같은 본문은 재응답하고 다른 송금 정보로 완료를 덮어쓸 수 없습니다.

상품·재고

설명

대시보드에서 연결한 외부 지급 서버의 실행 설정을 조회합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/fulfillment-settings" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

id, fulfillmentMode, status, timeoutMs, maxAttempts를 반환합니다. 서버 주소·인증값·callback Secret은 포함하지 않습니다.

설명

이미 연결된 외부 지급의 활성 상태·실행 모드·제한 시간·재시도 한도를 변경합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

요청 본문

필드	형식	설명
`settings*`	`object`	status(active/disabled), fulfillmentMode(local_inventory/api_delivery/hybrid), timeoutMs(500~10,000), maxAttempts(1~10) 중 변경할 값만 보내세요.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/fulfillment-settings" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "settings": {
    "maxAttempts": 3,
    "timeoutMs": 5000
  },
  "reason": "외부 지급 재시도 조정"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경 후 설정을 반환합니다. 기존 진행 중인 요청의 주소·인증값 스냅샷은 변경하지 않습니다.

외부 주소·인증값 설정과 서명 키 회전은 대시보드의 전용 절차를 유지합니다. 다른 상품에 설정을 생성하거나 인증 누락 상태로 활성화할 수 없습니다.

설명

외부 카탈로그나 ERP에서 상품 기본 정보를 동기화합니다.

쿼리 파라미터

필드	형식	설명
`cursor`	`string`	이전 응답의 pageInfo.nextCursor. 첫 요청에서는 보내지 않습니다.
`limit`	`integer`	한 번에 받을 개수. 기본값 30, 최댓값 100입니다.
`search`	`string`	최대 160자 검색어. 리소스에 따라 ID, 이름 또는 본문을 검색합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/products" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

items에 가격, 할인, 재고 요약, 지급 방식, 최소 구매등급, 공개 상태와 optionGroupCount를 반환합니다.

설명

상품의 기본 정보와 실제 옵션 그룹·옵션 값을 함께 조회합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

상품 객체에 optionGroups가 추가됩니다. 각 그룹은 inputType, required, 상위 옵션 의존 관계와 values(id, name, priceDelta)를 포함합니다.

설명

재고를 추가·삭제하기 전후에 상품과 옵션 조합별 가용 수량을 확인합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/inventory/summary" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

productId, availableDeliveryItemCount와 options 배열을 반환합니다. options에는 combinationKey, label, quantity, unlimited, paused가 있습니다.

실제 재고 원문은 반환하지 않습니다.
별칭 /products/{productId}/inventory도 지원합니다.

설명

Quartz Vend가 직접 지급할 재고 원문을 상품 또는 지정한 옵션 조합에 추가합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

요청 본문

필드	형식	설명
`items*`	`string[]`	추가하거나 삭제할 실제 지급 재고. 1~1,000개이며 한 요청 안에서 중복될 수 없습니다.
`optionCombinationKey`	`string`	상품 경로에서 특정 옵션 조합 재고를 다룰 때 사용합니다. 옵션 전용 경로에서는 보내지 않습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/inventory/append" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "items": [
    "LICENSE-KEY-001",
    "LICENSE-KEY-002"
  ],
  "reason": "ERP 입고 2026-08-04"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

batch에 requestedCount, acceptedCount, duplicateCount와 batchId를 반환하고 inventory에 반영 후 수량을 반환합니다.

이미 존재하는 재고 값은 중복으로 세지 않으며 duplicateCount에 포함됩니다.
API 전용 지급 상품은 hybrid 모드가 아니면 로컬 재고를 추가할 수 없습니다.

설명

옵션 조합 재고 ID를 알고 있을 때 해당 조합에 지급 재고를 추가합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.
`optionItemId*`	`12자리 숫자`	상품 옵션 조합 재고의 ID입니다. 옵션 값 ID가 아닙니다.

요청 본문

필드	형식	설명
`items*`	`string[]`	추가하거나 삭제할 실제 지급 재고. 1~1,000개이며 한 요청 안에서 중복될 수 없습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/options/202607190004/inventory/append" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "items": [
    "OPTION-KEY-001"
  ],
  "reason": "옵션 재고 입고"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

상품 재고 추가와 같은 batch 및 inventory 구조를 반환합니다.

설명

삭제할 실제 재고 문자열을 이미 알고 있을 때 그 값만 폐기합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.

요청 본문

필드	형식	설명
`items*`	`string[]`	추가하거나 삭제할 실제 지급 재고. 1~1,000개이며 한 요청 안에서 중복될 수 없습니다.
`optionCombinationKey`	`string`	상품 경로에서 특정 옵션 조합 재고를 다룰 때 사용합니다. 옵션 전용 경로에서는 보내지 않습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/inventory/remove" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "items": [
    "LICENSE-KEY-001"
  ],
  "reason": "공급사에서 키 폐기 요청"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

removal에 requestedCount, removedCount, notFoundCount, optionScope를 반환하고 inventory에 반영 후 수량을 반환합니다.

일치하는 미판매 재고만 삭제합니다. 판매된 재고는 삭제 대상이 아닙니다.
items 대신 단일 item 필드도 지원하지만 새 연동에서는 items 배열을 사용하세요.

설명

특정 옵션 조합에서 알고 있는 실제 재고 값만 폐기합니다.

경로 변수

필드	형식	설명
`productId*`	`12자리 숫자`	스토어에 속하며 삭제되지 않은 상품 ID입니다.
`optionItemId*`	`12자리 숫자`	상품 옵션 조합 재고의 ID입니다. 옵션 값 ID가 아닙니다.

요청 본문

필드	형식	설명
`items*`	`string[]`	추가하거나 삭제할 실제 지급 재고. 1~1,000개이며 한 요청 안에서 중복될 수 없습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/products/202607190003/options/202607190004/inventory/remove" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "items": [
    "OPTION-KEY-001"
  ],
  "reason": "잘못 등록된 재고 제거"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

상품 재고 삭제와 같은 removal 및 inventory 구조를 반환합니다.

후기

설명

후기 관리 화면이나 외부 분석 시스템에서 후기를 동기화할 때 호출합니다.

쿼리 파라미터

필드	형식	설명
`cursor`	`string`	이전 응답의 pageInfo.nextCursor. 첫 요청에서는 보내지 않습니다.
`limit`	`integer`	한 번에 받을 개수. 기본값 30, 최댓값 100입니다.
`search`	`string`	최대 160자 검색어. 리소스에 따라 ID, 이름 또는 본문을 검색합니다.
`rating`	`1~5`	별점이 정확히 일치하는 후기만 조회합니다.
`productId`	`12자리 숫자`	특정 상품 후기만 조회합니다.
`visible`	`true \| false`	문자열 true는 공개 후기, false는 숨김·삭제 후기를 조회합니다.
`from`	`RFC 3339`	이 시각 이후 작성된 후기만 조회합니다.
`to`	`RFC 3339`	이 시각까지 작성된 후기만 조회합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/reviews" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

items에 후기 ID, 상품·주문·작성자, 별점, 내용, 이미지, 판매자 답글, 공개 여부와 시각을 반환합니다.

설명

특정 후기의 현재 내용과 판매자 답글을 확인합니다.

경로 변수

필드	형식	설명
`reviewId*`	`12자리 숫자`	스토어에 속한 후기 ID입니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/reviews/202607190005" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

후기 목록 item과 같은 후기 객체를 반환합니다.

쿠폰

설명

외부 프로모션 도구에서 쿠폰과 사용량을 동기화합니다.

쿼리 파라미터

필드	형식	설명
`cursor`	`string`	이전 응답의 pageInfo.nextCursor. 첫 요청에서는 보내지 않습니다.
`limit`	`integer`	한 번에 받을 개수. 기본값 30, 최댓값 100입니다.
`search`	`string`	최대 160자 검색어. 리소스에 따라 ID, 이름 또는 본문을 검색합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/coupons" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

items에 코드, 할인 조건, 제외 상품, 사용 한도·횟수, 상태와 적용 기간을 반환합니다.

설명

외부 캠페인에서 사용할 스토어 쿠폰을 생성합니다.

요청 본문

필드	형식	설명
`code*`	`string`	쿠폰 코드. 최대 64자이며 저장 시 대문자로 정규화됩니다.
`name*`	`string`	관리용 쿠폰 이름. 최대 120자입니다.
`discountType*`	`amount \| percent`	정액 할인은 amount, 정률 할인은 percent입니다.
`discountAmount`	`정수 문자열`	amount일 때 1 이상. percent일 때는 0으로 둡니다.
`discountBps`	`integer`	percent일 때 1~10,000. 1,000은 10%입니다.
`minimumOrderAmount`	`정수 문자열`	최소 주문 금액. 0이면 제한하지 않습니다.
`maximumOrderAmount`	`정수 문자열`	최대 주문 금액. 0이면 제한하지 않습니다.
`maximumDiscountAmount`	`정수 문자열`	정률 할인 상한. 0이면 제한하지 않습니다.
`excludedProductIds`	`string[]`	할인에서 제외할 이 스토어의 상품 ID. 최대 500개입니다.
`stackable`	`boolean`	다른 할인과 중복 적용할지 여부. 기본값 false입니다.
`firstPurchaseOnly`	`boolean`	첫 구매 전용 여부. 기본값 false입니다.
`maxRedemptions`	`integer`	전체 사용 한도. 0이면 제한하지 않습니다.
`startsAt`	`RFC 3339 \| null`	사용 시작 일시. null이면 즉시 사용할 수 있습니다.
`expiresAt`	`RFC 3339 \| null`	만료 일시. startsAt보다 뒤여야 합니다.
`status`	`active \| disabled`	생성 또는 수정 후 상태. 기본값 active입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/coupons" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "code": "WELCOME10",
  "name": "첫 구매 10%",
  "discountType": "percent",
  "discountAmount": "0",
  "discountBps": 1000,
  "minimumOrderAmount": "10000",
  "maximumOrderAmount": "0",
  "maximumDiscountAmount": "5000",
  "excludedProductIds": [],
  "stackable": false,
  "firstPurchaseOnly": true,
  "maxRedemptions": 100,
  "startsAt": "2026-08-04T00:00:00+09:00",
  "expiresAt": "2026-08-31T23:59:59+09:00",
  "status": "active",
  "reason": "8월 신규 고객 캠페인"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

201로 couponId와 대문자로 정규화된 code를 반환합니다.

같은 스토어에서 이미 사용 중인 코드는 409입니다.

설명

쿠폰 이름, 기간, 상태 또는 아직 잠기지 않은 혜택 조건을 수정합니다.

경로 변수

필드	형식	설명
`couponId*`	`12자리 숫자`	스토어에 속한 쿠폰 ID입니다.

요청 본문

필드	형식	설명
`code*`	`string`	쿠폰 코드. 최대 64자이며 저장 시 대문자로 정규화됩니다.
`name*`	`string`	관리용 쿠폰 이름. 최대 120자입니다.
`discountType*`	`amount \| percent`	정액 할인은 amount, 정률 할인은 percent입니다.
`discountAmount`	`정수 문자열`	amount일 때 1 이상. percent일 때는 0으로 둡니다.
`discountBps`	`integer`	percent일 때 1~10,000. 1,000은 10%입니다.
`minimumOrderAmount`	`정수 문자열`	최소 주문 금액. 0이면 제한하지 않습니다.
`maximumOrderAmount`	`정수 문자열`	최대 주문 금액. 0이면 제한하지 않습니다.
`maximumDiscountAmount`	`정수 문자열`	정률 할인 상한. 0이면 제한하지 않습니다.
`excludedProductIds`	`string[]`	할인에서 제외할 이 스토어의 상품 ID. 최대 500개입니다.
`stackable`	`boolean`	다른 할인과 중복 적용할지 여부. 기본값 false입니다.
`firstPurchaseOnly`	`boolean`	첫 구매 전용 여부. 기본값 false입니다.
`maxRedemptions`	`integer`	전체 사용 한도. 0이면 제한하지 않습니다.
`startsAt`	`RFC 3339 \| null`	사용 시작 일시. null이면 즉시 사용할 수 있습니다.
`expiresAt`	`RFC 3339 \| null`	만료 일시. startsAt보다 뒤여야 합니다.
`status`	`active \| disabled`	생성 또는 수정 후 상태. 기본값 active입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/coupons/202607190006" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

couponId와 정규화된 code를 반환합니다.

한 번이라도 사용된 쿠폰은 코드, 할인 방식·금액, 주문 금액 조건, 중복 사용, 첫 구매 전용, 사용 한도를 바꿀 수 없습니다. 새 쿠폰을 생성하세요.

설명

쿠폰을 더 이상 적용할 수 없게 즉시 비활성화합니다.

경로 변수

필드	형식	설명
`couponId*`	`12자리 숫자`	스토어에 속한 쿠폰 ID입니다.

요청 본문

필드	형식	설명
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/coupons/202607190006/disable" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "reason": "프로모션 조기 종료"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

couponId와 status(disabled)를 반환합니다.

일반 설정

설명

변경하기 전 현재 API 관리 대상 설정을 읽어요.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/settings" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

name, description, purchasedProductAccessDaysDefault, discordLinkRequired, searchEngineVisible, searchRobotsText, searchSitemapXml, socialLinks를 반환합니다. 결제 계좌·비밀정보는 포함하지 않습니다.

설명

스토어 이름·소개·기본 열람기간·검색 노출·소셜 링크를 변경합니다.

요청 본문

필드	형식	설명
`settings*`	`object`	GET /settings의 필드 중 변경할 값만 보내세요. 미전송 필드는 그대로 유지합니다. 빈 객체·지원하지 않는 필드는 거절합니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/settings" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "settings": {
    "name": "테스트 스토어",
    "searchEngineVisible": false
  },
  "reason": "운영 설정 변경"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경 후의 일반 설정을 반환하고 감사로그에 API 키와 사유를 기록합니다.

주소·이미지 업로드·소유권·입금계좌 변경은 기존 대시보드의 별도 검증 절차를 유지합니다. 이 API로 해당 값을 우회 변경할 수 없습니다.
socialLinks는 Discord·Telegram·YouTube·Kakao 주소를 지원하며 플랜 권한과 URL 검사를 적용합니다.

보안

설명

보안 플래그와 현재 신뢰 이메일 도메인을 읽어요.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/security" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

대시보드와 같은 settings, trustedEmailDomains를 반환합니다. 조회 scope도 store.security.manage 권한이 있어야 발급할 수 있습니다.

설명

네트워크·이메일 제한 및 MFA 설정을 대시보드와 같은 검사로 변경합니다.

요청 본문

필드	형식	설명
`settings*`	`object`	restrictToKoreanTelecomNetworks, blockMobileData, blockIpv6, blockForeignAccess, blockUntrustedEmailDomain, blockUntrustedEmailDomainForPurchase, blockUntrustedEmailDomainForTopup, requireMfaForPurchase, requireMfaForStoreAdmin을 boolean으로 모두 보내세요. requireMfaForTopup은 선택값입니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/security" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경 후 보안 설정·신뢰 도메인과 감사·보안 이벤트를 같은 트랜잭션에서 저장합니다. 민감 변경에 대한 재인증 필수 정책 자체는 해제할 수 없습니다.

설명

스토어에서 허용할 이메일 도메인을 추가합니다.

요청 본문

필드	형식	설명
`domain*`	`string`	이메일 주소가 아닌 도메인. 대시보드와 같은 정규화·한도 검사를 적용합니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/security/trusted-email-domains" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "domain": "partner.example",
  "reason": "협력사 도메인 허용"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경 후 보안 설정과 신뢰 이메일 도메인 목록을 반환합니다.

설명

이전에 추가한 신뢰 이메일 도메인을 제거합니다.

요청 본문

필드	형식	설명
`domain*`	`string`	제거할 도메인. 보호된 기본 도메인은 제거할 수 없습니다.
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/security/trusted-email-domains/remove" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

변경 후 보안 설정과 신뢰 이메일 도메인 목록을 반환합니다.

Webhook

설명

현재 Endpoint 설정과 최근 성공·실패 상태를 점검합니다.

cURL

curl "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints" \
  --header "Authorization: Bearer $QUARTZ_API_KEY"

성공 응답의 data

최대 100개의 endpoints를 반환합니다. URL, 이벤트, 필터, 필드 정책, Secret prefix, 상태, 실패 횟수와 최근 결과 시각이 포함되며 Secret 원문은 포함되지 않습니다.

설명

Quartz Vend가 이벤트를 POST할 수신 서버를 등록합니다.

요청 본문

필드	형식	설명
`url*`	`HTTPS URL`	이벤트를 받을 공개 URL. 운영 환경에서는 사설 IP, localhost, URL 사용자 정보와 fragment를 허용하지 않습니다.
`description`	`string`	Endpoint를 구분할 설명. 최대 120자입니다.
`events`	`string[]`	구독할 canonical 이벤트 이름. 한 개 이상 필요합니다.
`filters`	`object`	payload 필드와 값으로 거르는 조건. 최대 20개이며 값은 문자열 또는 문자열 배열입니다.
`customHeaders`	`object`	수신 서버 식별용 고정 헤더. 최대 10개입니다. Authorization, Cookie와 Quartz 서명 헤더는 사용할 수 없습니다.
`allowFields`	`string[]`	data에서 전달을 허용할 객체 경로. 비어 있으면 안전 처리된 전체 data가 대상입니다.
`anonymizeFields`	`string[]`	최종 payload에서 제거할 data 경로. 배열에는 *를 사용할 수 있습니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://merchant.example.com/webhooks/quartz",
  "description": "주문 지급 서버",
  "events": [
    "store.order.fulfillment_pending",
    "store.order.fulfilled"
  ],
  "filters": {},
  "customHeaders": {
    "X-Merchant-System": "fulfillment-v2"
  },
  "allowFields": [],
  "anonymizeFields": [
    "data.content",
    "data.images"
  ]
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

201로 endpointId와 signingSecret을 반환합니다. signingSecret 원문은 이 응답에서만 확인할 수 있습니다.

운영 등록 시 DNS 결과까지 검사하여 사설·예약 IP와 메타데이터 주소를 거부합니다.
스토어당 활성 Endpoint는 최대 20개입니다.

설명

URL, 구독 이벤트, 필터, custom header, payload 정책 또는 활성 상태를 교체합니다.

경로 변수

필드	형식	설명
`endpointId*`	`12자리 숫자`	Webhook Endpoint ID입니다.

요청 본문

필드	형식	설명
`url*`	`HTTPS URL`	이벤트를 받을 공개 URL. 운영 환경에서는 사설 IP, localhost, URL 사용자 정보와 fragment를 허용하지 않습니다.
`description`	`string`	Endpoint를 구분할 설명. 최대 120자입니다.
`events`	`string[]`	구독할 canonical 이벤트 이름. 한 개 이상 필요합니다.
`filters`	`object`	payload 필드와 값으로 거르는 조건. 최대 20개이며 값은 문자열 또는 문자열 배열입니다.
`customHeaders`	`object`	수신 서버 식별용 고정 헤더. 최대 10개입니다. Authorization, Cookie와 Quartz 서명 헤더는 사용할 수 없습니다.
`allowFields`	`string[]`	data에서 전달을 허용할 객체 경로. 비어 있으면 안전 처리된 전체 data가 대상입니다.
`anonymizeFields`	`string[]`	최종 payload에서 제거할 data 경로. 배열에는 *를 사용할 수 있습니다.
`status`	`active \| disabled`	Endpoint 상태. 기본값 active입니다.

cURL

curl --request PATCH "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints/202607190007" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

endpointId와 반영된 status를 반환합니다.

customHeaders를 생략하면 기존 암호화 값을 유지합니다. 빈 객체를 보내면 제거됩니다.

설명

Secret 유출이 의심되거나 정기 교체할 때 새 Secret을 발급합니다.

경로 변수

필드	형식	설명
`endpointId*`	`12자리 숫자`	Webhook Endpoint ID입니다.

요청 본문

요청 본문 없이 전송합니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints/202607190007/rotate-secret" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

endpointId와 새 signingSecret을 반환합니다. 새 원문은 이 응답에서만 확인할 수 있습니다.

요청 본문은 필요하지 않습니다. Idempotency-Key를 함께 보냅니다.

설명

활성 Endpoint로 webhook.test 이벤트를 큐에 넣어 수신과 서명 검증을 확인합니다.

경로 변수

필드	형식	설명
`endpointId*`	`12자리 숫자`	Webhook Endpoint ID입니다.

요청 본문

요청 본문 없이 전송합니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints/202607190007/test" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

eventId와 status(queued)를 반환합니다. 이 응답은 상대 서버가 수신했다는 뜻이 아니라 전송 큐 등록 완료를 뜻합니다.

실제 성공 여부는 Webhook 전송 로그에서 확인합니다.

설명

전송을 일시 중지합니다. 목록에는 유지되며 수정 API에서 status를 active로 보내면 다시 사용할 수 있습니다.

경로 변수

필드	형식	설명
`endpointId*`	`12자리 숫자`	Webhook Endpoint ID입니다.

요청 본문

필드	형식	설명
`reason*`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request POST "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints/202607190007/disable" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "reason": "수신 서버 점검"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

endpointId와 status(disabled)를 반환합니다.

설명

Endpoint를 목록에서 삭제하고 대기 중인 전송을 취소합니다. 삭제한 Endpoint는 다시 사용할 수 없습니다.

경로 변수

필드	형식	설명
`endpointId*`	`12자리 숫자`	Webhook Endpoint ID입니다.

요청 본문

필드	형식	설명
`reason`	`string`	감사로그에 남길 변경 사유입니다. 1~1,000자입니다.

cURL

curl --request DELETE "https://api.quartz-vend.com/v1/open/stores/202603290001/webhook-endpoints/202607190007" \
  --header "Authorization: Bearer $QUARTZ_API_KEY" \
  --header "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "reason": "연동 종료"
}'

YOUR_UNIQUE_REQUEST_ID는 작업별 고유한 값으로 바꿉니다. 같은 작업을 재시도할 때는 이 값을 유지합니다.

성공 응답의 data

endpointId와 deleted(true)를 반환합니다. 기존 전송 이력은 보존됩니다.

응답과 오류

결과는 data에 들어 있습니다. 목록의 다음 페이지는 pageInfo.nextCursor를 cursor로 전달해 조회합니다. 아래는 주문이 없는 경우의 응답입니다.

주문 목록 응답

{
  "success": true,
  "data": {
    "items": [],
    "pageInfo": {
      "hasNextPage": false,
      "limit": 30,
      "nextCursor": null
    }
  },
  "requestId": "48441b71-41e4-4202-a467-a2fa0309c46f"
}

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "OPENAPI_CURSOR_INVALID",
    "message": "Open API cursor is invalid."
  },
  "requestId": "ec018c1f-b2b5-49f1-a687-233f6a201ad6"
}

오류는 error.code로 확인합니다. 문의할 때 requestId를 함께 전달하면 요청을 찾을 수 있습니다.

상태	확인할 내용
400	필수 값과 입력 형식
401	API 키의 만료·폐기 여부
403	키의 권한과 스토어 이용 상태
404	조회할 대상의 ID
409	이미 처리했거나 다른 요청과 충돌한 작업
429	요청이 많습니다. Retry-After에 안내된 시간 뒤 재시도
5xx	일시적인 서버 오류

중복 요청 방지

정보를 변경하는 요청에는 Idempotency-Key를 함께 보냅니다. 같은 작업을 다시 보낼 때는 같은 키와 내용을 사용합니다. 새 작업에는 새 키를 사용합니다. 응답이 늦거나 끊겨도 키를 바꿔서 다시 보내지 않습니다.

Idempotency-Key는 최대 128자입니다. 목록은 한 번에 기본 30개, 최대 100개를 조회할 수 있습니다. 요청 한도는 키·IP당 분당 300회, 스토어당 분당 1,000회입니다.

Open API

첫 요청

API 키

Node.js

사용 권한

사용자

주문·지급

환불

상품·재고

후기

쿠폰

일반 설정

보안

Webhook

API 참조

사용자

GET/users사용자 목록read:user

GET/users/{userId}사용자 상세read:user

PATCH/users/{userId}/profile관리자 메모 수정write:user_profile

POST/users/{userId}/balance-adjustments구매 잔액 조정write:user_balance

POST/users/{userId}/point-adjustments스토어 포인트 조정write:user_point

PATCH/users/{userId}/blacklist스토어 이용 차단write:user_blacklist

POST/users/{userId}/grade-overrides구매등급 지정write:user_grade

주문·지급

GET/orders주문 목록read:order

GET/orders/{orderId}주문 상세read:order

POST/orders/{orderId}/fulfillmentsAPI 수량별 지급write:order_fulfillment

GET/orders/{orderId}/fulfillment수량별 지급 상태read:order

POST/orders/{orderId}/exchanges수량별 교환write:order_exchange

환불

POST/orders/{orderId}/refunds수량별 환불 요청write:order_refund

GET/orders/{orderId}/refunds환불 내역과 송금 상태read:order

POST/orders/{orderId}/refunds/{refundId}/complete송금 완료 기록write:refund_completion

상품·재고

GET/products/{productId}/fulfillment-settings외부 지급 실행 설정 조회read:product

PATCH/products/{productId}/fulfillment-settings외부 지급 실행 설정 변경write:product_fulfillment

GET/products상품 목록read:product

GET/products/{productId}상품 상세read:product

GET/products/{productId}/inventory/summary재고 수량read:inventory

POST/products/{productId}/inventory/append상품 재고 추가write:inventory

POST/products/{productId}/options/{optionItemId}/inventory/append옵션 재고 추가write:inventory

POST/products/{productId}/inventory/remove알고 있는 재고 삭제write:inventory

POST/products/{productId}/options/{optionItemId}/inventory/remove알고 있는 옵션 재고 삭제write:inventory

후기

GET/reviews후기 목록read:review

GET/reviews/{reviewId}후기 상세read:review

쿠폰

GET/coupons쿠폰 목록read:coupon

POST/coupons쿠폰 생성write:coupon

PATCH/coupons/{couponId}쿠폰 수정write:coupon