외부 시스템 연동외부 재고 API
재고현황 목록
위치 범위·검색·재고 상태별 SKU 현재고를 페이지 단위로 조회합니다.
Endpoint
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/external/inventory-status |
| 인증 | Authorization: Bearer <developer-key> |
| 응답 단위 | SKU |
| 페이지 크기 | 1~100개 SKU |
Query parameters
| Query | 타입 | 설명 |
|---|---|---|
scopeLocationId | UUID | 상위 위치·구역·최하위 위치 ID. 선택한 위치와 하위 위치만 집계 |
q | string | 상품명, SKU 코드/명, 바코드 부분 검색 |
stockState | enum | all(기본), in_stock(0 초과), empty(0 이하) |
limit | integer | 1~100, 기본 50 |
cursor | string | 이전 응답의 page.nextCursor를 그대로 전달 |
요청
API 연동 시작하기의 환경 변수를 설정하고, LOCATION_ID에 위치·구역 목록의 id를 넣으세요. 전체 워크스페이스를 조회하려면 scopeLocationId를 생략합니다.
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", "definition-uuid": "Black" },
"optionItems": [
{ "definitionId": "definition-uuid", "name": "색상", "value": "Black", "position": 0 },
{ "definitionId": "size-definition-uuid", "name": "사이즈", "value": "M", "position": 1 }
],
"totalQuantity": 12,
"locationQuantities": { "location-uuid": 12 }
}],
"page": { "nextCursor": "eyJ2Ijox..." }
}해석 규칙
locations는 조회 범위에 포함된 최상위 위치별 요약입니다.leafLocationIds는 이번 조회 범위에 포함된 최하위 위치 ID입니다. 전체 조회에서는 해당 상위 위치의 모든 최하위 위치가, 구역 조회에서는 선택한 구역 아래의 최하위 위치가 들어갑니다.locationQuantities의 키는 최상위 위치 ID입니다. 최하위 위치별 상세 수량이 필요하면 SKU 재고 상세를 사용하세요.summary는 현재 페이지가 아니라 필터에 맞는 전체 결과 기준입니다.items만 페이지 단위로 반환됩니다. 2페이지부터는 첫 응답의page.nextCursor를 같은 필터에 전달하세요.limit은 바꿀 수 있지만 다른 필터는 유지해야 합니다.options는 기존 호환용 object입니다. 정의 ID와 정의 이름이 모두 키로 들어가며 순서를 보장하지 않습니다. 안정적인 옵션 식별자와 표시 순서가 필요하면optionItems를 사용하세요.
특정 SKU 하나를 조회하려면 items[].id를 SKU 재고 상세의 skuId로 사용하세요. 이 목록 API에서는 skuId 검색 조건을 지원하지 않습니다.