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

정산 플로우

이 가이드에서는 공급가 등록부터 정산 자동 생성, 거래명세서 조회까지의 정산 처리 흐름을 설명합니다.

정산 개요

브라이트몰의 정산은 공급가 등록 시 자동으로 생성됩니다. 별도의 정산 생성 API를 호출할 필요가 없습니다.

정산 플로우 요약:

  1. 공급가 등록 (재고 확인 / 배송 등록 / 배송 수정 / 상태 변경 API)
  2. 정산 자동 생성 (시스템)
  3. 거래명세서 조회 (PDF 또는 JSON)

Step 1. 공급가 등록

공급가는 다음 4개 API 중 하나에서 supply_price 파라미터로 입력합니다.

API엔드포인트권장 시점
재고 확인POST /vendor-api/inventory/confirm권장 - 주문 접수 직후
배송 등록POST /vendor-api/shipment송장번호 등록과 동시에
배송 수정PUT /vendor-api/shipment나중에 입력 또는 수정
상태 변경POST /vendor-api/orders/statusdelivered 처리 시

공급가 입력 형식

{
  "supply_price": {
    "unit_price": 75000,
    "quantity": 2,
    "total_amount": 150000
  }
}
필드타입필수설명
unit_pricenumberO공급 단가 (0 이상)
quantitynumberO수량 (1 이상, 정수)
total_amountnumberO총 공급가 (0 이상)

total_amount는 unit_price x quantity와 일치하는 것이 권장되나, 할인 등의 사유로 다를 수 있습니다.

공급가 수정

공급가는 배송 수정 API로 수정할 수 있습니다. 변경 이력은 시스템에서 자동으로 추적됩니다 (최대 10건).

Step 2. 정산 자동 생성

공급가가 등록되면 시스템이 해당 품목에 대한 정산을 자동으로 생성합니다.

정산에는 두 가지 유형이 있습니다.

유형settlement_type설명
표준 정산standard정상 주문에 대한 정산 (양수 금액)
취소 정산cancellation취소/반품에 대한 마이너스 정산 (음수 금액)

표준 정산은 공급가 등록 시 자동 생성됩니다. 취소 정산은 주문이 취소되거나 반품 처리될 때 시스템이 자동으로 생성합니다.

Step 3. 거래명세서 조회

정산이 생성된 후 거래명세서를 조회할 수 있습니다. PDF와 JSON 두 가지 형식을 지원합니다.

PDF 거래명세서 (권장)

POST /vendor-api/settlements/transaction-statement
{
  "ord_no": "202601220157_000020196"
}

PDF 파일이 바이너리로 직접 반환됩니다. 인쇄 및 보관에 즉시 사용할 수 있고, 서버 측 스키마 변경에 영향을 받지 않아 안정적입니다.

API 상세: 거래명세서 PDF API

JSON 거래명세서 (비권장)

POST /vendor-api/settlements/transaction-statement/data
{
  "ord_no": "202601220157_000020196"
}

JSON 데이터를 프로그래밍적으로 가공해야 하는 특수한 경우에만 사용하세요. 향후 응답 스키마가 변경될 경우 연동 코드 수정이 필요할 수 있습니다.

API 상세: 거래명세서 JSON API

PDF vs JSON 비교

구분PDF APIJSON API
응답 형식PDF 파일 (바이너리)JSON 데이터
직접 인쇄/보관가능별도 가공 필요
스키마 변경 대응불필요 (서버에서 렌더링)필요 (코드 수정)
커스텀 활용제한적데이터 자유 가공 가능
권장 여부권장비권장

거래명세서 조회 가능 시점

조건조회 가능 여부설명
공급가 미등록X공급가 등록 후 정산이 자동 생성됩니다
공급가 등록 완료 (정산 생성됨)Opending 상태부터 조회 가능
정산 확정 (confirmed)O조회 가능
정산 지급 완료 (paid)O조회 가능
취소/반품 발생Osettlement_type=cancellation으로 조회

공급가가 등록되지 않은 상태에서 거래명세서를 조회하면 SETTLEMENT_NOT_FOUND 에러가 반환됩니다.

ord_no vs ord_prd_no 조회 차이 (v1.7.0)

거래명세서 조회 시 주문번호(ord_no)와 주문품목번호(ord_prd_no) 중 하나를 사용할 수 있습니다.

조회 키반환 범위권장 여부사용 시나리오
ord_no (주문번호)해당 주문의 미출하(pending) 품목만권장출하 전 거래명세서 확인, 부분출하
ord_prd_no (주문품목번호)해당 품목이 속한 정산의 전체 품목하위 호환특정 품목의 정산 전체 내역 확인

ord_no로 조회 (권장)

{
  "ord_no": "202601220157_000020196"
}
  • 해당 주문에서 아직 출하되지 않은(pending) 품목만 거래명세서에 포함
  • 부분출하 시 나머지 품목만 자동 필터링
  • 모든 품목이 출하 완료되면 빈 거래명세서

ord_prd_no로 조회 (하위 호환)

{
  "ord_prd_no": "202601220157_000020196_[1]"
}
  • 해당 품목이 포함된 정산의 전체 품목이 거래명세서에 포함
  • 출하 상태와 무관하게 모든 품목 표시
  • v1.6.0 방식과 동일한 동작

두 파라미터를 모두 입력하면 ord_no가 우선 적용됩니다.

마이그레이션 방법

기존 ord_prd_no 방식에서 ord_no 방식으로 전환하려면, ord_prd_no에서 _[인덱스] 부분을 제거하면 됩니다.

변경 전: "ord_prd_no": "202601220157_000020196_[1]"
변경 후: "ord_no": "202601220157_000020196"

출하 상태와 부분출하 필터링

배송 등록 API를 호출하면 해당 품목의 정산 출하 상태(shipment_status)가 자동으로 pending에서 shipped로 변경됩니다.

shipment_status설명ord_no 조회 시
pending미출하거래명세서에 포함
shipped출하 완료거래명세서에서 제외

이 자동 필터링 덕분에 부분출하 시나리오를 별도 로직 없이 처리할 수 있습니다.

자세한 부분출하 시나리오는 주문 처리 플로우 - 부분출하 시나리오를 참조하세요.

취소 거래명세서

주문이 취소되거나 반품 처리되면 시스템이 자동으로 취소 정산(마이너스 정산)을 생성합니다.

취소 거래명세서 조회 흐름

  1. 고객 또는 관리자가 주문 취소/반품 요청
  2. 시스템이 자동으로 취소 정산 생성 (settlement_type: "cancellation")
  3. 거래명세서 API에서 settlement_type: "cancellation"으로 조회
{
  "ord_no": "202601220157_000020196",
  "settlement_type": "cancellation"
}

취소 정산은 해당 품목이 취소 또는 반품 처리된 경우에만 존재합니다. 취소 정산이 없으면 SETTLEMENT_NOT_FOUND 에러가 반환됩니다.

거래명세서 파일명 규칙

유형파일명 형식예시
표준 정산거래명세서_{정산번호}.pdf거래명세서_SET-20260211-001.pdf
취소 정산거래명세서(취소)_{정산번호}.pdf거래명세서(취소)_SET-20260211-002.pdf

에러 처리

SETTLEMENT_NOT_FOUND

거래명세서 조회 시 가장 자주 발생하는 에러입니다. 다음 항목을 순서대로 확인하세요.

  1. 공급가가 등록되었는지 확인 (가장 흔한 원인) - 공급가 등록 시 정산이 자동 생성됩니다
  2. 정산 유형 확인 - 표준 정산은 settlement_type 미지정 또는 "standard", 취소 정산은 "cancellation"
  3. 해당 입점사 품목인지 확인 - 다른 입점사 품목이나 자사제품은 조회 불가
  4. 주문번호/주문품목번호 형식 확인 - ord_no 또는 {주문번호}_[{인덱스}] 형식이 올바른지 확인

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

Next Steps

Last updated on
Order FlowWebhook