전체 업무 흐름

고객사 시스템의 요청과 창고의 작업이 어떻게 이어지는지 살펴보는 예제입니다. 세럼 100개를 입고하고, 20개를 예약한 뒤 그중 12개를 출고합니다. API 계정 없이도 읽을 수 있습니다.

개별 용어의 정의와 규칙은 핵심 개념에서 찾아볼 수 있습니다. 실제 요청 코드는 입고 연동, 출고 연동 가이드로 이어집니다.

입고부터 출고까지의 흐름

고객사 입고 요청 → 창고 수량 기록과 확인 요청 → 고객사 등록 내용 확인 → 창고 입고 처리 → 입고 완료 수량만큼 현재고 증가 — 입고·출고는 나눠 처리할 수 있으며 완료된 수량부터 재고에 반영됩니다. 완료 수량과 요청 전체의 상태를 함께 조회합니다.

예제를 단계별 설명으로 읽기

고객사 — 상품과 입고 예정 수량 제출

상품 코드 DEMO-SERUM-001을 등록하고 세럼 100개의 입고를 요청합니다. 아직 현재고는 늘지 않습니다.
창고 — 도착한 상품의 수량 등록 / 고객사 — 내용 확인

창고가 상품과 수량을 기록하고 고객사에 확인을 요청합니다. 고객사는 기록을 조회·검토한 뒤 해당 내용을 확인합니다.
창고 — 입고 처리 / 고객사 — 입고 완료 수량 조회

창고가 상품을 보관 위치에 넣고 적재 수량을 저장하면 그 수량의 입고가 완료됩니다. 예제에서는 100개의 입고가 완료돼 현재고가 100개가 됩니다. 입고 요청 전체의 종료 여부는 별도로 확인합니다.
고객사 — 수량 예약과 출고 요청

20개를 예약한 뒤 12개를 출고 요청합니다. 나머지 예약 8개는 다른 출고에 사용하거나 필요 없으면 해제할 수 있습니다.
창고 — 출고 처리 / 고객사 — 출고 완료 수량 조회

창고가 상품을 준비해 운송사나 픽업 담당자에게 넘긴 결과를 기록합니다. 5개를 먼저 출고하면 완료 수량은 5개이고 요청은 진행 중입니다. 나머지 7개까지 출고하면 완료 수량은 12개, 현재고는 88개가 되고 출고 요청이 전체 완료됩니다.

입고와 출고는 여러 번에 나눠 처리할 수 있습니다. 완료된 수량부터 재고에 반영되므로 고객사 시스템은 부분 완료 수량과 요청 전체의 상태를 함께 조회해야 합니다.

완료 수량과 요청 상태는 별개입니다

업무	부분 완료의 예	요청 전체의 종료·완료
입고 100개	60개가 먼저 입고되면 `completedQuantity`는 60, 상태는 `OPEN`일 수 있음	이번 요청의 처리를 마치면 `CLOSED`. 예정 수량보다 적게 받고 종료할 수도 있음
출고 12개	5개가 먼저 출고되면 `dispatchedQuantity`는 5, 상태는 `IN_PROGRESS`	모든 SKU의 요청 수량이 출고되면 `COMPLETED`

입고 완료 수량은 해당 입고의 누적 실적입니다. 이후 출고로 현재고가 줄어도 과거 입고 완료 수량은 줄지 않습니다. 새로 예약할 수 있는 수량은 재고 조회 API의 availableQuantity로 확인합니다.

단계별로 살펴볼 개념

상품을 등록할 때: 고객사와 연동 계정, 상품과 SKU
창고의 입고 수량을 확인할 때: 도착과 입고, 등록 내용의 버전 번호
출고할 수량을 확보할 때: 재고와 예약
출고 완료 수량과 남은 수량을 확인할 때: 출고 요청과 완료
변경을 자동으로 반영할 때: 이벤트와 웹훅

예제의 수량 변화

다른 입출고·예약·재고 정정이 없는 상황입니다. 현재고와 예약의 정의·계산 관계는 재고와 예약을 참고하세요.

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

입고 완료 수량 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개를 기준으로 표시합니다. 출고 완료 수량은 누계입니다.

출고 요청·피킹·포장만으로 현재고가 줄지는 않습니다. 출고가 완료된 수량만큼 현재고와 예약 수량이 함께 줄어듭니다. 이미 예약돼 있던 물량이므로 이 예제의 가용 수량은 80개로 유지됩니다. 남은 미사용 예약 8개는 다른 출고에 사용하거나 필요 없으면 해제할 수 있습니다.

고객사 시스템에 결과 반영

웹훅으로 입고·출고 변경을 받으면 API로 최신 상태를 조회해 고객사 시스템에 반영합니다. 처음 연결할 때의 상태 동기화와 중간에 놓친 이벤트의 복구도 함께 준비합니다.

연결 준비와 첫 호출에서 연동 계정과 API 인증 정보를 준비합니다.
입고 연동, 출고 연동에서 위 예제의 실제 호출을 연결합니다.
웹훅 수신과 초기 동기화·누락 복구를 구현합니다.