도착과 입고

정의

도착 기록은 물건이 창고에 도착했다는 사실입니다. 상품이나 낱개 수량을 아직 모두 확인하지 못한 상태에서도 도착 사실을 기록할 수 있습니다. 고객사는 자신에게 조회 권한이 있는 도착 기록을 조회합니다.

입고 요청은 고객사가 들어올 상품과 예정 수량을 제출한 업무 기록입니다. inboundId로 구분하며, 상품별 예정 수량과 입고 완료 수량을 함께 조회합니다.

입고 완료 수량(completedQuantity)은 해당 입고에서 실제로 재고에 반영된 누적 수량입니다. 한 요청을 나눠 처리할 수 있으므로 입고 요청이 진행 중이어도 완료 수량이 있을 수 있습니다.

입고 종료는 이번 입고 요청의 처리를 마쳐 CLOSED가 된 상태입니다. 예정 수량보다 적게 받고 종료할 수도 있습니다. 종료 자체가 재고를 추가로 늘리지는 않습니다.

입고 수량 등록은 창고가 도착한 상품의 수량 등을 확인하고 기록하는 작업입니다. 창고가 확인된 물량을 보관 위치에 넣고 적재 수량을 저장하면, 그 수량이 입고 완료 수량과 현재고에 반영됩니다. 수량 등록이나 고객사의 등록 내용 확인만으로 입고가 완료되지는 않습니다.

다른 개념과의 관계

• 도착 기록과 입고 요청은 별도로 관리하며 서로 여러 건을 연결할 수 있습니다. 연결 자체가 수량 배분이나 재고 반영을 뜻하지 않습니다.
• 입고 요청의 각 상품 행은 SKU와 예정 수량을 담습니다. 예정 수량과 창고가 실제로 기록한 수량은 다를 수 있습니다.
• 창고는 등록 내용을 고객사에 확인 요청하고, 고객사는 조회·검토한 내용을 확인합니다. 이후 창고에서 처리한 수량부터 입고 완료 수량에 반영됩니다.
• 한 입고의 완료 수량과 SKU의 현재고는 별개입니다. 완료 수량은 해당 입고의 실적이며, SKU의 현재고에는 다른 입고·출고·재고 정정도 반영됩니다. 이후 출고됐다고 과거 입고 완료 수량이 줄지는 않습니다.

등록 내용 확인과 버전 번호

등록 내용의 버전 번호(registrationRevision)는 고객사가 확인할 창고 기록을 구분하는 값입니다. 확인 요청과 고객사 확인은 이 버전 번호에 연결됩니다.

내가 검토한 등록 내용과 현재 버전이 같아야 합니다

조회·검토한 버전 3 → 확인 API에 3 전송

그사이 내용이 바뀌지 않았다면

현재 버전 3

같은 버전 → 확인 기록

이후 입고 완료 수량으로 실제 재고 반영을 확인합니다.

그사이 버전이 바뀌었다면

현재 버전 4

다른 버전 → 최신 내용 재조회

새 내용과 확인 요청을 검토합니다. 번호만 바꿔 자동으로 확인하지 않습니다.

입고가 OPEN이고 아직 확인하지 않은 현재 버전의 확인 요청이 있으며, 고객사가 내용을 검토한 경우의 예제입니다. 확인 자체로 현재고가 늘지는 않습니다.

확인 API를 호출하기 전에 다음을 함께 확인합니다.

• 입고 상태가 OPEN이다.
• 창고의 registrationConfirmationRequest가 있고, 요청의 버전 번호가 현재 registrationRevision과 같다.
• 현재 버전을 아직 확인하지 않았다. 이미 확인했다면 확인 작업을 새 업무로 반복하지 않는다.
• 고객사가 해당 버전의 수량·상품·필요한 실측 결과를 검토했다.

고객사는 조회한 버전 번호를 확인 API에 보냅니다. 그사이 버전이 바뀌면 이전 번호로 확인할 수 없으므로 최신 내용과 확인 요청을 다시 조회합니다. 버전 번호를 수정 횟수나 입고 요청 번호로 해석하지 않습니다.

상태와 수량의 변화

입고는 OPEN으로 진행하다 CLOSED로 종료됩니다. 등록 내용의 고객사 확인 여부와 입고 완료 수량은 입고 상태와 별도로 조회합니다.

• expectedQuantity: 고객사가 요청한 예정 수량
• registeredQuantity: 창고가 기록한 수량. 아직 입고 완료되지 않은 수량도 포함
• completedQuantity: 해당 입고의 입고 완료 수량

부분 완료와 입고 종료

예정 수량 100개를 모두 등록·확인한 뒤, 60개를 먼저 입고 처리하고 나머지 40개를 처리하는 예제입니다.

입고 완료 수량	입고 상태	의미
60	OPEN	60개는 이미 재고에 반영됐고 나머지 40개는 처리 중
100	OPEN	나머지 40개까지 재고에 반영됐지만 입고 요청은 아직 열려 있음
100	CLOSED	이번 요청의 처리를 마침. 종료로 재고가 다시 늘지는 않음

별도로, 100개 중 60개만 도착했다면 그 차이를 확인하고 도착한 물량을 모두 처리한 뒤 CLOSED로 종료할 수도 있습니다. 따라서 종료 여부만으로 예정 수량 전부의 입고 완료를 판단하지 않습니다.

연동 규칙

• 입고 요청 생성·도착 연결·수량 등록·고객사 확인만으로 현재고가 늘지 않습니다. completedQuantity로 입고 완료 수량을 확인합니다.
• 새로 예약할 수 있는 수량은 재고 조회 API의 availableQuantity로 확인합니다. 입고와 함께 자동 예약된 물량은 현재고에 포함돼도 가용 수량에서는 제외됩니다.
• 생성 응답의 inboundId를 고객사 입고 번호와 연결해 저장합니다.
• 웹훅 수신 자체를 고객사의 등록 내용 확인으로 처리하지 않습니다. 최신 상세와 확인 요청을 조회한 뒤 확인합니다.
• 예전 버전의 내용을 자동으로 다시 승인하지 않습니다. 버전 불일치 오류는 재조회와 재검토로 처리합니다.

관련 문서

• 입고 연동 가이드: 요청·조회·등록 내용 확인 API 호출
• 전체 업무 흐름: 입고·예약·출고 완료 수량의 예제
• 재고와 예약: 입고 수량과 현재고의 구분
• API 레퍼런스: 도착·입고 조회와 확인 API