개발자를 위한 FINGERPUSH.LINK API 연동 가이드

마케터가 매번 수동으로 URL을 만들 필요 없습니다

이커머스에서 매일 새로운 상품이 올라올 때마다 마케터가 콘솔에 접속해서 단축 URL을 만들고 계시나요?

FINGERPUSH.LINK의 Service API를 사용하면 시스템이 자동으로 단축 URL을 생성합니다. CMS에서 상품을 등록하면 자동으로 마케팅 링크가 만들어지고, 광고 시스템에 바로 연동됩니다.

API 인증 방식

API 키는 콘솔 → 설정 → API 키 관리에서 발급됩니다.

핵심 API 3가지

1. 단축 URL 생성

가장 많이 사용하는 API입니다. 긴 URL을 짧게 만듭니다.

curl -X POST https://fplink.net/api/v1/service/urls \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://shop.example.com/product/12345",
    "alias": "summer-shoes",
    "title": "여름 신발 특가",
    "expiresAt": "2026-06-30T23:59:59"
  }'

응답 예시:

{
  "shortUrl": "https://fplink.net/summer-shoes",
  "shortCode": "summer-shoes",
  "originalUrl": "https://shop.example.com/product/12345",
  "createdAt": "2026-04-02T10:00:00"
}

2. 클릭 통계 조회

생성한 URL의 클릭 데이터를 조회합니다.

curl -X GET "https://fplink.net/api/v1/service/urls/{shortCode}/stats?period=7d" \
  -H "X-API-KEY: your-api-key"

응답에 포함되는 데이터:

• 총 클릭 수 / 유니크 클릭 수
• 일별 클릭 추이
• 디바이스별 (데스크톱, 모바일, 태블릿)
• 브라우저별 / OS별
• 국가·지역별
• 리퍼러(유입 경로)별

3. 캠페인 단축 URL 생성

캠페인에 연결된 링크를 만들면 UTM 파라미터가 자동 부여됩니다.

curl -X POST https://fplink.net/api/v1/service/campaigns/{campaignId}/urls \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://shop.example.com/sale",
    "channelId": "instagram-story"
  }'

캠페인 안에서 채널별로 다른 channelId를 부여하면, 같은 캠페인의 채널별 성과를 분리해서 볼 수 있습니다.

실전 연동 시나리오

시나리오 1: 이커머스 상품 등록 자동화

상품 CMS에서 신상품 등록
    ↓
서버에서 FINGERPUSH.LINK API 호출
    ↓
단축 URL 자동 생성 (fplink.net/product-12345)
    ↓
광고 플랫폼에 자동 등록 / SNS 자동 포스팅

시나리오 2: 이메일 마케팅 개인화

회원 DB에서 추천 상품 목록 추출
    ↓
상품별 단축 URL 일괄 생성 (API batch 호출)
    ↓
이메일 템플릿에 개인화 링크 삽입
    ↓
발송 후 클릭 통계 API로 반응률 분석

시나리오 3: 오프라인 매장 QR코드 관리

각 매장별 프로모션 URL 생성 (API)
    ↓
QR 코드 자동 생성 → 매장별 전단지 인쇄
    ↓
통계 API로 매장별 스캔 수 비교
    ↓
성과 좋은 매장에 전단지 추가 배포

언어별 코드 예제

Python

import requests

API_KEY = "your-api-key"
BASE_URL = "https://fplink.net/api/v1/service"

response = requests.post(
    f"{BASE_URL}/urls",
    headers={
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "originalUrl": "https://shop.example.com/product/12345",
        "alias": "summer-shoes"
    }
)

data = response.json()
print(f"단축 URL: {data['shortUrl']}")

JavaScript (Node.js)

const response = await fetch('https://fplink.net/api/v1/service/urls', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    originalUrl: 'https://shop.example.com/product/12345',
    alias: 'summer-shoes'
  })
});

const data = await response.json();
console.log(`단축 URL: ${data.shortUrl}`);

Java (Spring)

RestTemplate restTemplate = new RestTemplate();

HttpHeaders headers = new HttpHeaders();
headers.set("X-API-KEY", "your-api-key");
headers.setContentType(MediaType.APPLICATION_JSON);

Map<String, String> body = Map.of(
    "originalUrl", "https://shop.example.com/product/12345",
    "alias", "summer-shoes"
);

HttpEntity<Map<String, String>> request = new HttpEntity<>(body, headers);
ResponseEntity<Map> response = restTemplate.postForEntity(
    "https://fplink.net/api/v1/service/urls",
    request,
    Map.class
);

System.out.println("단축 URL: " + response.getBody().get("shortUrl"));

Rate Limit & 에러 처리

Rate Limit 초과 시 429 Too Many Requests 응답이 반환됩니다. Retry-After 헤더를 확인하고 재시도하세요.

일반적인 에러 코드:

정리