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

모범 사례

브라이트몰 Vendor API를 안정적으로 연동하기 위한 실전 가이드입니다.

Rate Limit 처리

API 요청은 분당 100회(API Key 기준)로 제한됩니다. 제한을 초과하면 HTTP 429 응답이 반환됩니다.

Rate Limit 응답 헤더

429 응답에는 다음 헤더가 포함됩니다.

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

지수 백오프 (Exponential Backoff) 구현

Rate Limit 초과 시 Retry-After 헤더 값만큼 대기 후 재시도합니다. 연속 실패 시 대기 시간을 2배씩 증가시키세요.

async function callWithRetry(apiCall, maxRetries = 5) {
  let delay = 1000; // 초기 대기: 1초
 
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await apiCall();
 
      if (response.status === 429) {
        const retryAfter = response.headers['retry-after'];
        const waitTime = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.min(delay, 60000); // 최대 60초
 
        await sleep(waitTime);
        delay *= 2; // 지수 백오프
        continue;
      }
 
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await sleep(delay);
      delay *= 2;
    }
  }
}

요청 분산

대량 처리 시 요청을 고르게 분산하세요.

  • 한 번에 100건 배치 처리 후 잠시 대기
  • 불필요한 반복 조회를 줄이고, 웹훅으로 이벤트 수신
  • 조회 주기를 최소 1분 이상으로 설정

에러 처리

에러 응답 구조

모든 에러 응답은 동일한 구조를 따릅니다.

{
  "success": false,
  "request_id": "req_mkp3err_123xyz",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order not found: 202601220000_000000000_[1]",
    "details": {
      "ord_prd_no": "202601220000_000000000_[1]"
    }
  }
}

HTTP 상태 코드별 처리

코드설명권장 처리
200성공정상 처리
207부분 성공results 배열에서 개별 성공/실패 확인
400잘못된 요청요청 파라미터 검증 후 재요청
401인증 실패API Key 확인
403권한 없음IP 화이트리스트 확인
404리소스 없음주문번호/품목번호 확인
429Rate Limit 초과지수 백오프 적용
500서버 오류잠시 후 재시도, 지속 시 기술 지원 문의

부분 성공 (HTTP 207) 처리

배치 API(배송 등록, 재고 확인 등)에서 일부 항목만 실패할 수 있습니다.

{
  "success_count": 2,
  "failure_count": 1,
  "results": [
    { "ord_prd_no": "..._[1]", "success": true },
    { "ord_prd_no": "..._[2]", "success": true },
    { "ord_prd_no": "..._[3]", "success": false, "error": "ORDER_NOT_FOUND" }
  ]
}

results 배열을 순회하면서 success: false인 항목만 재처리하세요.

request_id 활용

모든 응답에 포함된 request_id는 문제 발생 시 기술 지원팀에 전달하면 빠른 원인 파악이 가능합니다. X-Request-Id 응답 헤더로도 확인할 수 있습니다.

전체 에러 코드: 에러 코드 목록

멱등성 키 (Idempotency Key)

배송 등록 API에서 idempotency_key를 사용하면 네트워크 오류 등으로 인한 중복 등록을 방지할 수 있습니다.

{
  "shipments": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "carrier_code": "cj",
      "tracking_number": "1234567890",
      "idempotency_key": "shipment_20260122_001"
    }
  ]
}
  • 동일한 idempotency_key로 재요청하면 최초 결과가 반환됩니다
  • 키는 요청 단위로 고유해야 합니다
  • UUID 또는 {날짜}_{순번} 형식을 권장합니다

페이지네이션

목록 조회 API는 페이지네이션을 지원합니다. 모든 데이터를 가져오려면 has_more가 false가 될 때까지 반복 조회하세요.

async function fetchAllOrders(startDate, endDate, status) {
  let page = 1;
  const allOrders = [];
 
  while (true) {
    const response = await fetchOrders({
      start_date: startDate,
      end_date: endDate,
      status: status,
      page: page,
      limit: 100
    });
 
    allOrders.push(...response.order_list);
 
    if (!response.pagination.has_more) break;
    page++;
  }
 
  return allOrders;
}

페이지네이션 응답

{
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 245,
    "has_more": true
  }
}
필드설명
page현재 페이지 번호
limit페이지당 항목 수 (최대 100)
total전체 항목 수
has_more다음 페이지 존재 여부

날짜 형식

요청 시

날짜 파라미터는 YYYY-MM-DD 형식을 사용합니다.

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}
  • start_date는 end_date보다 같거나 이전이어야 합니다
  • 잘못된 범위 지정 시 INVALID_DATE_RANGE 에러가 반환됩니다

응답 시

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

형식예시사용 필드
ISO 8601 (timestamp)2026-01-22T15:30:00.000Ztimestamp, ord_date, pay_date
YYYY-MM-DD (date)2026-01-22cancel_date, return_date, exchange_date

주문번호 체계

주문번호 (ord_no)

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

202601220157_000020196

주문품목번호 (ord_prd_no)

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

202601220157_000020196_[1]
  • 202601220157_000020196: 주문번호 (ord_no)
  • [1]: 주문 내 품목 인덱스

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

자주 묻는 질문

주문 조회 결과가 비어있습니다

정상적인 동작입니다. 조회 조건에 해당하는 주문이 없으면 빈 배열([])이 반환됩니다. HTTP 200 응답이며 에러가 아닙니다.

한 번에 여러 건을 처리할 수 있나요?

배송 등록, 재고 확인, 상태 변경 API는 배열로 최대 100건까지 한 번에 처리할 수 있습니다.

배송 등록 후 바로 배송완료 처리해도 되나요?

가능합니다. 배송 등록 API 호출 후 바로 상태 변경 API로 delivered 처리할 수 있습니다.

재고 확인 API는 필수인가요?

필수는 아닙니다. 다만 다음과 같은 이점이 있습니다:

  • 출고 불가 품목을 사전에 알려 고객 대응 가능
  • 공급가를 사전 등록하여 정산 준비
  • 브라이트몰 시스템과 재고 상태 동기화

공급가를 나중에 수정할 수 있나요?

가능합니다. 배송 수정 API로 공급가를 수정할 수 있으며, 변경 이력은 자동으로 기록됩니다.

자사제품이 주문에 포함되어 있으면 어떻게 되나요?

입점사 API는 인증된 입점사의 품목만 반환합니다. 자사제품(브라이트몰 직접 판매)이나 다른 입점사의 품목은 조회 결과에서 자동으로 제외됩니다. partner_code 필드로 해당 품목의 공급 입점사를 확인할 수 있습니다.

거래명세서 조회 시 SETTLEMENT_NOT_FOUND 에러가 발생합니다

가장 흔한 원인은 공급가가 아직 등록되지 않은 것입니다. 공급가 등록 시 정산이 자동 생성되며, 정산 생성 후에 거래명세서를 조회할 수 있습니다. 자세한 해결 방법은 정산 플로우 - 에러 처리를 참조하세요.

Next Steps

Last updated on
Webhook