개발자 문서외부 재고 API
SKU 재고 변동 이력
특정 SKU의 movement와 확정 SET을 하나의 시간축으로 조회합니다.
Endpoint
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/external/inventory-status/{skuId}/history |
| 인증 | Authorization: Bearer <developer-key> |
Parameters
| 위치 | Parameter | 타입 | 설명 |
|---|---|---|---|
| path | skuId | UUID | 이력을 조회할 stable SKU ID |
| query | scopeLocationId | UUID | root·section·leaf 범위. 선택 범위만 반환 |
| query | limit | integer | 1~100, 기본 20 |
| query | cursor | string | 이전 응답의 page.nextCursor |
요청
curl --fail-with-body \
"$API_BASE_URL/v1/external/inventory-status/$SKU_ID/history?scopeLocationId=$LOCATION_ID&limit=20" \
-H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
-H "Accept: application/json"응답
{
"items": [{
"kind": "set",
"occurredAt": "2026-09-18T01:23:45.000Z",
"direction": "out",
"quantity": 2,
"locationId": "leaf-uuid-1",
"locationName": "기본 구역",
"locationCode": "DEFAULT",
"eventId": null,
"eventTypeCode": null,
"eventTypeName": null,
"setSessionId": "session-uuid",
"setTypeCode": "regular",
"observedQuantity": 8,
"note": "재실사 반영"
}],
"page": { "nextCursor": "eyJ2Ijox..." }
}이력 해석
kind: movement: 입출고 이벤트입니다.kind: set: 확정된 inventory SET입니다.direction:in,out,none중 하나입니다.quantity: 해당 row의 변동량입니다. SET의 경우 관측된 절대 재고가 아니라 직전 projection 대비 delta입니다.observedQuantity: SET 당시 실사에서 관측한 절대 수량입니다.occurredAt내림차순으로 반환됩니다. 다음 페이지가 있으면 같은skuId와scopeLocationId에page.nextCursor를 그대로 전달하세요.
이 endpoint는 SKU 단위 운영 이력 조회입니다. 원시 이벤트 전체 export나 updatedSince 증분 export는 제공하지 않습니다.