개발자 문서외부 재고 API
SKU 재고 상세
특정 SKU의 전체·선택 범위 수량과 위치별 projection 상태를 조회합니다.
Endpoint
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/external/inventory-status/{skuId} |
| 인증 | Authorization: Bearer <developer-key> |
Path parameter
| Parameter | 타입 | 설명 |
|---|---|---|
skuId | UUID | 재고현황 목록 items[].id의 stable SKU ID |
Query parameter
| Query | 타입 | 설명 |
|---|---|---|
scopeLocationId | UUID | 선택 범위. root·section·leaf ID |
요청
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" }
},
"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: workspace에서 조회 가능한 전체 위치의 수량입니다.locations: 위치별 수량과 projection freshness입니다. 부모와 leaf를 다시 합산해 중복 계산하지 마세요.freshness.status가dirty,rebuilding,failed이면 최신 스캔 반영 상태를 별도로 표시하세요.
SKU 이름이나 상품명을 연동 키로 저장하지 말고 sku.id를 사용하세요.