Superfid Docs

위치 범위와 기간으로 입출고 이벤트를 조회하고 SKU별 수량 라인을 이어서 가져옵니다.

Endpoint

항목	값
Method	`GET`
Path	`/v1/external/events`
인증	`Authorization: Bearer <developer-key>`
응답 단위	inventory event 1건

Query parameters

Query	타입	설명
`scopeLocationId`	UUID	위치·구역·상위 위치 ID. 해당 위치와 하위 위치의 이벤트를 조회
`eventTypeCode`	string	이벤트 종류의 안정적인 코드
`direction`	`in` \| `out`	입고 또는 출고
`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/events?scopeLocationId=$LOCATION_ID&occurredFrom=2026-10-01T00%3A00%3A00Z&limit=50" \
  -H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
  -H "Accept: application/json"

응답

{
  "items": [{
    "id": "event-uuid",
    "eventType": { "code": "IN_PURCHASE", "name": "구매 입고", "direction": "in", "isCustom": false },
    "location": { "id": "location-uuid", "name": "시흥 센터", "code": "SIHEUNG", "deletedAt": null },
    "occurredAt": "2026-10-16T08:30:00.000Z",
    "recordedAt": "2026-10-16T08:31:02.000Z",
    "actorUserId": "user-id",
    "scanSessionId": "session-uuid",
    "device": { "id": "device-uuid", "name": "창고 단말 1", "model": null },
    "lineMode": "sku_quantity",
    "lineCount": 2,
    "totalQuantity": 15
  }],
  "page": { "nextCursor": "eyJ2Ijox..." }
}

해석과 페이지 이동

eventType.code를 연동 키로 사용하세요. name은 표시용이며 사용자 지정 종류는 알 수 없는 새 코드가 추가될 수 있습니다.
occurredAt은 업무 발생 시각이고, recordedAt은 서버에 기록된 시각입니다. 페이지 순서는 recordedAt이나 occurredAt이 아니라 opaque cursor가 정합니다.
lineCount는 원본 이벤트 줄 또는 EPC 태그 수입니다. totalQuantity는 수량 줄의 합이며, EPC 이벤트에서는 각 태그를 1개로 셉니다.
한 응답에는 이벤트만 포함됩니다. SKU별 수량은 이벤트 수량 라인에서 조회하세요.
다음 페이지가 있으면 같은 위치·종류·방향·기간 필터와 함께 page.nextCursor를 전달하세요. limit은 바꿀 수 있습니다. 커서는 워크스페이스와 필터에 묶여 있으므로 다른 조건에 재사용하면 400 오류가 납니다.
위치 범위는 각 요청 시점의 위치 트리에서 하위 위치를 확장합니다. 페이지를 읽는 동안 위치 계층을 바꾸면 기존 cursor 순회 결과가 달라질 수 있으므로 처음부터 다시 조회하세요.
이벤트가 아직 처리 중인 쓰기 작업에 속해 있으면 해당 작업이 완료된 뒤 조회됩니다. 모든 페이지가 한 시점의 고정된 재고 스냅샷을 뜻하지는 않습니다.

이 API는 이벤트 원장의 일부 안전한 필드만 제공합니다. EPC 원문, 파트너, 원가·판매가, 임의 metadata는 반환하지 않습니다.

위치별 재고 이벤트

Endpoint

Query parameters

요청

응답

해석과 페이지 이동

On this page