상품과 SKU

정의

SKU는 고객사가 정한 상품 코드입니다. 입고할 상품, 현재 재고, 출고할 상품을 같은 코드로 연결하는 기준입니다.

• sku: 고객사가 정한 코드입니다. 대소문자를 구분합니다.
• skuId: 상품을 등록한 뒤 Maybox가 부여한 ID입니다. sku와 다른 값입니다.
• skuName·brandName: 창고에서 상품을 알아볼 수 있게 전달하는 상품명·브랜드명입니다.

같은 코드라도 고객사가 다르면 별도의 상품 범위에 속합니다.

다른 개념과의 관계

• 입고와 출고 요청의 각 상품 행은 sku로 상품을 지정합니다.
• 재고와 예약 수량도 고객사와 SKU를 기준으로 조회하고 관리합니다. 상품 등록 자체로 재고가 생기지는 않습니다.
• 입고·출고 요청에는 상품 코드와 함께 창고 작업자가 볼 상품명·브랜드명을 보냅니다. 이 값은 요청을 생성할 때의 정보입니다.
• 고객사 시스템의 입고·주문·출고 번호는 상품 코드와 별개입니다. externalReference로 전달할 수 있으며, 생성 응답의 inboundId·outboundId와 연결해 저장합니다.

상품 정보·규격·실측

규격은 상품이나 기본 카톤의 기준 치수·무게 등의 정보입니다. 실측은 창고가 낱개나 카톤을 실제로 측정한 결과입니다. 카톤 실측에는 입수량·외부 치수·총중량이 포함됩니다.

상품에 저장된 최신 실측과 특정 입고에서 확인한 실측 결과를 구분합니다. 입고 내용을 확인할 때는 그 입고의 조회 결과를 사용합니다.

생성과 변경

상품을 등록하면 skuId를 받습니다. 이미 등록된 SKU라면 중복 생성 오류를 처리하고 기존 상품을 조회합니다. 상품 정보와 변경 이력, 최신 실측은 각각 해당 조회 API로 확인합니다.

상품 정보가 바뀌었다고 해서 이미 생성한 입고·출고 요청의 표시 정보까지 바뀌었다고 가정하지 않습니다. 필요한 업무의 상세를 다시 조회합니다.

연동 규칙

• sku와 skuId를 바꾸어 사용하지 않습니다. 각 API가 요구하는 필드를 확인합니다.
• Maybox ID는 문자열로 보관합니다. JavaScript number로 변환하지 않습니다.
• 상품 코드나 externalReference를 멱등 키 대신 사용하지 않습니다. 같은 업무 요청의 재시도는 같은 Idempotency-Key와 입력으로 처리합니다.
• 상품 정보·실측을 조회한 결과만으로 물건의 도착이나 재고 반영을 판단하지 않습니다.

관련 문서

• 입고 연동: SKU 등록과 기존 상품 조회
• 식별자와 업무 참조: ID·고객사 업무 번호 규칙
• 도착과 입고: 상품 요청과 창고 기록의 관계
• API 레퍼런스: 상품·변경 이력·실측 API