Superfid Docs

특정 SKU의 입출고와 확정된 재고 실사 결과를 시간순으로 조회합니다.

Endpoint

항목	값
Method	`GET`
Path	`/v1/external/inventory-status/{skuId}/history`
인증	`Authorization: Bearer <developer-key>`

Parameters

위치	Parameter	타입	설명
path	`skuId`	UUID	재고현황 목록의 `items[].id`
query	`scopeLocationId`	UUID	상위 위치·구역·최하위 위치 ID. 선택한 범위만 반환
query	`limit`	integer	1~100, 기본 20
query	`cursor`	string	이전 응답의 `page.nextCursor`

요청

API 연동 시작하기의 환경 변수를 설정하세요. SKU_ID는 재고현황 목록의 items[].id, LOCATION_ID는 위치 목록의 id입니다. 전체 위치의 이력을 조회하려면 scopeLocationId를 생략합니다.

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: 확정된 재고 실사 결과입니다.
direction: in, out, none 중 하나입니다.
quantity: 0 이상의 변동 수량 크기입니다. 양수·음수 부호는 direction으로 해석하세요. in이면 더하고 out이면 빼며, none이면 변동이 없습니다. 실사 기록의 quantity도 장부 수량과 실사 수량 차이의 절대 크기입니다. 직전 재고가 10개이고 관측 수량이 8개이면 direction: "out", quantity: 2, observedQuantity: 8입니다.
observedQuantity: 실사에서 관측한 수량입니다. 입출고 기록에서는 null입니다.
occurredAt 내림차순으로 반환됩니다. 다음 페이지가 있으면 같은 skuId와 scopeLocationId에 page.nextCursor를 그대로 전달하세요.

이 API는 SKU 하나의 재고 변동 이력을 조회합니다. 원시 이벤트 전체 내보내기나 updatedSince 조건을 이용한 변경분 내보내기는 지원하지 않습니다.

SKU 재고 변동 이력

Endpoint

Parameters

요청

응답

이력 해석

On this page