📡 URL API 레퍼런스

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

📌 인증

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

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://fplink.net/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://fplink.net/my-promo",
  "originalUrl": "https://example.com/landing-page",
  "title": "프로모션 랜딩",
  "clickCount": 0,
  "createdAt": "2026-01-15T14:30:00Z"
}

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 목록 배열 (각 항목은 URL 상세 참조)
page	Integer	현재 페이지 번호 (0부터 시작)
size	Integer	페이지 크기
totalElements	Long	전체 URL 수
totalPages	Integer	전체 페이지 수
first	Boolean	첫 번째 페이지 여부
last	Boolean	마지막 페이지 여부

cURL

curl "https://fplink.net/api/v1/service/urls?page=0&size=10&keyword=promo" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "content": [
    {
      "id": 123,
      "shortUrl": "https://fplink.net/my-promo",
      "originalUrl": "https://example.com/landing-page",
      "title": "프로모션 랜딩",
      "clickCount": 42,
      "createdAt": "2026-01-15T14:30:00Z",
      "expiresAt": null,
      "showAdPage": false,
      "goalType": "purchase"
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true
}

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

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

Path Parameters

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

Response

필드	타입	설명
id	Long	URL ID
shortUrl	String	완전한 단축 URL
originalUrl	String	원본 URL
title	String	URL 제목
clickCount	Long	클릭 수
createdAt	DateTime	생성 시간 (UTC)
expiresAt	DateTime	만료 시간 (UTC, 미설정 시 null)
showAdPage	Boolean	광고 페이지 표시 여부
ogTitle	String	OG 태그 제목
ogDescription	String	OG 태그 설명
ogImageUrl	String	OG 태그 이미지 URL
iosAppId	Long	연결된 iOS 앱 ID (미연결 시 null)
androidAppId	Long	연결된 Android 앱 ID (미연결 시 null)
utmSource	String	UTM Source
utmMedium	String	UTM Medium
utmTerm	String	UTM Term
utmContent	String	UTM Content
customDomainName	String	커스텀 도메인 이름 (미설정 시 null)
iosDeepLinkPath	String	iOS 딥링크 경로
androidDeepLinkPath	String	Android 딥링크 경로
mobileTargetUrl	String	모바일 대체 URL
goalType	String	전환 목표 유형

cURL

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

JSON

{
  "id": 123,
  "shortUrl": "https://fplink.net/my-promo",
  "originalUrl": "https://example.com/landing-page",
  "title": "프로모션 랜딩",
  "clickCount": 42,
  "createdAt": "2026-01-15T14:30:00Z",
  "expiresAt": null,
  "showAdPage": false,
  "iosAppId": null,
  "androidAppId": null,
  "utmSource": null,
  "utmMedium": null,
  "customDomainName": null,
  "goalType": "purchase"
}

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

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

cURL

curl -X PUT https://fplink.net/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://fplink.net/my-promo",
  "originalUrl": "https://example.com/new-landing",
  "createdAt": "2026-01-15T14:30:00Z"
}

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

단축 URL을 삭제합니다. 삭제된 URL의 단축 코드는 더 이상 접근할 수 없습니다.

Path Parameters

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

Response

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

cURL

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

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

필드	타입	설명
url	Object	URL 상세 정보 (URL 상세 조회와 동일)
chartLabels	Array	일별 클릭 차트 라벨 (날짜 문자열 배열)
chartData	Array	일별 클릭 차트 데이터 (숫자 배열)
hourlyChartLabels	Array	시간대별 차트 라벨 ("00:00"~"23:00")
hourlyChartData	Array	시간대별 클릭 데이터 (숫자 배열)
topReferrers	Array	유입 경로별 클릭 통계
topCountries	Array	국가별 클릭 통계
topBrowsers	Array	브라우저별 클릭 통계
topOsSystems	Array	운영체제별 클릭 통계
deviceTypeStats	Array	기기 유형별 클릭 통계 (Mobile, Desktop, Tablet)
meta	Object	메타 정보 (dataRetentionDays, actualStartDate, actualEndDate)

cURL

curl "https://fplink.net/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://fplink.net/api/v1/service/urls/123/qr" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "qrCode": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAA...",
  "shortUrl": "https://fplink.net/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://fplink.net/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 개요

캠페인 API →