배송 등록

품목의 배송 정보(택배사, 송장번호)를 등록합니다. 선택적으로 공급가를 함께 등록할 수 있습니다.

Endpoint


POST /vendor-api/shipment

배송 등록 시 해당 품목의 정산 출하 상태가 자동으로 shipped로 변경됩니다. 이후 ord_no(주문번호)로 거래명세서를 조회하면 출하 완료된 품목은 거래명세서에서 제외됩니다.

요청 파라미터

필드	타입	필수	설명
`shipments`	array	O	배송 등록 배열 (최대 100건)
`shipments[].ord_prd_no`	string	O	주문품목번호 (세트 구성품은 `{주문품목번호}^s{n}` — 같은 품목 구성품은 `carrier_code`·`tracking_number` 가 같아야 함)
`shipments[].carrier_code`	string	O	택배사 코드
`shipments[].tracking_number`	string	O	송장번호
`shipments[].shipped_at`	string	-	발송일시 (ISO 8601, 미입력 시 현재시각)
`shipments[].idempotency_key`	string	-	멱등성 키 (중복 방지)
`shipments[].supply_price`	object	-	공급가 정보 (공통 스키마 참조)

택배사 코드

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

요청 예시


curl -X POST "https://brightmall-backend.certi.life/vendor-api/shipment" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: <발급받은 API 키>" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{
    "shipments": [
      {
        "ord_prd_no": "202601220157_000020196_[1]",
        "carrier_code": "cj",
        "tracking_number": "1234567890",
        "supply_price": {
          "unit_price": 75000,
          "quantity": 2,
          "total_amount": 150000
        }
      }
    ]
  }'

응답 예시


{
  "request_id": "req_mkp3shp_abc123",
  "timestamp": "2026-01-22T08:00:00.000Z",
  "success_count": 1,
  "failure_count": 0,
  "results": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "success": true,
      "status": "success",
      "message": "Shipment registered",
      "order_status": "shipped"
    }
  ]
}

응답 필드 설명

필드	타입	설명
`success_count`	number	처리 성공 건수
`failure_count`	number	처리 실패 건수
`results[].ord_prd_no`	string	보낸 주문품목번호 그대로
`results[].base_ord_prd_no`	string	(v1.9.0) 세트 구성품 번호로 보낸 경우 몰 주문품목번호
`results[].quantity_mismatch`	object	(v1.9.0) `supply_price.quantity` 가 몰 주문 수량과 다를 때 `{ expected, received }` — 거절 아님
`results[].success`	boolean	처리 성공 여부
`results[].status`	string	처리 상태 (`success`, `failed`)
`results[].message`	string	처리 결과 메시지
`results[].order_status`	string	변경된 주문 상태

참고사항

한 번에 최대 100건까지 배송을 등록할 수 있습니다.
supply_price를 함께 입력하면 공급가와 송장을 동시에 등록할 수 있습니다. quantity 는 몰 주문 수량(몰 판매단위), unit_price 는 몰 판매단위 1개당입니다(공통 규격).
(v1.9.0) 세트 구성품 번호로 보내면 같은 품목의 구성품을 한 품목으로 출고합니다. 송장이 서로 다르면 SUB_ITEM_CONFLICT(출고 안 됨). 구성품 supply_price 는 검토용 기록만 하고 정산은 몰 공급가로 만듭니다.
이미 배송 등록된 품목에 대해 다시 호출하면 ALREADY_SHIPPED 에러가 반환됩니다. 송장번호를 변경하려면 배송 수정 API를 사용하세요.