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

거래명세서 조회 (PDF, 패킹 동봉용)

POST /vendor-api/settlements/transaction-statement

B2C 패킹 명세서 전용입니다. 구매자(병원)에게 배송 시 동봉되는 명세서로, 매 PUT confirm 회차마다 1장씩 패킹용도로 출력하는 흐름입니다. 정산 권위 문서가 아닙니다.

POST /vendor-api/settlements/transaction-statement
Content-Type: application/json

요청 파라미터

필드타입필수설명
ord_nostring택1주문번호 — 현재 preparing 상태인 모든 라인의 패킹 명세서
ord_prd_nostring택1주문품목번호 (형식: {주문번호}_[{인덱스}]) — 단일 라인 명세서

ord_no와 ord_prd_no 중 하나는 반드시 입력해야 합니다.

조회 키별 동작

조회 키반환 범위사용 시나리오
ord_no (주문번호)해당 주문에서 현재 preparing 상태인 모든 라인매 PUT 회차마다 패킹 명세서 출력
ord_prd_no (주문품목번호)해당 단일 라인이 preparing이면 1건 응답특정 라인만 명세서 재출력

요청 예시

주문번호로 조회

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 packing_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 packing_statement.pdf

응답

성공 시

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

응답 헤더값설명
Content-Typeapplication/pdfPDF 파일
Content-Dispositionattachment; filename*=UTF-8''거래명세서_{주문번호}.pdf파일명
Content-Length(바이트 수)파일 크기
X-Request-Idreq_m5k2a1_x7f3p9요청 추적 ID
X-Statement-Modepreview | nonepreview: 정상 응답 / none: 응답 라인 없음 (404)

실패 시

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

{
  "success": false,
  "request_id": "req_mkp3pdf_abc123",
  "error": {
    "code": "SETTLEMENT_NOT_FOUND",
    "message": "No packing statement available (no preparing line items)",
    "details": null
  }
}

동작 (B2C 패킹 흐름)

본 endpoint는 현재 preparing 상태인 라인만 응답합니다. 매 PUT confirm 회차 = 1장의 패킹 명세서 = 1회 배송 동봉.

  • 응답 unit_price는 판매가(sale_price, 플랫폼→병원 공급가)입니다.
  • 입점사→플랫폼 공급가는 응답에 노출되지 않습니다 (영업 비밀 보호).
  • 출하된 라인(shipped / delivered)은 이미 이전 회차 명세서에서 패킹되어 나갔으므로 다음 명세서에 포함되지 않습니다.
  • 자동 제외 라인: shipped, delivered, cancel_requested, null (PUT omit으로 reset), stock_available = false

응답 시나리오:

  1. 현재 preparing 라인 1건 이상 → PDF 반환 (X-Statement-Mode: preview)
  2. preparing 라인 0건 (전부 출고 또는 omit) → 404 SETTLEMENT_NOT_FOUND

주의사항

  • 응답은 JSON이 아닌 바이너리 PDF 파일입니다. HTTP 클라이언트에서 파일 저장 처리가 필요합니다.
  • Content-Disposition 헤더의 파일명은 UTF-8 인코딩되어 있습니다.
  • 정산 권위 문서(B2B 세금계산서/정산)는 별도 정산 도메인 endpoint를 사용하세요.

권장 흐름 (입점사 운영)

PUT confirm [라인 N개]   →  preparing
        ↓
GET packing statement     →  PDF 발급 (preparing 라인 N개 동봉)
        ↓
POST shipment             →  운송장 등록 → shipped
        ↓
PUT confirm [다른 라인]   →  다음 회차 시작
        ↓
GET packing statement     →  다음 회차 PDF 발급 (이전 출고 라인은 자동 제외)

매 PUT 회차마다 1장의 명세서를 출력해 패킹에 동봉하시면 됩니다.

Update ShipmentSettlement JSON