상품 추천 연동하기

콘솔에서 만든 추천 슬롯의 추천 상품을 실시간으로 받아 웹·앱 화면에 노출하는 API입니다. 추천 연동 키로 추천을 요청하면, 그 유저에게 맞는 상품 ID 목록을 돌려줍니다.

엔드포인트

POST https://recsys-api-realtime.blux.ai/v1/applications/{APPLICATION_ID}/slots/{SLOT_KEY}/recommend

경로 파라미터	설명
APPLICATION_ID	애플리케이션 ID
SLOT_KEY	추천 연동 키. 콘솔 관리 > 상품 추천에서 슬롯에 지정한 값입니다.

활성화된 슬롯만 응답합니다. 비활성·임시저장 슬롯이거나 없는 추천 연동 키로 요청하면 404가 반환됩니다.

인증

요청 시 Authorization 헤더에 애플리케이션 secret key를 포함합니다.

Authorization: {SECRET_KEY}

secret key는 서버 사이드 전용 비밀 키입니다. 브라우저 등 외부에 노출하지 말고, 추천 요청은 고객사 서버에서 호출하세요.

요청 본문

{
  "blux_user_id": "BLUX_USER_ID",
  "item_ids": ["ITEM_ID"],
  "category_id": "CATEGORY_ID",
  "brand_id": "BRAND_ID",
  "limit": 10,
  "offset": 0
}

필드	타입	설명
blux_user_id	string	(선택) 추천을 받을 유저의 블럭스 내부 ID. 개인화 추천에 사용합니다. 미지정 시 콜드 유저 추천으로 동작합니다.
item_ids	Array<string>	(선택) 기준 상품 ID 목록. 함께 본 상품 추천·유사 상품 추천처럼 입력 상품이 필요한 슬롯에서 사용합니다. 상품 하나만 전달할 때도 길이 1짜리 배열로 넣습니다.
category_id	string	(선택) 호출별 조건에서 카테고리를 호출 시 전달값으로 좁힐 때 사용합니다.
brand_id	string	(선택) 호출별 조건에서 브랜드를 호출 시 전달값으로 좁힐 때 사용합니다.
limit	number	(선택, 기본값 10) 받을 추천 상품 수. 1~1000 범위입니다.
offset	number	(선택, 기본값 0) 페이지네이션 오프셋.

입력 상품이 필요한 슬롯에서 item_ids를 비우면, 슬롯의 입력 상품이 유저 행동 기반일 때 blux_user_id의 가장 최근 행동 상품을 자동으로 기준 상품으로 사용합니다.

응답

{
  "item_ids": ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"],
  "metadata": {}
}

필드	타입	설명
item_ids	Array<string>	추천 상품 ID 목록. 추천 순서대로 정렬됩니다.
metadata	object	추천 관련 부가 정보.

응답은 상품 ID만 돌려줍니다. 화면에 노출할 상품명·가격·이미지 등 상세 정보는 고객사 상품 데이터에서 채워 주세요.

상태 코드

코드	설명
200 OK	추천 상품을 정상적으로 반환
401 Unauthorized	인증 실패 (secret key 누락·오류)
404 Not Found	없는 애플리케이션이거나, 추천 연동 키에 해당하는 활성 슬롯이 없음
412 Precondition Failed	추천 후보 캐시가 아직 준비되지 않음. 일시적 상태이므로 잠시 후 재시도하세요.
502 Bad Gateway	추천 엔진 일시 오류. 잠시 후 재시도하세요.

테스트 예시

curl -X POST https://recsys-api-realtime.blux.ai/v1/applications/abcd1234/slots/main_home/recommend \
  -H "Authorization: xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "blux_user_id": "blux-user-1",
    "limit": 10
  }'

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