BuzzBooster 리워드 포스트백 연동 가이드

사용자에게 보상을 지급하기 위해서 포스트백(Postback) 연동이 필요합니다. 포스트백 요청은 보안을 위해 서버 간 통신(Server-to-server) 형태로 진행됩니다.

개요

버즈빌을 통해 사용자가 포인트를 지급받은 경우, 파트너사에게 이 사실을 전달하여 적립 요청을 보내기 위한 API입니다.

항목

내용

항목

내용

1

요청 방향

버즈빌 → 파트너사

2

HTTP Request method

POST - application/json

3

HTTP Request URL

파트너사 서버의 endpoint

4

HTTP Request Parameters

아래의 Http Request Parameters 표를 참고하세요.

5

HTTP Response Code

버즈빌 서버는 파트너사 서버로부터 전달받은 응답 코드(Response Code)를 바탕으로 성공 여부를 판단합니다.

  • 200/201(ok): 성공 처리

    • 파트너사 서버에서 요청을 제대로 처리한 경우의 응답 코드

  • 200/201 이외의 응답 코드: 실패 처리

body에 오류 내용을 담더라도 응답 코드가 다를 경우, 실패로 처리합니다

HTTP Request Parameters

기능에 따라서 두 종류의 포스트백이 존재합니다. 각 타입에 관한 포스트백 파라미터 정보는 아래의 표를 참고하세요.

  • String 타입의 파라미터 필드 값이 한국어일 경우에는 유니코드로 인코딩되어 전달됩니다.

  • Optional 필드는 파트너사가 일반적으로 사용하는 필드입니다. Optional 필드가 필요한 경우 버즈빌 담당자에게 연락하세요.

파라미터 필드(Field)

타입
(Type)

설명

파라미터 필드(Field)

타입
(Type)

설명

user_id

REQUIRED

String 
(max 255)

파트너사에서 정의한 유저의 식별 값입니다.

transaction_id

REQUIRED

String 
(UUID 형식)

포인트 지급에 발급되는 ID입니다.. 포인트 중복 지급을 방지하기 위해 사용합니다.

같은 transaction_id로 요청이 온 경우에는 반드시 포인트 중복 적립이 되지 않도록 처리해야 합니다.

points.point

REQUIRED

Integer

사용자에게 지급해야 하는 포인트입니다.

custom.campaign_id

Optional

String

(max 255)

포인트를 지급받게 된 캠페인의 ID입니다.

포인트 지급 내역을 보여주는 경우에 주로 사용합니다.

캠페인의 이름을 바로 사용하기 힘드신 경우에 주로 사용합니다.

custom.campaign_name

Optional

String

(max 255)

포인트를 지급받게 된 캠페인의 이름입니다.

포인트 지급 내역을 보여주는 경우에 주로 사용합니다.

custom.code

Optional

String

(max 255)

캠페인마다 별도로 지정할 수 있는 코드입니다.

포인트 지급 내역을 보여주는 경우에 주로 사용합니다.

custom.params

Optional

Array of String

(max 255)

캠페인마다 다르게 사용될 수 있는 파라미터입니다.

포인트 지급 기록 등에 더 자세한 정보를 추가하고 싶은 경우에 사용합니다.

 

OpenAPI Spec

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 openapi: 3.0.0 info: title: Partner's Give Point API description: 파트너가 꼭 구현해주어야하는 포인트 지급 API의 스펙입니다. version: 0.0.1 servers: - url: https://dev.example.com description: Development server - url: https://example.com description: Production server components: schemas: Point: type: object properties: point: type: integer description: 지급해야 하는 포인트 금액 example: 2 custom: type: object properties: campaign_id: type: string description: 포인트를 지급받게 된 캠페인의 ID example: "ad2c8e1f-4ae9-4e9f-90a3-78f1eb78fcbf" nullable: true campaign_name: type: string description: 포인트를 지급받게 된 캠페인 이름 example: "2월 연속 출석체크 캠페인" nullable: true code: type: string description: 캠페인 별로 지정할 수 있는 코드 example: "C023" nullable: true params: type: array description: 추가적으로 보내주는 파라미터들. 연속 출석 일수, 혹은 지금까지 초대한 친구의 인원수와 같이 캠페인 별로 다른 값이 보내진다. items: type: string paths: /points: post: operationId: GivePointsToUser description: 유저에게 포인트를 지급합니다. tags: - reward requestBody: description: 유저에게 포인트를 지급하기 위한 정보들이 포함되어있습니다. required: true content: application/json: schema: type: object properties: transaction_id: type: string format: UUID v4 description: 디버깅, 중복 지급 방지를 위한 요청마다 부여되는 고유한 ID user_id: type: string points: type: array description: "여러 리워드가 같은 시점에 생성될 수 있습니다. 이 경우 points에 list형태로 모아서 지급됩니다." items: $ref: '#/components/schemas/Point' responses: '201': description: 포인트 지급이 성공하였습니다. '4XX': description: 올바르지 않은 요청으로 인하여 포인트 지급이 실패하였습니다. '5XX': description: 예상치 못한 문제로 인하여 포인트 지급이 실패하였습니다. tags: - name: reward description: reward 지급을 위한 API

 

커스텀 파라미터

커스텀 이벤트를 포스트백으로 전송하기 위해서는 미리 추가 연동 작업을 진행해야 합니다. 따라서 사전에 반드시 버즈빌에 문의하시기 바랍니다.