주문 처리 플로우

이 가이드에서는 브라이트몰 Vendor API의 주문 처리 전체 생명주기를 설명합니다. 주문 조회부터 재고 확인, 배송 등록, 상태 변경, 거래명세서 발급까지의 흐름을 단계별로 안내합니다.

기본 주문 처리 플로우

주문 처리는 5단계로 구성됩니다.

Step 1. 신규 주문 조회

결제 완료된 주문을 조회하여 처리할 신규 주문을 확인합니다.

POST /vendor-api/orders

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "status": "결제완료"
}

응답의 order_list에서 ord_prd_no(주문품목번호)를 확인합니다. 이 값은 이후 모든 API 호출의 기본 식별자입니다.

입점사 API는 인증된 입점사의 품목만 반환합니다. 브라이트몰 자사제품이나 다른 입점사의 품목은 자동으로 제외됩니다.

API 상세: 주문 조회 API

Step 2. 재고 확인 및 공급가 사전 등록

주문 품목에 대해 재고 가용 여부를 확인하고, 공급가를 사전 등록합니다.

POST /vendor-api/inventory/confirm

{
  "confirmations": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "stock_available": true,
      "supply_price": {
        "unit_price": 75000,
        "quantity": 2,
        "total_amount": 150000
      }
    }
  ]
}

이 단계에서 supply_price를 입력하면 정산이 자동으로 생성됩니다. 정산 생성 후에는 거래명세서를 즉시 조회할 수 있습니다.

재고가 없는 경우 stock_available: false와 unavailable_reason을 설정합니다.

API 상세: 재고 확인 API

Step 2-1. 거래명세서 PDF 다운로드 (선택)

공급가 등록으로 정산이 생성된 후, 출하 전에 거래명세서를 발급받을 수 있습니다.

POST /vendor-api/settlements/transaction-statement

{
  "ord_no": "202601220157_000020196"
}

출하 전이므로 해당 주문의 모든 품목이 거래명세서에 포함됩니다.

API 상세: 거래명세서 PDF API

Step 3. 배송 등록 (송장번호 입력)

택배사 코드와 송장번호를 등록합니다. 배송 등록 시 해당 품목의 출하 상태가 자동으로 shipped로 변경됩니다.

POST /vendor-api/shipment

{
  "shipments": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "carrier_code": "cj",
      "tracking_number": "1234567890"
    }
  ]
}

지원되는 택배사 코드: cj(CJ대한통운), hanjin(한진택배), lotte(롯데택배), logen(로젠택배), epost(우체국택배), kdexp(경동택배), daesin(대신택배), ilyang(일양로지스), other(기타)

API 상세: 배송 등록 API

Step 4. 배송완료 처리

고객이 상품을 수령하면 상태를 delivered로 변경합니다.

POST /vendor-api/orders/status

{
  "updates": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "status": "delivered"
    }
  ]
}

API 상세: 주문 상태 변경 API

간소화된 플로우 (공급가 + 배송 동시 등록)

재고 확인 단계를 생략하고, 배송 등록 시 공급가를 함께 입력하는 간소화 플로우입니다.

Step 1. 주문 조회

POST /vendor-api/orders (status=결제완료)

Step 2. 배송 등록 + 공급가 동시 입력

POST /vendor-api/shipment

{
  "shipments": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "carrier_code": "cj",
      "tracking_number": "1234567890",
      "supply_price": {
        "unit_price": 75000,
        "quantity": 2,
        "total_amount": 150000
      }
    }
  ]
}

supply_price를 포함하면 정산이 자동 생성되고, 출하 상태도 shipped로 변경됩니다.

Step 3. 배송완료 처리

POST /vendor-api/orders/status (status=delivered)

공급가 입력 가능 시점

공급가는 여러 API에서 입력할 수 있습니다. 비즈니스 상황에 맞는 시점에 입력하세요.

공급가를 입력하면 정산이 자동으로 생성됩니다. 이미 정산이 존재하는 경우 공급가만 업데이트되며, 변경 이력은 자동 추적됩니다 (최대 10건).

부분출하 시나리오 (v1.7.0)

하나의 주문에 여러 품목이 있을 때, 일부만 먼저 출하하고 나머지는 나중에 출하하는 부분출하를 지원합니다.

예시: 주문에 3개 품목, 2회 나눠서 출하

1차 출하 전

재고 확인(Step 2)에서 3개 품목 모두 공급가를 등록합니다.

• 3개 품목 모두 출하 상태: pending
• ord_no로 거래명세서 조회 시: 3개 품목 전부 포함

1차 출하 (품목 1, 2만)

배송 등록(Step 3)으로 품목 _[1], _[2]만 출하합니다.

• _[1], _[2] 출하 상태: shipped
• _[3] 출하 상태: pending (미출하)
• ord_no로 거래명세서 조회 시: _[3]만 포함 (미출하 품목만)

2차 출하 (품목 3)

배송 등록으로 품목 _[3]를 출하합니다.

• 모든 품목 출하 상태: shipped
• ord_no로 거래명세서 조회 시: 미출하 품목 없음

부분출하 시 거래명세서 조회 규칙

ord_prd_no로 조회하면 출하 상태와 관계없이 정산의 전체 품목이 반환됩니다 (하위 호환).

부분출하는 배송 등록 API를 분할 호출하는 것만으로 자동 처리됩니다. 별도의 추가 API 호출이 필요하지 않습니다.

취소/반품 주문 처리

취소 및 반품 주문은 별도의 조회 API로 확인할 수 있습니다.

취소 주문 확인

POST /vendor-api/orders/cancel

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}

응답에는 cancel_date(취소일)와 cancel_reason(취소 사유)이 포함됩니다.

API 상세: 취소 주문 조회 API

반품 주문 확인

POST /vendor-api/orders/return

API 상세: 반품 주문 조회 API

교환 주문 확인

POST /vendor-api/orders/exchange

교환 주문에는 new_ord_prd_no(교환 후 새 주문품목번호)가 포함됩니다.

API 상세: 교환 주문 조회 API

주문 상태 흐름

주문 품목은 다음 상태를 순서대로 거칩니다.

각 상태별로 해당 item_status의 품목만 반환됩니다. 예: status=배송준비로 조회하면 item_status: "preparing" 품목만 반환됩니다.

Next Steps

• 정산 플로우 - 공급가 등록부터 거래명세서 발급까지
• 모범 사례 - Rate Limit 처리, 에러 핸들링 팁
• 에러 코드 - 전체 에러 코드 목록