메인 콘텐츠로 건너뛰기
이 API는 Client SDK 키(osk_ 접두사)로 인증합니다. 데이터 수집 API(서버→OneSight)와는 반대 방향으로, 서버가 클라이언트에게 푸시하는 이벤트를 폴링합니다.

​
엔드포인트

GET /v1/persona/{persona_id}/events

​
개요

이벤트 폴링 API는 백엔드에서 클라이언트로 전달해야 하는 모든 푸시성 정보를 단일 채널로 제공합니다.
  • Zone 진입 알림: 매장 내 특정 코너 진입 시 알림
  • 프로모션: Flash Deal, 할인 정보
  • 결제 상태: 결제 요청 → 처리 중 → 완료/실패

​
요청

​
쿼리 파라미터

파라미터타입필수설명
zonestringX현재 진입한 매장 Zone (예: wine, meat). 생략 시 zone 무관 이벤트만 반환

​
Zone 종류

Zone설명
processed_food가공식품
fresh_produce신선 채소
meat정육
wine주류
bakery베이커리
checkout계산대

​
응답

​
Zone 프로모션 이벤트

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_flash_001",
        "event_type": "zone_promo",
        "expires_at": "2026-04-16T12:00:00Z",
        "blocks": [
          {
            "type": "promo_card",
            "header": "Flash Deal",
            "title": "가공식품 코너",
            "subtitle": "카레라이스 특별 할인",
            "image_url": "https://cdn.example.com/products/house-curry.jpg",
            "badge": "50% OFF",
            "price": 2450,
            "original_price": 4900,
            "actions": [
              { "id": "claim_coupon", "label": "쿠폰 받기", "style": "primary" },
              { "id": "dismiss_event", "label": "다음에", "style": "text" }
            ]
          }
        ]
      }
    ]
  }
}

​
Zone 진입 알림

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_zone_enter_wine_001",
        "event_type": "zone_entered",
        "zone": "wine",
        "expires_at": "2026-04-16T11:00:00Z",
        "blocks": [
          {
            "type": "text",
            "content": "와인 코너에 오셨군요! 카레와 어울리는 와인을 골라드릴까요?"
          },
          {
            "type": "suggestion",
            "content": "가성비 좋은 까베르네 소비뇽을 추천드릴 수 있습니다.",
            "actions": [
              { "id": "recommend_wine", "label": "추천받기", "style": "primary" },
              { "id": "skip_wine", "label": "괜찮아요", "style": "secondary" }
            ]
          }
        ]
      }
    ]
  }
}

​
결제 상태 이벤트

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_pay_001",
        "event_type": "payment_state",
        "state": "COMPLETED",
        "order_id": "ORD-2026.04.16-A14:23",
        "amount": 42600,
        "blocks": [
          {
            "type": "result_card",
            "status": "success",
            "title": "결제가 완료되었습니다!",
            "message": "주문번호 ORD-2026.04.16-A14:23"
          }
        ]
      }
    ]
  }
}

​
이벤트 없음

{
  "success": true,
  "data": {
    "events": []
  }
}

​
이벤트 타입

타입설명
zone_promoZone 프로모션 (Flash Deal 등)
zone_enteredZone 진입 알림
payment_state결제 상태 변경

​
결제 상태

상태설명
REQUESTED결제 요청 접수
PROCESSING결제사 처리 중
COMPLETED결제 완료
FAILED결제 실패

​
결제 실패 코드

코드설명
INSUFFICIENT_BALANCE잔액/한도 부족
CARD_DECLINED카드 거절
TIMEOUT시간 초과
USER_CANCELLED사용자 취소
UNKNOWN알 수 없는 오류

​
블록 타입

타입설명
promo_card프로모션 카드 (이미지, 가격, 할인)
text텍스트 메시지
image이미지
product_list상품 목록
suggestionAI 추천/제안
result_card결과 카드 (성공/실패/정보)
info_box안내 박스

​
동작 방식

  • 이벤트는 한 번만 반환됩니다 (조회 후 consumed 처리)
  • expires_at이 지난 이벤트는 자동으로 제외됩니다
  • event_id로 클라이언트 측 중복 방지 (dedupe) 가능
  • 주기적 폴링을 권장합니다 (2~5초 간격)

​
코드 예제

​
curl

# Zone 지정 폴링
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events?zone=wine" \
  -H "Authorization: Bearer $SDK_KEY"

# Zone 미지정 폴링 (범용 이벤트만)
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events" \
  -H "Authorization: Bearer $SDK_KEY"

​
Swift (iOS) — 타이머 기반 폴링

Timer.scheduledTimer(withTimeInterval: 3.0, repeats: true) { _ in
    let url = URL(string: "https://api.ones1ght.com/v1/persona/\(personaId)/events?zone=\(currentZone)")!
    var request = URLRequest(url: url)
    request.setValue("Bearer \(sdkKey)", forHTTPHeaderField: "Authorization")

    URLSession.shared.dataTask(with: request) { data, _, _ in
        guard let data = data,
              let result = try? JSONDecoder().decode(EventsResponse.self, from: data) else { return }

        for event in result.data.events {
            handleEvent(event)  // UI 업데이트
        }
    }.resume()
}