외부 시스템 연동외부 재고 API
SKU 재고 상세
특정 SKU의 전체 수량, 선택한 위치의 수량, 재고 반영 상태를 조회합니다.
Endpoint
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/external/inventory-status/{skuId} |
| 인증 | Authorization: Bearer <developer-key> |
Path parameter
| Parameter | 타입 | 설명 |
|---|---|---|
skuId | UUID | 재고현황 목록의 items[].id |
Query parameter
| Query | 타입 | 설명 |
|---|---|---|
scopeLocationId | UUID | 조회할 상위 위치·구역·최하위 위치의 ID |
요청
API 연동 시작하기의 환경 변수를 설정하세요. SKU_ID는 재고현황 목록의 items[].id, LOCATION_ID는 위치 목록의 id입니다. 전체 위치를 조회하려면 scopeLocationId를 생략합니다.
curl --fail-with-body \
"$API_BASE_URL/v1/external/inventory-status/$SKU_ID?scopeLocationId=$LOCATION_ID" \
-H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
-H "Accept: application/json"응답
{
"sku": {
"id": "sku-uuid",
"code": "STYLE-001-BLK-M",
"skuCode": "CUSTOM-001",
"name": "Black / M",
"barcode": "8800000000000",
"unit": "개",
"product": { "id": "product-uuid", "name": "Basic Tee", "brand": "Superfid" },
"options": { "색상": "Black", "사이즈": "M", "definition-uuid": "Black" },
"optionItems": [
{ "definitionId": "definition-uuid", "name": "색상", "value": "Black", "position": 0 },
{ "definitionId": "size-definition-uuid", "name": "사이즈", "value": "M", "position": 1 }
]
},
"selectedQuantity": 12,
"totalQuantity": 27,
"locations": [{
"id": "leaf-uuid-1",
"name": "기본 구역",
"code": "DEFAULT",
"parentId": "location-uuid",
"quantity": 12,
"freshness": {
"status": "clean",
"lastReplayedAt": "2026-09-18T01:23:45.000Z",
"lastSourceKind": "event"
}
}]
}해석 규칙
selectedQuantity:scopeLocationId가 있으면 선택 범위의 수량, 없으면 전체 수량입니다.totalQuantity: 워크스페이스에서 조회 가능한 전체 위치의 수량입니다.locations: 위치별 수량과 재고 반영 상태입니다. 상위 위치의 합계와 하위 위치의 수량을 다시 더하면 중복 계산됩니다.freshness.status가dirty,rebuilding,failed이면 최신 기록이 수량에 모두 반영되지 않았을 수 있습니다. 연동 화면에 반영 상태를 표시하세요.freshness가null이면 해당 위치의 재고 projection 상태 행이 없는 것이며, 위치 상세 API 오류를 뜻하지 않습니다. 보통 재고를 직접 집계하는 최하위가 아닌 상위 위치에서 나타납니다.options는 기존 호환용 object로 정의 ID와 정의 이름을 모두 키로 사용하고 순서를 보장하지 않습니다. 정의 ID와 표시 순서가 필요하면optionItems배열을 사용하세요.
SKU 이름이나 상품명을 연동 키로 저장하지 말고 sku.id를 사용하세요.