본문으로 건너뛰기

행동 데이터 연동하기

행동 데이터 서버 연동하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 secret key를 사용해서 행동 데이터를 연동할 수 있습니다.

행동 데이터 서버 연동 API​

엔드포인트​

POST https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/events/bulk

인증​

요청 시 Authorization 헤더에 발급받은 secret key를 포함해야 합니다:

Authorization: {SECRET_KEY}

요청 본문​

{
  "events": [
      {
        "user_id": "USER_ID",
        "event_type": "offline_order",
        "event_properties": {
          "item_id": "ITEM_ID",
          "order_id": "ORDER_ID",
          "order_amount": 21000,
          "paid_amount": 18000
        },
        "custom_event_properties": {
          "location": "seoul",
          "payment_method": "cash"
        },
        "captured_at": "2025-11-03T05:01:02.849Z"
      },
      ...
    ]
}

필드 설명​

필드타입필수설명
eventsArray<object>필수행동 데이터 목록
  ↳ user_idstring필수유저 고유 ID
  ↳ event_typestring필수이벤트 타입
  ↳ captured_atstring필수이벤트 발생 시각 (ISO 8601 형식)
  ↳ event_propertiesobject선택이벤트에 포함된 속성 정보
    • item_idstring선택상품 ID
    • order_idstring선택주문 ID
    • order_amountnumber선택주문 금액
    • paid_amountnumber선택실제 결제 금액
    • search_querystring선택검색 쿼리
    • itemsArray<object>선택복수 상품 목록 (여러 상품이 포함된 이벤트에 사용)
      ↳ idstring선택상품 ID
      ↳ pricenumber선택상품 단가
      ↳ quantitynumber선택상품 수량
      ↳ custom_event_propertiesobject선택상품 단위 커스텀 속성 — item별로 추가 연동 필드를 붙일 때 사용
  ↳ custom_event_propertiesobject선택커스텀 이벤트 속성 — event_properties에 정의되지 않은 추가 연동 필드

제한 사항​

  • 한 요청당 최대 events 수: 1000개
  • 권장 요청 속도: 초당 최대 100건
  • 내부적으로 AWS Lambda 및 Kinesis Data Stream 기반으로 처리됩니다

상태 코드​

코드설명
200 OK요청이 정상적으로 수락되어 SQS에 등록됨
400 Bad Request필수 필드 누락, 잘못된 값 전달 시
401 Unauthorized인증 실패 (secret key 오류)
500 Internal Server Error서버 내부 오류

테스트 예시​

curl -X POST https://api.blux.ai/prod/v2/applications/abcd1234/events/bulk \
  -H "Authorization: xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "user_id": "blux-test",
        "event_type": "offline_order",
        "event_properties": {
          "item_id": "ITEM_ID",
          "order_id": "ORDER_ID",
          "order_amount": 21000,
          "paid_amount": 18000
        },
        "custom_event_properties": {
          "location": "seoul",
          "payment_method": "cash"
        },
        "captured_at": "2025-11-03T05:01:02.849Z"
      },
      ...
    ]
  }'

200 OK를 반환하면 행동 데이터가 성공적으로 Kinesis Data Stream에 전송되었음을 의미합니다.



추가 문의는 블럭스 기술지원팀에 연락주세요.