공통 규격

Brightmall Vendor API의 모든 엔드포인트에 공통으로 적용되는 규격입니다.

요청 형식

Content-Type: application/json
Method: 모든 조회 API는 POST, 수정 API는 PUT

모든 API 요청에는 아래 두 개의 인증 헤더가 필수입니다.

Header	설명	예시
`X-Vendor-Api-Key`	발급받은 API Key	`bm_xOpGAqgHbJQBXxBBbUIZ_...`
`X-Vendor-Id`	입점사 고유 ID (ULID)	`01KC51ST1WSTAET481SHPH3PSY`

응답 형식

모든 JSON 응답에는 아래 필드가 포함됩니다.

필드	타입	설명
`request_id`	string	요청 추적 ID (문의 시 사용)
`timestamp`	string	응답 시간 (ISO 8601)

예외: 거래명세서 PDF API(POST /vendor-api/settlements/transaction-statement)는 바이너리 파일을 직접 반환하므로 request_id와 timestamp가 응답 본문에 포함되지 않습니다. 에러 발생 시에만 JSON 에러 응답이 반환됩니다.

X-Request-Id 응답 헤더

모든 API 응답에는 X-Request-Id HTTP 헤더가 포함됩니다. 이 값은 응답 본문의 request_id와 동일합니다.

응답 헤더	값 예시	설명
`X-Request-Id`	`req_m5k2a1_x7f3p9`	요청 추적 ID

API 호출 관련 문의 시 X-Request-Id 헤더 값 또는 응답 본문의 request_id를 함께 전달해주시면 신속한 원인 파악이 가능합니다.

날짜 형식

용도	형식	예시
요청 파라미터	`YYYY-MM-DD`	`2026-01-22`
응답 필드 (timestamp)	ISO 8601	`2026-01-22T15:30:00.000Z`
응답 필드 (date)	`YYYY-MM-DD`	`2026-01-22`

응답의 날짜 필드는 두 가지 형식이 사용됩니다.

timestamp 형식 (ISO 8601): 정확한 시각이 필요한 필드 (예: timestamp, ord_date, pay_date)

date 형식 (YYYY-MM-DD): 일자만 필요한 필드 (예: cancel_date, return_date, exchange_date)

주문번호와 주문품목번호

주문번호 (ord_no)

주문 단위의 고유 식별자입니다. 거래명세서 조회 시 권장하는 조회 키입니다.


{bright_order_no}

예시: 202601220157_000020196

주문품목번호 (ord_prd_no)

품목 단위의 고유 식별자입니다. 배송 등록/수정, 상태 변경 API에서 사용합니다.


{bright_order_no}_[{index}]

예시: 202601220157_000020196_[1]

202601220157_000020196: 주문번호 (bright_order_no = ord_no)
[1]: 해당 주문 내 품목 인덱스

ord_prd_no의 인덱스는 데이터베이스에 저장된 원본 값을 그대로 반환합니다. 자사제품이 제외되어 일부 품목만 반환되더라도 인덱스가 재정렬되지 않습니다.

supply_price 공통 스키마

모든 API에서 공급가 입력 시 동일한 형식을 사용합니다.

필드	타입	필수	설명	검증 규칙
`unit_price`	number	O	공급 단가 (입점사 납품가)	0 이상
`quantity`	number	O	수량	1 이상, 정수
`total_amount`	number	O	총 공급가	0 이상, unit_price x quantity 권장


{
  "supply_price": {
    "unit_price": 75000,
    "quantity": 2,
    "total_amount": 150000
  }
}

total_amount는 unit_price x quantity와 일치하는 것이 권장되나, 할인 등의 사유로 다를 수 있습니다. 공급가 변경 이력은 시스템에서 자동으로 추적됩니다 (최대 10건).

Pagination 응답 형식

모든 목록 조회 API의 응답에는 pagination 객체가 포함됩니다.

필드	타입	설명
`page`	number	현재 페이지 번호
`limit`	number	페이지당 항목 수
`total`	number	전체 항목 수
`has_more`	boolean	다음 페이지 존재 여부


{
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 245,
    "has_more": true
  }
}

has_more가 true이면 page를 증가시켜 다음 페이지를 조회하세요.

Rate Limit (요청 제한)

API 요청은 분당 횟수로 제한됩니다.

항목	값
제한	분당 100회
적용 범위	API Key 기준
초과 시 응답	HTTP 429

Rate Limit 응답 헤더

Rate Limit 초과 시 아래 헤더가 응답에 포함됩니다.

헤더	설명	예시
`X-RateLimit-Limit`	분당 최대 요청 수	`100`
`X-RateLimit-Remaining`	남은 요청 수	`0`
`X-RateLimit-Reset`	제한 초기화 시간 (Unix timestamp)	`1706529660`
`Retry-After`	재시도 가능 시간 (초)	`45`

Rate Limit 초과 응답 예시


{
  "success": false,
  "request_id": "req_mkp3rate_xyz123",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 45 seconds.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2026-01-30T10:41:00.000Z"
    }
  }
}

권장 처리 방법

Retry-After 헤더 확인: 응답의 Retry-After 값(초)만큼 대기 후 재시도
지수 백오프 (Exponential Backoff): 연속 실패 시 대기 시간을 2배씩 증가 (최대 60초)
요청 분산: 대량 처리 시 요청을 분산하여 Rate Limit 내에서 처리