행동 데이터 연동하기

행동 데이터 서버 연동하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 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"
      },
      ...
    ]
}

필드 설명

필드	타입	설명
events	Array<object>	(필수) 행동 데이터 목록
↳ user_id	string	(필수) 유저 고유 ID
↳ event_type	string	(필수) 이벤트 타입
↳ captured_at	string	(필수) 이벤트 발생 시각 (ISO 8601 형식)
↳ event_properties	object	(선택) 이벤트에 포함된 속성 정보
• item_id	string	(선택) 상품 ID
• order_id	string	(선택) 주문 ID
• order_amount	number	(선택) 주문 금액
• paid_amount	number	(선택) 실제 결제 금액
• search_query	string	(선택) 검색 쿼리
• items	Array<object>	(선택) 복수 상품 목록 (여러 상품이 포함된 이벤트에 사용)
↳ id	string	(필수) 상품 ID
↳ price	number	(필수) 상품 단가
↳ quantity	number	(선택) 상품 수량
↳ custom_event_properties	object	(선택) 상품 단위 커스텀 속성 — item별로 추가 연동 필드를 붙일 때 사용
↳ custom_event_properties	object	(선택) 커스텀 이벤트 속성 — event_properties에 정의되지 않은 추가 연동 필드

제한 사항

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

상태 코드

코드	설명
200 OK	요청이 정상적으로 수락되어 SQS에 등록됨
400 Bad Request	필수 필드 누락, 잘못된 값 전달 시
400 Bad Request	인증 실패 (secret key 오류, errorCode: UnAuthorized)
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에 전송되었음을 의미합니다.

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