📡 캠페인 API 레퍼런스

마케팅 캠페인 생성, 관리, 삭제 및 통계 조회 (7개 엔드포인트)

📌 인증

모든 Service API 요청에는 X-API-KEY 헤더를 포함해야 합니다. API Key는 콘솔 > 개발자 > API 키 관리에서 발급받을 수 있습니다. 공통 규칙은 API 개요를 참고하세요.

POST /api/v1/service/campaigns

새로운 마케팅 캠페인을 생성합니다.

Request Body

필드	타입	최대 길이	필수	설명
name	String	50	✅	캠페인 이름
alias	String	50		캠페인 별칭 (URL 경로에 사용, 영문/숫자/-, _만)
originalUrl	String	1000	✅	목적지 URL
iosAppId	Long	-		연결할 iOS 앱 ID (콘솔 > 모바일 앱 관리에서 확인)
androidAppId	Long	-		연결할 Android 앱 ID
expiresAt	String	-		만료 시간 (ISO-8601 형식)
goalType	String	50		전환 목표 유형 (purchase, signup, addToCart, productView, subscription, appInstall, formSubmit, contentView 또는 커스텀 값)

Response

필드	타입	설명
id	Long	캠페인 ID
name	String	캠페인 이름
alias	String	캠페인 별칭
originalUrl	String	목적지 URL
createdAt	DateTime	생성 시간

cURL

curl -X POST https://fplink.net/api/v1/service/campaigns \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "name": "신년 프로모션",
    "alias": "new-year-2026",
    "originalUrl": "https://example.com/promo",
    "goalType": "purchase"
  }'

JSON

{
  "id": 45,
  "name": "신년 프로모션",
  "alias": "new-year-2026",
  "originalUrl": "https://example.com/promo",
  "createdAt": "2026-01-15T14:30:00Z"
}

GET /api/v1/service/campaigns

생성한 캠페인 목록을 페이징하여 조회합니다.

Query Parameters

파라미터	타입	최대 길이	설명
page	Integer	-	페이지 번호 (0부터 시작, 기본: 0)
size	Integer	-	페이지 크기 (1~100, 기본: 20)
search	String	100	검색 키워드 (이름, 별칭 검색)
createdAfter	DateTime	-	이 시간 이후 생성된 캠페인 필터
createdBefore	DateTime	-	이 시간 이전 생성된 캠페인 필터

Response

필드	타입	설명
content[]	Array	캠페인 목록 배열 (각 항목은 캠페인 상세 참조)
page	Integer	현재 페이지 번호 (0부터 시작)
size	Integer	페이지 크기
totalElements	Long	전체 캠페인 수
totalPages	Integer	전체 페이지 수
first	Boolean	첫 번째 페이지 여부
last	Boolean	마지막 페이지 여부

cURL

curl "https://fplink.net/api/v1/service/campaigns?page=0&size=10&search=프로모션" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "content": [
    {
      "id": 45,
      "name": "신년 프로모션",
      "alias": "new-year-2026",
      "originalUrl": "https://example.com/promo",
      "createdAt": "2026-01-15T14:30:00Z",
      "updatedAt": "2026-01-20T09:15:00Z",
      "expiresAt": "2026-03-31T23:59:00Z",
      "iosAppId": 12,
      "iosAppName": "MyApp iOS",
      "iosAppIconUrl": null,
      "androidAppId": 15,
      "androidAppName": "MyApp Android",
      "androidAppIconUrl": null,
      "username": "john_doe",
      "utmSource": "email",
      "utmMedium": "campaign",
      "appPath": "myapp",
      "customDomainName": null,
      "iosDeepLinkPath": "/promo/new-year",
      "androidDeepLinkPath": "/promo/new-year",
      "clickCount": 42,
      "goalType": "purchase"
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true
}

GET /api/v1/service/campaigns/{id}

특정 캠페인의 상세 정보를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	캠페인 ID

Response

필드	타입	설명
id	Long	캠페인 ID
name	String	캠페인 이름
alias	String	캠페인 별칭
originalUrl	String	목적지 URL
createdAt	DateTime	생성 시간 (UTC)
updatedAt	DateTime	수정 시간 (UTC)
expiresAt	DateTime	만료 시간 (UTC, 미설정 시 null)
iosAppId	Long	연결된 iOS 앱 ID (미연결 시 null)
iosAppName	String	iOS 앱 이름
iosAppIconUrl	String	iOS 앱 아이콘 URL
androidAppId	Long	연결된 Android 앱 ID (미연결 시 null)
androidAppName	String	Android 앱 이름
androidAppIconUrl	String	Android 앱 아이콘 URL
username	String	생성자 사용자명
utmSource	String	UTM Source
utmMedium	String	UTM Medium
appPath	String	앱 경로 (URL 네임스페이스)
customDomainName	String	커스텀 도메인 이름 (미설정 시 null)
iosDeepLinkPath	String	iOS 딥링크 경로
androidDeepLinkPath	String	Android 딥링크 경로
clickCount	Long	클릭 수
goalType	String	전환 목표 유형

cURL

curl "https://fplink.net/api/v1/service/campaigns/45" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "id": 45,
  "name": "신년 프로모션",
  "alias": "new-year-2026",
  "originalUrl": "https://example.com/promo",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-20T09:15:00Z",
  "expiresAt": "2026-03-31T23:59:00Z",
  "iosAppId": 12,
  "iosAppName": "MyApp iOS",
  "iosAppIconUrl": null,
  "androidAppId": 15,
  "androidAppName": "MyApp Android",
  "androidAppIconUrl": null,
  "username": "john_doe",
  "utmSource": "email",
  "utmMedium": "campaign",
  "appPath": "myapp",
  "customDomainName": null,
  "iosDeepLinkPath": "/promo/new-year",
  "androidDeepLinkPath": "/promo/new-year",
  "clickCount": 42,
  "goalType": "purchase"
}

PUT /api/v1/service/campaigns/{id}

기존 캠페인의 정보를 수정합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	캠페인 ID

Request Body

필드	타입	최대 길이	설명
name	String	50	새 캠페인 이름
originalUrl	String	1000	새 목적지 URL
expiresAt	String	-	새 만료 시간 (null로 만료 해제)
goalType	String	50	전환 목표 유형

Response

캠페인 상세 조회와 동일한 전체 필드를 반환합니다.

cURL

curl -X PUT "https://fplink.net/api/v1/service/campaigns/45" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "name": "신년 프로모션 v2",
    "originalUrl": "https://example.com/promo-v2",
    "expiresAt": "2026-06-30T23:59",
    "goalType": "signup"
  }'

JSON

{
  "id": 45,
  "name": "신년 프로모션 v2",
  "alias": "new-year-2026",
  "originalUrl": "https://example.com/promo-v2",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-03-17T10:20:00Z",
  "expiresAt": "2026-06-30T23:59:00Z",
  "iosAppId": 12,
  "iosAppName": "MyApp iOS",
  "iosAppIconUrl": null,
  "androidAppId": 15,
  "androidAppName": "MyApp Android",
  "androidAppIconUrl": null,
  "username": "john_doe",
  "utmSource": "email",
  "utmMedium": "campaign",
  "appPath": "myapp",
  "customDomainName": null,
  "iosDeepLinkPath": "/promo/new-year",
  "androidDeepLinkPath": "/promo/new-year",
  "clickCount": 42,
  "goalType": "signup"
}

DELETE /api/v1/service/campaigns/{id}

캠페인을 삭제합니다. 삭제된 캠페인의 별칭은 더 이상 접근할 수 없습니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	삭제할 캠페인 ID

Response

성공 시 204 No Content를 반환합니다. 응답 본문은 없습니다.

cURL

curl -X DELETE https://fplink.net/api/v1/service/campaigns/45 \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/campaigns/{id}/stats

캠페인의 클릭 통계 및 사용자 추적 데이터를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	캠페인 ID

Query Parameters

파라미터	타입	최대 길이	설명
startDate	Date	-	시작일 (YYYY-MM-DD 형식)
endDate	Date	-	종료일 (YYYY-MM-DD 형식)
customId	String	100	사용자 추적 ID로 필터링 (cid 파라미터)

Response

필드	타입	설명
campaign	Object	캠페인 기본 정보 (id, name, alias, createdAt, expiresAt)
totalClicks	Long	전체 클릭 수
dailyClicks	Array	일별 클릭 통계 배열
hourlyClicks	Array	시간대별 클릭 통계 배열
userClicks	Array	사용자별(cid) 클릭 통계 배열
topCountries	Array	국가별 클릭 통계
topTrackers	Array	트래커별 클릭 통계
topBrowsers	Array	브라우저별 클릭 통계
topOs	Array	운영체제별 클릭 통계
topReferrers	Array	유입 경로별 클릭 통계
deviceTypeStats	Array	기기 유형별 클릭 통계 (Mobile, Desktop, Tablet)
revenueStats	Object	매출 통계 (totalRevenue, purchaseConversionRate, dailyRevenue 등)
meta	Object	메타 정보 (dataRetentionDays, actualStartDate, actualEndDate)

cURL

curl "https://fplink.net/api/v1/service/campaigns/45/stats?startDate=2026-01-01&endDate=2026-01-31&customId=user-001" \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/campaigns/{id}/app-install-stats

캠페인을 통한 앱 설치 통계를 조회합니다 (모바일 앱 연동 시).

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	캠페인 ID

Query Parameters

파라미터	타입	설명
startDate	Date	시작일 (YYYY-MM-DD 형식)
endDate	Date	종료일 (YYYY-MM-DD 형식)
timeZone	String	타임존 (예: Asia/Seoul)

Response

필드	타입	설명
period	String	조회 기간
appName	String	앱/캠페인 별칭
platform	String	플랫폼 필터 (All, iOS, Android)
totalInstalls	Long	전체 설치 수
iosInstalls	Long	iOS 설치 수
androidInstalls	Long	Android 설치 수
totalClicks	Long	전체 클릭 수
conversionRate	Double	클릭 대비 설치 전환율 (%)
dailyInstalls	Array	일별 설치 통계
platformStats	Array	플랫폼별 설치 통계
countryStats	Array	국가별 설치 통계
recentInstalls	Array	최근 설치 내역
reengagementStats	Object	리인게이지먼트 통계
funnelStats	Object	퍼널 통계 (딥링크 클릭 → 스토어 방문 → 설치 → 실행)
qualityStats	Object	딥링크 품질 통계

cURL

curl "https://fplink.net/api/v1/service/campaigns/45/app-install-stats?startDate=2026-01-01&endDate=2026-01-31&timeZone=Asia/Seoul" \
  -H "X-API-KEY: your-api-key"

← URL API

앱 API →