Referral Tracking

API 엔드포인트

서버 측 추천 추적 엔드포인트

추천 API 엔드포인트

서버 측 추천 추적을 선호하거나(또는 백엔드 전용 통합에 필요할 경우) JavaScript 추적 스크립트를 사용하는 대신 이 엔드포인트를 직접 호출할 수 있습니다.

모든 추천 엔드포인트는 CORS를 지원하며 API 키 인증이 필요하지 않습니다.

추천 캠페인 vs 제휴 캠페인: 추천 캠페인은 가입 및 구매 시 포인트를 부여합니다. 제휴 캠페인은 독점적인 지급 구조를 사용하여 추천된 구매에 대해 달러 커미션을 지급합니다 — 판매의 일정 비율 또는 판매당 고정 금액(둘 다 아님). 가입 추적은 제휴 캠페인에서 커미션을 지급하지 않습니다(구매 전용). 구매 응답에는 추천 모드의 pointsAwarded와 제휴 모드의 commissionAwarded가 포함됩니다.


추천 코드 검증

GET/api/referral/validate-code
No authentication required

추천 코드가 유효한지 확인하고 추천인에 대한 정보를 가져옵니다.

쿼리 매개변수

codestring required

검증할 추천 코드

contestIdstring required

콘테스트 식별자

요청

bash
curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"

응답

json
{
  "valid": true,
  "referrerEmail": "jane@example.com",
  "referrerName": "Jane Doe",
  "contestId": "clx1abc123"
}

방문 추적

POST/api/referral/track-visit
No authentication required

추천 링크를 통해 누군가가 사이트를 방문했음을 기록합니다.

요청 본문

referralCodestring required

URL에서 가져온 추천 코드

contestIdstring required

콘테스트 식별자

urlstring

방문한 페이지 URL (선택 사항)

요청

bash
curl -X POST https://blitzrocket.com/api/referral/track-visit \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123",
    "url": "https://yoursite.com/landing-page"
  }'

응답

json
{
  "success": true
}

가입 추적

POST/api/referral/track-signup
No authentication required

추천 방문자가 가입했음을 기록합니다.

요청 본문

emailstring required

새 가입자의 이메일 주소

contestIdstring required

콘테스트 식별자

referralCodestring

추천한 사람의 추천 코드 (직접 가입 시 선택 사항)

externalSiteUrlstring required

가입이 발생한 페이지 URL

namestring

새 가입자의 이름 (선택 사항)

요청

bash
curl -X POST https://blitzrocket.com/api/referral/track-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "externalSiteUrl": "https://yoursite.com/signup"
  }'

응답

json
{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

구매 추적

POST/api/referral/track-purchase
No authentication required

추천받은 사용자가 구매를 완료했음을 기록합니다. blitzrocket.jsRocketTracker.trackPurchase()에서 사용됩니다.

요청 본문

campaignIdstring required

콘테스트 식별자 (contestId와 동일)

referralCodestring required

추천인의 추천 코드

orderIdstring required

고유 주문 식별자

amountnumber required

구매 금액

externalSiteUrlstring required

구매가 발생한 페이지의 URL

emailstring

구매자의 이메일 주소 (선택 사항)

phonestring

구매자의 전화번호 (선택 사항)

currencystring

통화 코드 (기본값: 'USD')

요청

bash
curl -X POST https://blitzrocket.com/api/referral/track-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "orderId": "order-12345",
    "amount": 99.99,
    "currency": "USD",
    "externalSiteUrl": "https://yoursite.com/checkout/success",
    "email": "buyer@example.com"
  }'

응답

추천 캠페인 (포인트):

json
{
  "success": true,
  "message": "구매가 성공적으로 추적되었습니다",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 50, "friend": 10 },
  "commissionAwarded": { "advocate": 0 }
}

제휴 캠페인 (달러 커미션):

json
{
  "success": true,
  "message": "구매가 성공적으로 추적되었습니다",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 0, "friend": 0 },
  "commissionAwarded": { "advocate": 24.99 }
}

이메일 전용 구매 추적(요청에 추천 코드가 없는 경우)은 대신 POST /api/contest/track-purchase를 사용하세요.


완전한 서버 사이드 예제

서버에서 추천 추적을 구현하는 완전한 예제는 다음과 같습니다:

javascript
const express = require("express");
const app = express();

const BLITZROCKET_BASE = "https://blitzrocket.com/api/referral";
const CONTEST_ID = process.env.CONTEST_ID;

app.post("/api/signup", async (req, res) => {
  const { email, name, referralCode } = req.body;

  // 1. 시스템에서 사용자 생성
  const user = await createUser({ email, name });

  // 2. Blitz Rocket에서 추천 가입 추적
  if (referralCode) {
    await fetch(`${BLITZROCKET_BASE}/track-signup`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        name,
        contestId: CONTEST_ID,
        referralCode,
      }),
    });
  }

  res.json({ success: true, user });
});

app.post("/api/purchase", async (req, res) => {
  const { email, orderId, amount, currency } = req.body;

  // 1. 시스템에서 구매 처리
  const order = await processOrder({ email, orderId, amount });

  // 2. Blitz Rocket에서 구매 추적
  await fetch(`${BLITZROCKET_BASE}/track-purchase`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email,
      contestId: CONTEST_ID,
      orderId,
      amount,
      currency,
    }),
  });

  res.json({ success: true, order });
});