Superfid Docs

위치와 SKU별로 확정된 재고 실사 수량과 차이를 조회합니다.

Endpoint

항목	값
Method	`GET`
Path	`/v1/external/counts`
인증	`Authorization: Bearer <developer-key>`
응답 단위	실사 session × 위치 × SKU 1건

미확정·취소된 실사는 반환하지 않습니다.

Query parameters

Query	타입	설명
`scopeLocationId`	UUID	위치·구역·상위 위치 ID. 해당 위치와 하위 위치의 실사를 조회
`skuId`	UUID	특정 SKU의 실사만 조회
`countTypeCode`	string	실사 종류의 안정적인 코드
`occurredFrom`	ISO-8601 timestamp	실사 업무 시각의 시작 범위(포함)
`occurredTo`	ISO-8601 timestamp	실사 업무 시각의 끝 범위(포함)
`limit`	integer	1~100, 기본 50
`cursor`	string	이전 응답의 `page.nextCursor`

요청

curl --fail-with-body \
  "$API_BASE_URL/v1/external/counts?scopeLocationId=$LOCATION_ID&occurredFrom=2026-10-01T00%3A00%3A00Z&limit=50" \
  -H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
  -H "Accept: application/json"

응답

{
  "items": [{
    "id": "count-item-uuid",
    "scanSessionId": "session-uuid",
    "countType": { "code": "regular", "name": "정기 실사" },
    "scope": "selected_skus",
    "inputMode": "rfid",
    "location": { "id": "location-uuid", "name": "기본 구역", "code": "DEFAULT", "deletedAt": null },
    "sku": { "id": "sku-uuid", "code": "STYLE-001-BLK-M", "skuCode": null, "name": "Black / M" },
    "observedQuantity": 8,
    "bookQuantityBefore": 10,
    "varianceQuantity": -2,
    "varianceDirection": "out",
    "note": "재실사 반영",
    "occurredAt": "2026-10-16T08:30:00.000Z",
    "confirmedAt": "2026-10-16T08:35:00.000Z",
    "recordedAt": "2026-10-16T08:35:01.000Z",
    "actorUserId": "user-id",
    "approvedByUserId": "user-id",
    "device": null
  }],
  "page": { "nextCursor": null }
}

해석과 페이지 이동

observedQuantity는 실사에서 센 절대 수량입니다. bookQuantityBefore는 확정 직전 장부 수량이며 varianceQuantity는 observedQuantity - bookQuantityBefore입니다.
varianceDirection은 차이의 방향입니다. in은 장부보다 많음, out은 적음, none은 차이 없음입니다. 부호가 있는 수량 차이는 varianceQuantity를 사용하세요.
occurredAt은 업무 발생 시각, confirmedAt은 확정 시각, recordedAt은 실사 항목이 기록된 시각입니다. 페이지 순서는 opaque cursor가 정합니다.
다음 페이지가 있으면 같은 필터와 page.nextCursor를 전달하세요. limit은 바꿀 수 있습니다. 커서는 워크스페이스와 필터에 묶여 있습니다.
위치 범위는 각 요청 시점의 위치 트리에서 하위 위치를 확장합니다. 페이지를 읽는 동안 위치 계층을 바꾸면 기존 cursor 순회 결과가 달라질 수 있으므로 처음부터 다시 조회하세요.
응답은 확정된 실사만 포함하며 실사 이력을 재고 이벤트 API의 이동 이벤트와 별도로 처리하세요.

확정된 재고 실사

Endpoint

Query parameters

요청

응답

해석과 페이지 이동

On this page