개발자 문서외부 재고 API
재고현황 목록
위치 범위·검색·재고 상태별 SKU 현재고를 페이지 단위로 조회합니다.
Endpoint
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/external/inventory-status |
| 인증 | Authorization: Bearer <developer-key> |
| 응답 단위 | SKU |
Query parameters
| Query | 타입 | 설명 |
|---|---|---|
scopeLocationId | UUID | root·section·leaf ID. 선택한 하위 tree만 집계 |
q | string | 상품명, SKU 코드/명, 바코드 부분 검색 |
stockState | enum | all(기본), in_stock(0 초과), empty(0 이하) |
limit | integer | 1~100, 기본 50 |
cursor | string | 이전 응답의 page.nextCursor를 그대로 전달 |
요청
curl --fail-with-body \
"$API_BASE_URL/v1/external/inventory-status?scopeLocationId=$LOCATION_ID&stockState=in_stock&limit=50" \
-H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
-H "Accept: application/json"응답
{
"locations": [{
"id": "location-uuid",
"name": "시흥 센터",
"code": "SIHEUNG",
"childCount": 2,
"leafLocationIds": ["leaf-uuid-1", "leaf-uuid-2"],
"skuCount": 120,
"totalQuantity": 530,
"averageQuantityPerSku": 4.4167
}],
"summary": {
"skuCount": 120,
"totalQuantity": 530,
"averageQuantityPerSku": 4.4167
},
"items": [{
"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" },
"totalQuantity": 12,
"locationQuantities": { "location-uuid": 12 }
}],
"page": { "nextCursor": "eyJ2Ijox..." }
}해석 규칙
locations는 조회 범위에 포함된 root별 요약입니다.leafLocationIds는 해당 root에서 이번 요청 범위에 포함된 실제 leaf 위치 ID입니다. 전체 조회에서는 root 전체 leaf가, section 조회에서는 선택 section 아래 leaf가 들어갑니다.locationQuantities의 key는 root location ID입니다. leaf별 상세 수량이 필요하면 SKU 재고 상세를 사용하세요.summary는 현재 페이지가 아니라 필터에 맞는 전체 결과 기준입니다.items만 페이지 단위로 반환됩니다. 다음 페이지가 있으면page.nextCursor를 같은 필터에 전달하세요.limit은 바꿀 수 있지만 다른 필터는 유지해야 합니다.
목록에는 exact skuId query를 추가하지 않았습니다. 특정 SKU 하나를 안정적으로 조회할 때는 items[].id를 SKU 재고 상세의 path parameter로 사용하세요.