거래명세서 조회 - PDF

주문번호(ord_no) 또는 주문품목번호(ord_prd_no)로 해당 주문/품목이 포함된 정산 건의 거래명세서를 PDF 파일로 다운로드합니다.

권장: 거래명세서가 필요한 경우 이 API 사용을 권장합니다. PDF 형식은 서버 측 스키마 변경에 영향받지 않으며, 인쇄/보관에 즉시 사용 가능하므로 연동 파트너 측에서 별도 대응 없이 안정적으로 사용할 수 있습니다.

Endpoint


POST /vendor-api/settlements/transaction-statement

요청 파라미터

필드	타입	필수	설명
`ord_no`	string	택1	주문번호 — 권장. 미출하 품목만 포함
`ord_prd_no`	string	택1	주문품목번호 (형식: `{주문번호}_[{인덱스}]`) — 하위 호환
`settlement_type`	string	-	정산 유형 (기본값: `"standard"`)

ord_no와 ord_prd_no 중 하나는 반드시 입력해야 합니다. 둘 다 입력하면 ord_no가 우선 적용됩니다.

조회 키별 동작 차이

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

settlement_type 허용값

값	설명	예시 상황
`standard`	표준 정산 (기본값) - 정상 주문에 대한 거래명세서	정상 배송 완료 주문
`cancellation`	취소 정산 - 취소/반품된 주문에 대한 마이너스 거래명세서	고객 취소, 반품 처리

요청 예시

주문번호로 조회 (권장)

미출하 품목만 거래명세서에 포함됩니다.


curl -X POST "https://brightmall-backend.certi.life/vendor-api/settlements/transaction-statement" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{"ord_no": "202601220157_000020196"}' \
  --output transaction_statement.pdf

주문품목번호로 조회 (하위 호환)

해당 품목이 포함된 정산의 전체 품목이 거래명세서에 포함됩니다.


curl -X POST "https://brightmall-backend.certi.life/vendor-api/settlements/transaction-statement" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{"ord_prd_no": "202601220157_000020196_[1]"}' \
  --output transaction_statement.pdf

취소 거래명세서 조회


curl -X POST "https://brightmall-backend.certi.life/vendor-api/settlements/transaction-statement" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{"ord_no": "202601220157_000020196", "settlement_type": "cancellation"}' \
  --output cancellation_statement.pdf

응답

성공 시

PDF 바이너리 파일이 직접 반환됩니다.

응답 헤더	값	설명
`Content-Type`	`application/pdf`	PDF 파일
`Content-Disposition`	`attachment; filename*=UTF-8''거래명세서_SET-20260211-001.pdf`	파일명
`Content-Length`	(바이트 수)	파일 크기
`X-Request-Id`	`req_m5k2a1_x7f3p9`	요청 추적 ID

파일명 규칙:

표준 정산: 거래명세서_{정산번호}.pdf (예: 거래명세서_SET-20260211-001.pdf)
취소 정산: 거래명세서(취소)_{정산번호}.pdf (예: 거래명세서(취소)_SET-20260211-002.pdf)

실패 시

JSON 에러 응답이 반환됩니다.


{
  "success": false,
  "request_id": "req_mkp3pdf_abc123",
  "error": {
    "code": "SETTLEMENT_NOT_FOUND",
    "message": "No settlement found for the given order number",
    "details": null
  }
}

주의사항

응답은 JSON이 아닌 바이너리 PDF 파일입니다. HTTP 클라이언트에서 파일 저장 처리가 필요합니다.
Content-Disposition 헤더의 파일명은 UTF-8 인코딩되어 있습니다.
정산 상태가 pending, confirmed, paid 중 하나인 경우에만 거래명세서 조회가 가능합니다.
정산이 아직 생성되지 않은 품목은 SETTLEMENT_NOT_FOUND 에러가 반환됩니다.
ord_no로 조회 시, 이미 출하 완료(배송 등록)된 품목은 거래명세서에서 자동 제외됩니다. 모든 품목이 출하 완료된 경우 빈 거래명세서가 될 수 있습니다.

거래명세서 조회 가능 시점

거래명세서는 공급가 등록 후 정산이 자동 생성된 시점부터 조회할 수 있습니다.

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