📡 Service API 레퍼런스

서버 간 통합을 위한 REST API 엔드포인트 명세입니다. 모든 요청에 X-API-KEY 헤더가 필요합니다.

📌 인증

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

URL API

단축 URL 생성, 조회, 수정 및 통계 조회 (7개 엔드포인트)

POST /api/v1/service/urls

새로운 단축 URL을 생성합니다.

Request Body

필드	타입	최대 길이	필수	설명
url	String	1000	✅	원본 URL (https://로 시작하는 유효한 URL)
customAlias	String	50		사용자 지정 단축 코드 (영문, 숫자, -, _만 허용)
title	String	200		URL 제목
iosAppId	Long	-		연결할 iOS 앱 ID (콘솔 > 모바일 앱 관리에서 확인)
androidAppId	Long	-		연결할 Android 앱 ID
expirationDate	String	-		만료 시간 (ISO-8601 형식)
showAdPage	Boolean	-		광고 페이지 표시 여부 (기본: false)
goalType	String	50		전환 목표 유형 (purchase, signup, addToCart, productView, subscription, appInstall, formSubmit, contentView 또는 커스텀 값)

Response

필드	타입	설명
id	Long	생성된 URL의 고유 ID
shortUrl	String	완전한 단축 URL
originalUrl	String	원본 URL
title	String	URL 제목
clickCount	Long	클릭 수 (초기값: 0)
createdAt	DateTime	생성 시간

cURL

curl -X POST https://fpl-stage-console.kissoft.biz/api/v1/service/urls \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "url": "https://example.com/landing-page",
    "customAlias": "my-promo",
    "title": "프로모션 랜딩",
    "goalType": "purchase"
  }'

JSON

{
  "id": 123,
  "shortUrl": "https://fpl-stage-console.kissoft.biz/my-promo",
  "originalUrl": "https://example.com/landing-page",
  "title": "프로모션 랜딩",
  "clickCount": 0,
  "createdAt": "2026-01-15T14:30:00"
}

GET /api/v1/service/urls

생성한 단축 URL 목록을 페이징하여 조회합니다.

Query Parameters

파라미터	타입	최대 길이	설명
page	Integer	-	페이지 번호 (0부터 시작, 기본: 0)
size	Integer	-	페이지 크기 (1~100, 기본: 20)
keyword	String	100	검색 키워드 (URL, 단축코드 검색)
showAdPage	Boolean	-	광고 페이지 표시 URL만 필터
createdAfter	DateTime	-	이 시간 이후 생성된 URL 필터
createdBefore	DateTime	-	이 시간 이전 생성된 URL 필터

Response

필드	타입	설명
content	Array	URL 목록 배열
totalElements	Long	전체 개수
totalPages	Integer	전체 페이지 수
number	Integer	현재 페이지 번호

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/urls?page=0&size=10&keyword=promo" \
  -H "X-API-KEY: your-api-key"

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

특정 단축 URL의 상세 정보를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	URL ID

Response

필드	타입	설명
id	Long	URL ID
shortUrl	String	완전한 단축 URL
originalUrl	String	원본 URL
clickCount	Long	클릭 수
createdAt	DateTime	생성 시간
expiresAt	DateTime	만료 시간 (없으면 null)

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

기존 단축 URL의 정보를 수정합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	URL ID

Request Body

필드	타입	최대 길이	설명
originalUrl	String	1000	새 원본 URL
expirationDate	String	-	새 만료 시간 (null로 만료 해제)
showAdPage	Boolean	-	광고 페이지 표시 여부
goalType	String	50	전환 목표 유형

Response

필드	타입	설명
id	Long	URL ID
shortUrl	String	완전한 단축 URL
originalUrl	String	수정된 원본 URL
createdAt	DateTime	생성 시간

cURL

curl -X PUT https://fpl-stage-console.kissoft.biz/api/v1/service/urls/123 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "originalUrl": "https://example.com/new-landing",
    "goalType": "signup"
  }'

JSON

{
  "id": 123,
  "shortUrl": "https://fpl-stage-console.kissoft.biz/my-promo",
  "originalUrl": "https://example.com/new-landing",
  "createdAt": "2026-01-15T14:30:00Z"
}

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

단축 URL의 클릭 통계를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	URL ID

Query Parameters

파라미터	타입	필수	설명
startDate	Date		시작일 (YYYY-MM-DD 형식)
endDate	Date		종료일 (YYYY-MM-DD 형식)

Response

필드	타입	설명
totalClicks	Long	전체 클릭 수
dailyClicks	Array	일별 클릭 통계 배열
topCountries	Array	국가별 클릭 Top 10
topBrowsers	Array	브라우저별 클릭 Top 10
topDevices	Array	기기별 클릭 통계

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/urls/123/stats?startDate=2026-01-01&endDate=2026-01-31" \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/urls/{id}/qr

단축 URL에 대한 QR 코드를 생성합니다.

🔒 플랜 제한

이 엔드포인트는 PRO 플랜 이상에서만 사용할 수 있습니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	URL ID

Response

필드	타입	설명
qrCode	String	QR 코드 이미지 (Base64 인코딩)
shortUrl	String	단축 URL

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/urls/123/qr" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "qrCode": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAA...",
  "shortUrl": "https://fpl-stage-console.kissoft.biz/my-promo"
}

💡 QR 코드 이미지 사용법

응답의 qrCode 값은 PNG 이미지의 Base64 인코딩 문자열입니다. data:image/png;base64, 접두사를 붙여 HTML에서 바로 표시할 수 있습니다.

HTML

<img src="data:image/png;base64,{qrCode 값}" alt="QR Code" />

JavaScript

const img = document.createElement('img');
img.src = 'data:image/png;base64,' + response.qrCode;
document.body.appendChild(img);

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

단축 URL을 통한 앱 설치 통계를 조회합니다 (모바일 앱 연동 시).

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	URL ID

Query Parameters

파라미터	타입	필수	설명
startDate	Date		시작일 (YYYY-MM-DD 형식)
endDate	Date		종료일 (YYYY-MM-DD 형식)

Response

필드	타입	설명
period	String	조회 기간
appName	String	앱/URL 별칭
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://fpl-stage-console.kissoft.biz/api/v1/service/urls/123/app-install-stats?startDate=2026-01-01&endDate=2026-01-31" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "period": "2026-01-01 ~ 2026-01-31",
  "appName": "my-promo",
  "platform": "All",
  "totalInstalls": 152,
  "iosInstalls": 87,
  "androidInstalls": 65,
  "totalClicks": 1240,
  "conversionRate": 12.26,
  "dailyInstalls": [],
  "platformStats": [],
  "countryStats": [],
  "recentInstalls": [],
  "reengagementStats": {
    "totalReengagements": 0,
    "successfulReengagements": 0,
    "successRate": 0.0,
    "uniqueReengagedUsers": 0,
    "platformDistribution": { "ios": 0, "android": 0, "other": 0 }
  },
  "funnelStats": {
    "totalSessions": 0,
    "completedSessions": 0,
    "overallConversionRate": 0.0,
    "stages": [
      { "stageName": "딥링크 클릭", "stageOrder": 1, "sessionsReached": 0, "conversionRate": 0.0 },
      { "stageName": "스토어 방문", "stageOrder": 2, "sessionsReached": 0, "conversionRate": 0.0 },
      { "stageName": "앱 설치", "stageOrder": 3, "sessionsReached": 0, "conversionRate": 0.0 },
      { "stageName": "앱 실행", "stageOrder": 4, "sessionsReached": 0, "conversionRate": 0.0 }
    ]
  },
  "qualityStats": {
    "totalAttempts": 0,
    "successfulResolutions": 0,
    "successRate": 0.0,
    "fingerprintMatchRate": 0.0,
    "failureReasons": []
  }
}

캠페인 API

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

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://fpl-stage-console.kissoft.biz/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:00"
}

GET /api/v1/service/campaigns

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

Query Parameters

파라미터	타입	최대 길이	설명
page	Integer	-	페이지 번호 (0부터 시작, 기본: 0)
size	Integer	-	페이지 크기 (1~100, 기본: 20)
search	String	100	검색 키워드 (이름, 별칭 검색)

Response

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

cURL

curl "https://fpl-stage-console.kissoft.biz/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",
      "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 앱 이름
androidAppId	Long	연결된 Android 앱 ID (미연결 시 null)
androidAppName	String	Android 앱 이름
username	String	생성자 사용자명
utmSource	String	UTM Source
utmMedium	String	UTM Medium
appPath	String	앱 경로 (URL 네임스페이스)
customDomainName	String	커스텀 도메인 이름 (미설정 시 null)
iosDeepLinkPath	String	iOS 딥링크 경로
androidDeepLinkPath	String	Android 딥링크 경로
goalType	String	전환 목표 유형

cURL

curl "https://fpl-stage-console.kissoft.biz/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",
  "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://fpl-stage-console.kissoft.biz/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",
  "goalType": "signup"
}

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

필드	타입	설명
totalClicks	Long	전체 클릭 수
userClicks	Array	사용자별 클릭 통계 배열
dailyClicks	Array	일별 클릭 통계 배열
topCountries	Array	국가별 클릭 Top 10

cURL

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

모바일 앱 통계 API

모바일 앱 통계 조회 (읽기 전용, 3개 엔드포인트)

GET /api/v1/service/mobile-apps

등록된 모바일 앱 목록을 조회합니다 (읽기 전용).

Query Parameters

파라미터	타입	필수	설명
page	Integer		페이지 번호 (0부터 시작, 기본: 0)
size	Integer		페이지 크기 (1~100, 기본: 20)

Response

Spring Page 응답 형식으로 반환됩니다.

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

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/mobile-apps?page=0&size=10" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "content": [
    {
      "id": 12,
      "appName": "MyApp iOS",
      "platform": "IOS",
      "appIconUrl": "https://example.com/icon.png",
      "bundleId": "com.example.myapp",
      "path": "myapp",
      "apiKey": "mak_a1b2c3d4e5f6...",
      "scheme": "myapp://",
      "teamId": "ABC123DEF4",
      "storeUrl": "https://apps.apple.com/app/id123456789"
    },
    {
      "id": 15,
      "appName": "MyApp Android",
      "platform": "ANDROID",
      "appIconUrl": "https://example.com/icon-android.png",
      "bundleId": "com.example.myapp",
      "path": "myapp",
      "apiKey": "mak_f6e5d4c3b2a1...",
      "scheme": "myapp://",
      "teamId": null,
      "storeUrl": "https://play.google.com/store/apps/details?id=com.example.myapp"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "size": 10,
  "number": 0,
  "first": true,
  "last": true
}

GET /api/v1/service/mobile-apps/{id}

특정 모바일 앱의 상세 정보를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	앱 ID

Response

필드	타입	설명
id	Long	앱 ID
appName	String	앱 이름
platform	String	플랫폼 (IOS 또는 ANDROID)
appIconUrl	String	앱 아이콘 URL
bundleId	String	Bundle ID (iOS) / Package Name (Android)
path	String	고유 경로 (URL 네임스페이스)
apiKey	String	모바일 SDK 연동 API 키
scheme	String	URL 스킴 (딥링크용)
teamId	String	Apple Team ID (iOS 전용, Android는 null)
storeUrl	String	앱 스토어/플레이스토어 URL

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/mobile-apps/12" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "id": 12,
  "appName": "MyApp iOS",
  "platform": "IOS",
  "appIconUrl": "https://example.com/icon.png",
  "bundleId": "com.example.myapp",
  "path": "myapp",
  "apiKey": "mak_a1b2c3d4e5f6...",
  "scheme": "myapp://",
  "teamId": "ABC123DEF4",
  "storeUrl": "https://apps.apple.com/app/id123456789"
}

GET /api/v1/service/mobile-apps/{id}/install-stats

모바일 앱의 설치 및 클릭 통계를 조회합니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	✅	앱 ID

Query Parameters

파라미터	타입	필수	설명
startDate	Date		시작일 (YYYY-MM-DD 형식)
endDate	Date		종료일 (YYYY-MM-DD 형식)

Response

필드	타입	설명
totalInstalls	Long	전체 설치 수
totalClicks	Long	전체 클릭 수
conversionRate	Double	전환율 (%)
dailyStats	Array	일별 통계 배열

cURL

curl "https://fpl-stage-console.kissoft.biz/api/v1/service/mobile-apps/5/install-stats?startDate=2026-01-01&endDate=2026-01-31" \
  -H "X-API-KEY: your-api-key"

← API 개요

웹훅 연동 가이드 →