BuzzBooster V1 API 연동 스펙

Step 1. URL 등록

dashboard > reward manager > settings > integration > SDK 탭에서 아래와 같이 포인트 지급을 처리할 URL 을 등록해주세요.

포인트 API URL 등록 화면

포인트 지급 API URL 은 환경별(dev, prod)로 세팅할 수 있습니다.

V1 spec 에서는 등록한 URL 뒤에 buzzbooster 내에서 자체적으로 /points 를 붙여서 요청을 보냅니다.

예시) https://booster.buzzvil.com/rewards 로 등록한 경우, https://booster.buzzvil.com/rewards/points 로 지급 요청을 보냅니다

입력 후 “저장” 버튼을 클릭하여 등록을 완료합니다.

Step 2. 도메인 등록 요청, 방화벽 설정

등록한 URL에 대해 buzzbooster 자체적으로 해당 URL 에 대해 도메인 등록 작업이 필요하기 때문에 도메인 공유 절차가 필요합니다? 또한, 방화벽 설정을 위해 버즈빌의 고정 아이피 주소를 화이트리스팅 처리해주세요.

Step 3. API 구현

buzzbooster 내에서 포인트 지급이 발생한 경우, 버즈부스터는 아래의 spec 으로 Step 1 에서 등록한 URL에 자체적으로 /points 를 붙여 POST요청을 전송하고, 쿠폰의 경우 /coupons 를 붙여 POST요청을 보냅니다. 요청 수신 후, 포인트 지급및 쿠폰 지급을 처리할 수 있도록 아래 spec을 구현해주세요.

[POST] /points

BuzzBooster Request

Request Parameter

종류	파라미터명	타입	값
Header	Content-Type	string	application/json

Request Body

파라미터명	타입	설명
transaction_id	string	포인트 지급/차감에 발급되는 ID입니다. 포인트 중복 지급/차감을 방지하기 위해 사용합니다. 같은 transaction_id로 요청이 온 경우에는 반드시 포인트 중복 적립/차감이 되지 않도록 처리해야 합니다.
user_id	string	파트너사에서 정의한 유저의 식별값입니다.
points	array	적립/차감 해야되는 포인트 금액 배열 입니다. 여러 리워드가 동시발생하여 지급/차감될 수 있습니다.
custom	object	적립 요청에는 유저가 참여한 캠페인 ID와 이름, 차감 요청에는 차감 사유가 포함됩니다.

JSON

{
    "transaction_id": "2195ffb0-8f64-44b2-8c85-4723b9ecb18a",
    "user_id": "USER_123456789",
    "points": [
				{
						"point": 10,
						"custom": {
								"campaign_id": "1234-567890-abcd-efgh"
								"campaign_name": "대시보드에서 설정한 캠페인 이름"
						}
				},
				{
						"point": -1500,
						"custom": {
								"reason": "네이버페이 포인트 전환"
						}
				},
    ],
}

[POST] /coupons

BuzzBooster Request

Request Parameter

종류	파라미터명	타입	값
Header	Content-Type	string	application/json

Request Body

파라미터명	타입	설명
transaction_id	string	포인트 지급/차감에 발급되는 ID입니다. 포인트 중복 지급/차감을 방지하기 위해 사용합니다. 같은 transaction_id로 요청이 온 경우에는 반드시 포인트 중복 적립/차감이 되지 않도록 처리해야 합니다.
user_id	string	파트너사에서 정의한 유저의 식별값입니다.
coupon	object	지급해야하는 쿠폰 객체입니다.
coupon.code	string	지급해야하는 쿠폰 코드로 쿠폰의 식별자입니다. 최대 250자까지 지원합니다.(ascii)
amount	integer	지급해야하는 쿠폰의 수량입니다.

JSON

{
    "transaction_id": "2195ffb0-8f64-44b2-8c85-4723b9ecb18a",
    "user_id": "USER_123456789",
    "coupon": {
      "code": "ABC123",
    },
    "amount": 2
}

Retry Policy

적립/차감에 실패 시 응답 코드가 500번대(501 Not Implemented 제외) 또는 429 Too Many Requests라면, 200 OK, 201 Created 혹은 409 Conflict 를 응답받을 때까지 BuzzBooster 서버에서 동일한 request body로 최대 4회 재시도합니다.

Partner Response

200, 201 - 포인트 적립/차감이 성공한 경우

4xx - 올바르지 않은 요청으로 인하여 포인트 적립/차감이 실패한 경우

409 - 이미 정상 처리된 트랜잭션이 중복 요청된 경우

5xx - 예상치 못한 문제로 인하여 포인트 적립/차감이 실패한 경우

Step 3. 연동 테스트(포인트만 가능)

dashboard > reward manager > settings > integration > SDK 탭 의 각 환경별 “적립 테스트” 버튼을 클릭하여 연동이 완료되었는지 테스트할 수 있습니다. 테스트 결과는 dashboard > reward manager > reward admin > 포인트 지급 내역 에서 확인할 수 있습니다.