Referral Tracking
API 엔드포인트
서버 측 추천 추적 엔드포인트
추천 API 엔드포인트
서버 측 추천 추적을 선호하거나(또는 백엔드 전용 통합에 필요할 경우) JavaScript 추적 스크립트를 사용하는 대신 이 엔드포인트를 직접 호출할 수 있습니다.
모든 추천 엔드포인트는 CORS를 지원하며 API 키 인증이 필요하지 않습니다.
추천 캠페인 vs 제휴 캠페인: 추천 캠페인은 가입 및 구매 시 포인트를 부여합니다. 제휴 캠페인은 독점적인 지급 구조를 사용하여 추천된 구매에 대해 달러 커미션을 지급합니다 — 판매의 일정 비율 또는 판매당 고정 금액(둘 다 아님). 가입 추적은 제휴 캠페인에서 커미션을 지급하지 않습니다(구매 전용). 구매 응답에는 추천 모드의 pointsAwarded와 제휴 모드의 commissionAwarded가 포함됩니다.
추천 코드 검증
/api/referral/validate-code추천 코드가 유효한지 확인하고 추천인에 대한 정보를 가져옵니다.
쿼리 매개변수
codestring required 검증할 추천 코드
contestIdstring required 콘테스트 식별자
요청
curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"
응답
{
"valid": true,
"referrerEmail": "jane@example.com",
"referrerName": "Jane Doe",
"contestId": "clx1abc123"
}
방문 추적
/api/referral/track-visit추천 링크를 통해 누군가가 사이트를 방문했음을 기록합니다.
요청 본문
referralCodestring required URL에서 가져온 추천 코드
contestIdstring required 콘테스트 식별자
urlstring방문한 페이지 URL (선택 사항)
요청
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"
}'
응답
{
"success": true
}
가입 추적
/api/referral/track-signup추천 방문자가 가입했음을 기록합니다.
요청 본문
emailstring required 새 가입자의 이메일 주소
contestIdstring required 콘테스트 식별자
referralCodestring추천한 사람의 추천 코드 (직접 가입 시 선택 사항)
externalSiteUrlstring required 가입이 발생한 페이지 URL
namestring새 가입자의 이름 (선택 사항)
요청
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"
}'
응답
{
"success": true,
"data": {
"entryId": "entry_new789",
"isReferred": true,
"pointsAwarded": {
"advocate": 10,
"friend": 5
}
}
}
구매 추적
/api/referral/track-purchase추천받은 사용자가 구매를 완료했음을 기록합니다. blitzrocket.js의 RocketTracker.trackPurchase()에서 사용됩니다.
요청 본문
campaignIdstring required 콘테스트 식별자 (contestId와 동일)
referralCodestring required 추천인의 추천 코드
orderIdstring required 고유 주문 식별자
amountnumber required 구매 금액
externalSiteUrlstring required 구매가 발생한 페이지의 URL
emailstring구매자의 이메일 주소 (선택 사항)
phonestring구매자의 전화번호 (선택 사항)
currencystring통화 코드 (기본값: 'USD')
요청
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"
}'
응답
추천 캠페인 (포인트):
{
"success": true,
"message": "구매가 성공적으로 추적되었습니다",
"referrerEntryId": "entry_abc123",
"pointsAwarded": { "advocate": 50, "friend": 10 },
"commissionAwarded": { "advocate": 0 }
}
제휴 캠페인 (달러 커미션):
{
"success": true,
"message": "구매가 성공적으로 추적되었습니다",
"referrerEntryId": "entry_abc123",
"pointsAwarded": { "advocate": 0, "friend": 0 },
"commissionAwarded": { "advocate": 24.99 }
}
이메일 전용 구매 추적(요청에 추천 코드가 없는 경우)은 대신 POST /api/contest/track-purchase를 사용하세요.
완전한 서버 사이드 예제
서버에서 추천 추적을 구현하는 완전한 예제는 다음과 같습니다:
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 });
});