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

주문 품목의 재고 상태를 확인하고, 선택적으로 공급가를 사전 등록합니다.

Endpoint


POST /vendor-api/inventory/confirm

요청 파라미터

필드	타입	필수	설명
`confirmations`	array	O	확인 항목 배열 (최대 100건)
`confirmations[].ord_prd_no`	string	O	주문품목번호
`confirmations[].stock_available`	boolean	O	재고 가용 여부 (`true`: 출고 가능, `false`: 출고 불가)
`confirmations[].unavailable_reason`	string	조건부	출고 불가 사유 (`stock_available=false` 시 필수)
`confirmations[].memo`	string	-	메모 (최대 500자)
`confirmations[].supply_price`	object	-	공급가 정보 (공통 스키마 참조)

unavailable_reason 허용값

값	설명
`out_of_stock`	재고 부족 (품절)
`reserved`	다른 주문에 예약됨
`damaged`	상품 파손
`discontinued`	단종
`other`	기타 사유

요청 예시


curl -X POST "https://brightmall-backend.certi.life/vendor-api/inventory/confirm" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{
    "confirmations": [
      {
        "ord_prd_no": "202601220157_000020196_[1]",
        "stock_available": true,
        "supply_price": {
          "unit_price": 75000,
          "quantity": 2,
          "total_amount": 150000
        }
      },
      {
        "ord_prd_no": "202601220157_000020196_[2]",
        "stock_available": false,
        "unavailable_reason": "out_of_stock",
        "memo": "재입고 예정일: 2026-02-15"
      }
    ]
  }'

응답 예시


{
  "request_id": "req_mkp3inv_abc123",
  "timestamp": "2026-01-29T07:00:00.000Z",
  "success_count": 2,
  "failure_count": 0,
  "available_count": 1,
  "unavailable_count": 1,
  "results": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "success": true,
      "stock_available": true,
      "new_status": "preparing",
      "supply_price_recorded": true,
      "message": "Inventory confirmed and supply price recorded"
    },
    {
      "ord_prd_no": "202601220157_000020196_[2]",
      "success": true,
      "stock_available": false,
      "new_status": "pending",
      "message": "Item marked as unavailable: out_of_stock"
    }
  ]
}

응답 필드 설명

필드	타입	설명
`success_count`	number	처리 성공 건수
`failure_count`	number	처리 실패 건수
`available_count`	number	재고 가용 건수
`unavailable_count`	number	재고 불가 건수
`results[].ord_prd_no`	string	주문품목번호
`results[].success`	boolean	처리 성공 여부
`results[].stock_available`	boolean	재고 가용 여부
`results[].new_status`	string	변경된 품목 상태
`results[].supply_price_recorded`	boolean	공급가 기록 여부 (supply_price 입력 시에만 포함)
`results[].message`	string	처리 결과 메시지

Endpoint


PUT /vendor-api/inventory/confirm

요청 파라미터

필드	타입	필수	설명
`ord_no`	string	O	주문번호
`confirmations`	array	O	확인 항목 배열 (최대 100건) — POST와 동일 스키마
`confirmations[].ord_prd_no`	string	O	주문품목번호
`confirmations[].stock_available`	boolean	O	재고 가용 여부
`confirmations[].unavailable_reason`	string	조건부	출고 불가 사유 (`stock_available=false` 시 필수)
`confirmations[].memo`	string	-	메모
`confirmations[].supply_price`	object	-	공급가 정보

동작: Snapshot replace 시맨틱. Body의 confirmations에 명시한 품목만 처리하고, 누락된 pending/preparing 품목은 자동으로 cancel_requested 상태로 전환됩니다.

v0.2.0 — 점진적 회복 지원: 이전 PUT에서 vendor_omitted_in_put 사유로 cancel된 품목을 다음 PUT으로 회복 가능합니다. confirmations에 해당 ord_prd_no를 다시 포함하면 cancel_requested → preparing으로 전환되고 응답에 recovered: true 플래그가 표시됩니다. 회복 시 기존 cancel_request는 cancel_history[] 배열로 이동되어 감사 기록이 누적됩니다. 단, 다른 사유(재고 부족, 사용자 취소 등)로 cancel된 품목은 회복 불가 — 보호 그대로.

unavailable_reason 허용값

값	설명
`out_of_stock`	재고 부족 (품절)
`reserved`	다른 주문에 예약됨
`damaged`	상품 파손
`discontinued`	단종
`other`	기타 사유

요청 예시


curl -X PUT "https://brightmall-backend.certi.life/vendor-api/inventory/confirm" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{
    "ord_no": "202601220157_000020196",
    "confirmations": [
      {
        "ord_prd_no": "202601220157_000020196_[1]",
        "stock_available": true,
        "supply_price": {
          "unit_price": 75000,
          "quantity": 2,
          "total_amount": 150000
        }
      }
    ]
  }'

응답 예시


{
  "request_id": "req_mkp3inv_abc123",
  "timestamp": "2026-01-29T07:00:00.000Z",
  "success_count": 1,
  "failure_count": 0,
  "available_count": 1,
  "unavailable_count": 0,
  "omitted_count": 1,
  "results": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "success": true,
      "stock_available": true,
      "previous_status": "preparing",
      "new_status": "preparing",
      "supply_price_recorded": true,
      "recovered": false,
      "message": "Inventory confirmed and supply price recorded"
    }
  ],
  "omitted_and_cancelled": [
    {
      "ord_prd_no": "202601220157_000020196_[2]",
      "previous_status": "pending",
      "new_status": "cancel_requested",
      "message": "Automatically cancelled: vendor_omitted_in_put"
    }
  ]
}

회복 응답 예시 (점진적 PUT)

직전에 vendor_omitted_in_put으로 cancel된 _[2]를 다시 PUT 호출하면 recovered: true로 회복됩니다.


{
  "request_id": "req_mkp3inv_def456",
  "timestamp": "2026-01-29T07:05:00.000Z",
  "success_count": 1,
  "failure_count": 0,
  "available_count": 1,
  "unavailable_count": 0,
  "omitted_count": 1,
  "results": [
    {
      "ord_prd_no": "202601220157_000020196_[2]",
      "success": true,
      "stock_available": true,
      "previous_status": "cancel_requested",
      "new_status": "preparing",
      "supply_price_recorded": true,
      "recovered": true,
      "message": "Item recovered from vendor_omitted_in_put"
    }
  ],
  "omitted_and_cancelled": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "previous_status": "preparing",
      "new_status": "cancel_requested",
      "message": "Automatically cancelled: vendor_omitted_in_put"
    }
  ]
}

응답 필드 설명

필드	타입	설명
`omitted_count`	number	누락되어 자동 cancel 처리된 품목 수
`omitted_and_cancelled[]`	array	누락되어 cancel_requested 전환된 품목 목록
`omitted_and_cancelled[].ord_prd_no`	string	주문품목번호
`omitted_and_cancelled[].previous_status`	string	변경 전 상태
`omitted_and_cancelled[].new_status`	string	변경 후 상태 (항상 `"cancel_requested"`)
`omitted_and_cancelled[].message`	string	상태 변경 메시지
`results[].recovered`	boolean	v0.2.0: vendor_omitted_in_put 회복 시 `true`. 재고 입력 신호로 cancel_requested → preparing 전환된 경우
`results[].previous_status`	string	변경 전 상태 (`pending` / `preparing` / `cancel_requested`)

사용 사례

PUT은 최종 전송 = 진실 시맨틱입니다. 입점사가 다회 호출로 인한 잔존 데이터 없이 한 번에 재고 상태를 갱신하고 싶을 때 사용합니다.

예시 1 — 한 번에 명시: 주문의 3개 품목 중 2개만 재고 있을 때

POST: 2개를 재고 있음으로 표시 → 나머지 1개는 pending 상태 유지
PUT: ord_no + confirmations 2개만 전송 → 나머지 1개는 자동으로 cancel_requested 전환

예시 2 — 점진적 PUT (v0.2.0): 한 품목씩 재고 확인하며 거래명세서 단계별 확인

1차 PUT: [_[1]] → _[2],_[3] 자동 cancel(vendor_omitted_in_put)
거래명세서 호출 → items=1 (_[1])
2차 PUT: [_[1], _[2]] → _[2] 회복 (recovered: true), _[3] 여전히 cancel
거래명세서 호출 → items=2 (_[1], _[2])
3차 PUT: [_[1], _[2], _[3]] → _[3] 회복 (recovered: true)
거래명세서 호출 → items=3 (모두 출력)

각 PUT 후 거래명세서가 그 시점의 최종 상태를 정확히 반영합니다. cancel_request 객체는 회복 시 cancel_history[] 배열로 이동되어 누적되므로 cancel/recovery 이력을 추적할 수 있습니다.

회복 가능 조건: cancel 사유가 vendor_omitted_in_put인 품목만 회복. 다른 사유(재고 부족, 사용자 취소, 환불 등)로 cancel된 품목은 회복 불가.

에러

코드	상태	설명
`ORDER_NOT_FOUND_OR_NO_VENDOR_ITEMS`	404	본인 vendor 품목 0건
`ORD_PRD_NO_MISMATCH`	400	confirmations의 ord_prd_no가 ord_no에 속하지 않음

주의사항

공급가를 입력하면 메타데이터만 저장되며, 정산 생성은 배송 등록/수정 시점에서 발생합니다
shipped/delivered 품목은 PUT 누락이어도 무변경입니다 (post-shipment 가드)
다른 vendor 품목, 자사몰(DNTM) 품목, order/order_item/결제 정보는 절대 손대지 않습니다
v0.2.0: vendor_omitted_in_put 사유로 cancel된 품목은 다음 PUT으로 회복 가능 (recovered: true). 다른 cancel 사유는 보호 그대로

참고사항

이 API는 선택사항이지만, 공급가를 사전에 등록하면 거래명세서를 미리 확인할 수 있습니다.
POST: 멱등성 지원. 동일한 공급가와 수량이면 기존 상태 유지, 변경되면 메타데이터 업데이트.
PUT: Snapshot replace. confirmations에 명시한 품목만 처리, 누락된 pending/preparing은 자동 cancel.
출고 불가(stock_available: false)로 등록한 품목은 번복할 수 없습니다. 취소 프로세스가 즉시 시작되므로, 재고 유무를 전송하기 전에 반드시 실재고를 확인해주세요.