메인 콘텐츠로 건너뛰기

​
엔드포인트

POST /api/openapi/v1/data/events

​
개요

OneSight 데이터 수집 API는 스키마-프리 방식으로 동작합니다. event_type으로 데이터 종류를 구분하고, payload에 자유로운 JSON 데이터를 전송할 수 있습니다.

​
요청

​
Headers

헤더필수설명
AuthorizationOBearer {API_KEY}
Content-TypeOapplication/json

​
Body

{
  "events": [
    {
      "event_type": "uwb_location",
      "event_id": "loc_20260412_001",
      "source": "virtual_store_server",
      "payload": {
        "customer_id": "cust_123",
        "position": {"x": 12.5, "y": 8.3, "z": 1.2},
        "zone": "produce_section",
        "accuracy_cm": 15,
        "timestamp": "2026-04-12T10:30:00Z"
      }
    },
    {
      "event_type": "pos_transaction",
      "event_id": "txn_20260412_001",
      "source": "pos_system",
      "payload": {
        "transaction_id": "TXN001",
        "store_id": "store_001",
        "items": [
          {"sku": "A001", "name": "Golden Curry", "qty": 1, "price": 298}
        ],
        "total": 298,
        "payment_method": "credit_card",
        "timestamp": "2026-04-12T10:35:00Z"
      }
    }
  ]
}
필드타입필수설명
eventsarrayO이벤트 배열 (최대 1,000건/요청)
events[].event_typestringO이벤트 유형 (예: uwb_location, pos_transaction)
events[].event_idstringX중복 방지 키 (idempotency)
events[].sourcestringX데이터 출처 (예: ios_app, pos_system)
events[].payloadobjectO실제 데이터 (자유 형식 JSON)

​
응답

{
  "success": true,
  "data": {
    "received": 2,
    "event_ids": ["uuid-1", "uuid-2"]
  }
}

​
이벤트 타입 예시

​
UWB 위치 추적

{
  "event_type": "uwb_location",
  "payload": {
    "customer_id": "cust_123",
    "position": {"x": 12.5, "y": 8.3, "z": 1.2},
    "floor": 1,
    "zone": "electronics",
    "accuracy_cm": 15,
    "timestamp": "2026-04-12T10:30:00Z"
  }
}

​
POS 거래

{
  "event_type": "pos_transaction",
  "payload": {
    "transaction_id": "TXN001",
    "store_id": "store_001",
    "customer_id": "cust_123",
    "items": [
      {"sku": "ELEC-001", "name": "USB-C Cable", "qty": 1, "price": 15.99}
    ],
    "subtotal": 15.99,
    "total": 17.43,
    "payment_method": "credit_card",
    "timestamp": "2026-04-12T10:35:00Z"
  }
}

​
존 트리거 이벤트

{
  "event_type": "zone_trigger",
  "payload": {
    "customer_id": "cust_123",
    "zone": "deli_section",
    "trigger_type": "enter",
    "timestamp": "2026-04-12T10:32:00Z"
  }
}

​
상품 스캔

{
  "event_type": "product_scan",
  "payload": {
    "customer_id": "cust_123",
    "barcode": "4901777304314",
    "product_name": "S&B Golden Curry",
    "price": 298,
    "timestamp": "2026-04-12T10:33:00Z"
  }
}

​
Idempotency

event_id를 포함하면 동일한 이벤트가 중복 저장되지 않습니다. 같은 event_id로 재전송하면 기존 레코드가 유지됩니다. 
{
  "event_type": "pos_transaction",
  "event_id": "txn_20260412_001",
  "payload": { ... }
}

​
이벤트 조회

GET /api/openapi/v1/data/events?event_type=pos_transaction&from=2026-04-01&to=2026-04-12&limit=100
파라미터타입설명
event_typestring이벤트 유형 필터
fromdate시작일 (ISO 8601)
todate종료일 (ISO 8601)
limitinteger최대 반환 건수 (기본: 100)
offsetinteger오프셋 (기본: 0)
데이터 수집 API의 구체적인 이벤트 타입 스키마는 프로젝트별로 별도 협의하여 정의합니다. 위 예시는 스마트 리테일 시나리오 기준입니다.