재고와 예약

수량의 정의

모든 수량은 같은 고객사와 SKU를 기준으로 조회하고 관리합니다.

현재고(onHandQuantity)는 입고·재고 정정 등으로 재고에 반영됐고 아직 출고하지 않은 물리 수량입니다. 예약한 상품이나 피킹·포장 중인 상품도 출고 전에는 포함됩니다. 수량만 등록하고 아직 입고 처리하지 않은 물량은 포함하지 않습니다.

예약 수량(reservedQuantity)은 출고에 사용할 수 있도록 확보해 새 예약의 대상에서 제외한 수량입니다. 고객사와 SKU별로 합산해 관리합니다.

가용 수량(availableQuantity)은 현재고 중 새로 예약할 수 있는 수량입니다.

출고 확보 수량(securedOutboundQuantity)은 진행 중인 출고가 확보한 예약 수량 중 아직 출고 완료되지 않은 수량입니다.

미사용 예약 수량(unusedReservedQuantity)은 진행 중인 출고가 확보하지 않은 예약 수량입니다. 새 출고에 사용하거나 예약을 해제할 수 있습니다.

수량 사이의 관계

같은 시점에 조회한 수량은 다음 관계를 가집니다.

가용 수량 = max(현재고 - 예약 수량, 0)
미사용 예약 수량 = 예약 수량 - 출고 확보 수량

예약 수량은 특정 주문·호출자·입고 물량에 귀속되지 않습니다. 예약 요청이 성공해도 그 요청자만 사용할 별도 예약 객체나 예약 ID가 만들어지는 것은 아닙니다. 같은 고객사·SKU의 다른 출고 요청도 미사용 예약 수량을 확보할 수 있습니다.

고객사 시스템이 주문별 배정과 우선순위를 관리해야 합니다. 예약 성공 응답의 reservationEventId는 수량 변경 기록의 식별자이며, 출고 요청에서 예약을 지정하는 ID가 아닙니다.

수량이 변하는 시점

입고 완료 수량 반영: 완료된 수량만큼 현재고가 늘어납니다. 자동 예약 지시를 사용한 경우 예약 수량도 함께 늘어날 수 있어, 입고 수량 전부가 가용 수량으로 늘지는 않습니다.
예약 확보: 예약 수량이 늘고 가용 수량이 줄어듭니다. 현재고는 그대로입니다.
출고 생성: 미사용 예약 수량을 해당 출고가 확보합니다. 전체 예약 수량과 현재고는 그대로입니다.
피킹·포장·인계 계획 등록: 현재고와 예약 수량을 소비하지 않습니다.
출고 완료 수량 반영: 완료된 수량만큼 현재고·예약 수량·출고 확보 수량이 함께 줄어듭니다. 미사용 예약 수량은 그대로입니다. 현재고와 예약이 같은 수량만큼 줄므로 가용 수량도 그대로입니다.
출고 취소: 해당 출고가 확보했던 수량이 미사용 예약으로 돌아옵니다. 공개 API의 출고 취소는 예약 자체를 해제하지 않습니다.
예약 해제: 미사용 예약 수량을 줄입니다. 현재고는 그대로이며, 가용 수량은 위 계산 관계에 따라 다시 계산됩니다.

재고 정정 등으로 현재고가 예약 수량보다 작아질 수도 있습니다. 이때 가용 수량은 음수가 되지 않고 0입니다. reservationExcessQuantity는 예약 수량이 현재고를 초과한 수량, outboundShortageQuantity는 출고 확보 수량이 현재고를 초과한 수량입니다.

입고·출고는 일부 수량씩 완료할 수 있습니다. 완료된 수량부터 현재고에 반영되며, 입고 요청이 CLOSED로 종료되거나 출고 요청이 COMPLETED로 전체 완료되는 순간에 같은 수량을 다시 반영하지 않습니다. 창고 작업상 입고는 적재 수량 저장, 출고는 실제 인계 결과 기록이 재고 반영의 기준입니다.

연동 규칙

새 예약은 최신 가용 수량 안에서만 요청할 수 있습니다. Maybox가 요청량 중 가능한 일부만 임의로 예약하지 않습니다.
출고 생성에는 모든 상품 행에 충분한 미사용 예약 수량이 필요합니다. 예약 확보와 출고 생성은 별도 API 요청입니다.
예약 해제는 미사용 예약 수량 안에서만 가능합니다. 진행 중인 출고가 확보한 수량은 해제할 수 없습니다.
예약은 자동으로 만료되지 않습니다. 필요 없어진 수량의 해제는 고객사 시스템에서 판단합니다.
조회 뒤 다른 요청으로 수량이 바뀔 수 있습니다. 조회값만으로 성공을 가정하지 않고 변경 API의 응답으로 결과를 판단합니다.

예제로 수량 변화 살펴보기

같은 상품의 수량은 어떻게 달라질까요?

입고 완료 수량 100개가 현재고에 반영됩니다. 입고 요청의 종료 여부와 별개로 완료된 수량부터 반영됩니다. 자동 예약이 없는 예제이므로 100개 모두 새로 예약할 수 있습니다.

현재고: 100개
예약 수량: 0개
가용 수량: 100개
출고 확보: 0개
미사용 예약: 0개

예약은 사용할 수량을 확보합니다. 현재고는 100개 그대로이고 새로 예약할 수 있는 수량은 80개입니다. 예약한 20개는 아직 어느 출고도 확보하지 않았습니다.

현재고: 100개
예약 수량: 20개
가용 수량: 80개
출고 확보: 0개
미사용 예약: 20개

출고 요청이 예약 중 12개를 확보합니다. 현재고와 전체 예약 수량은 그대로입니다. 남은 미사용 예약 8개는 다른 출고에 사용하거나 해제할 수 있습니다.

현재고: 100개
예약 수량: 20개
가용 수량: 80개
출고 확보: 12개
미사용 예약: 8개

12개 중 5개 출고가 완료됐고, 요청은 진행 중입니다. 출고 완료 수량은 5개, 남은 수량은 7개입니다. 현재고는 95개, 예약은 15개로 줄고 가용 수량 80개와 미사용 예약 8개는 그대로입니다.

현재고: 95개
예약 수량: 15개
가용 수량: 80개
출고 확보: 7개
미사용 예약: 8개

나머지 7개까지 출고해 요청한 12개 전체가 완료됩니다. 출고 완료 수량은 누적 12개입니다. 현재고는 88개, 예약은 8개가 되고 가용 수량 80개와 미사용 예약 8개는 그대로입니다.

현재고: 88개
예약 수량: 8개
가용 수량: 80개
출고 확보: 0개
미사용 예약: 8개

같은 고객사·SKU에 다른 입출고·예약·재고 정정이 없는 예제입니다. 두 막대 모두 처음 입고가 완료된 100개를 기준으로 표시합니다. 출고 완료 수량은 누계입니다.