Skip to Content
API v1.7.0 Released - Settlement order number query + partial shipment support
API ReferenceCommon

공통 규격

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

요청 형식

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

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

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

응답 형식

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

필드타입설명
request_idstring요청 추적 ID (문의 시 사용)
timestampstring응답 시간 (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-Idreq_m5k2a1_x7f3p9요청 추적 ID

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

날짜 형식

용도형식예시
요청 파라미터YYYY-MM-DD2026-01-22
응답 필드 (timestamp)ISO 86012026-01-22T15:30:00.000Z
응답 필드 (date)YYYY-MM-DD2026-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의 인덱스는 데이터베이스에 저장된 원본 값을 그대로 반환합니다. 자사제품이 제외되어 일부 품목만 반환되더라도 인덱스가 재정렬되지 않습니다.

세트 구성품 번호 (v1.9.0)

입점사 재고가 몰 품목 하나를 여러 품목(세트 구성품)으로 나눠 관리하는 경우, 주문품목번호 뒤에 구성품 꼬리 ^s{n}(n = 1~4자리 숫자)을 붙여 보낼 수 있습니다.

{bright_order_no}_[{index}]^s{n}

예시: 202610301742_000028212_[1]^s3 → 몰 주문품목 202610301742_000028212_[1] 의 구성품 3

항목규칙
쓸 수 있는 API재고 확인(POST) · 재고 확정(PUT) · 배송 등록 · 배송 수정 · 상태 변경
적용 대상꼬리를 뗀 몰 주문품목 한 줄. 주문·입점사 확인은 몰 번호로 똑같이 합니다
한 요청 안의 같은 품목 구성품한 품목으로 처리합니다. 값이 모두 같아야 합니다 — 재고 확인 stock_available / 배송 등록 carrier_code·tracking_number / 배송 수정 보낸 carrier_code·tracking_number / 상태 변경 status
값이 서로 다르면그 품목의 구성품 전부 SUB_ITEM_CONFLICT 로 실패하고 품목은 바뀌지 않습니다. 같은 요청의 다른 품목은 그대로 처리됩니다
구성품의 supply_price몰 판매단위 단가가 아니므로 품목 공급가에 반영하지 않습니다. 받은 값은 품목에 검토용으로 기록되고, 품목 공급가는 몰 공급가를 유지합니다. 구성품 하나라도 형식이 틀리면(합계 ≠ 단가 × 수량) 그 품목 전체가 INVALID_SUPPLY_PRICE 입니다
응답보낸 번호마다 한 건씩(ord_prd_no = 보낸 번호 그대로) + base_ord_prd_no = 몰 주문품목번호
권장한 품목의 구성품은 한 요청에 모두 보내 주세요. 몰 판매단위 공급가를 계산할 수 있으면 꼬리 없는 몰 번호로 보내는 것이 가장 정확합니다

꼬리 규칙은 모든 입점사에 같습니다. 위 API 밖(취소 요청·반품 등)은 꼬리 없는 몰 번호만 받습니다.

supply_price 공통 스키마

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

필드타입필수설명검증 규칙
unit_pricenumberO몰 판매단위 1개당 공급가 (입점사 납품가)0 이상
quantitynumberO몰 주문 수량 (몰 판매단위)1 이상, 정수
total_amountnumberO총 공급가0 이상, unit_price x quantity 와 같아야 함 (다르면 INVALID_SUPPLY_PRICE)
{
  "supply_price": {
    "unit_price": 75000,
    "quantity": 2,
    "total_amount": 150000
  }
}

수량·단가 기준 (v1.9.0)

  • quantity 는 몰에서 주문된 수량(몰 판매단위) 입니다. 묶음 상품도 낱개 수로 바꾸지 마세요. 부분 취소가 있으면 취소분을 뺀 수량입니다.
    • 예: 「신규환자 접수증 10묶음」 3개 주문 → quantity: 3, unit_price: 7000(1묶음 공급가), total_amount: 21000
  • unit_price 는 몰 판매단위 1개 기준입니다. 낱개 단가를 보내면 몰 공급 금액이 틀어집니다.
  • quantity 가 몰 주문 수량과 달라도 거절하지 않습니다. 몰 공급 금액은 항상 몰 주문 수량 x unit_price 이고, 보낸 수량은 품목에 기록되어 응답에 quantity_mismatch: { "expected": 몰 수량, "received": 보낸 수량 } 으로 표시됩니다.
    • 예: 위 주문에 quantity: 30, unit_price: 7000, total_amount: 210000 을 보내면 처리는 되고, 몰 금액은 7000 x 3 = 21,000원, 응답에 quantity_mismatch: { "expected": 3, "received": 30 }
  • total_amount 는 unit_price x quantity 와 같아야 합니다(0.01 이내). 다르면 그 항목이 INVALID_SUPPLY_PRICE 로 실패하고 처리되지 않습니다.
  • 세트 구성품 번호(^s{n})로 보낸 supply_price 는 검토용으로만 기록합니다.
  • 공급가 변경 이력은 시스템에서 자동으로 추적됩니다 (최대 10건).

실패한 항목: 일괄 API 에서 success: false 인 항목은 처리되지 않습니다(그 품목의 상태·공급가·송장이 바뀌지 않음). error_code 를 확인해 고친 뒤 그 항목을 다시 보내 주세요. 같은 요청의 다른 항목은 그대로 처리됩니다(HTTP 207).

Pagination 응답 형식

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

필드타입설명
pagenumber현재 페이지 번호
limitnumber페이지당 항목 수
totalnumber전체 항목 수
has_moreboolean다음 페이지 존재 여부
{
  "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"
    }
  }
}

권장 처리 방법

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