비볼디 단축 URL 개발자 API
비볼디 개발자 API는 REST API와 JSON 응답 기반으로 단축 URL 생성, 링크 관리, 클릭 통계 조회 기능을 다양한 서비스와 시스템에 연동할 수 있도록 제공합니다.
모든 API는 JSON 기반 응답 구조를 제공하며 JavaScript, Python, Java, PHP, Android, iOS 등 HTTP 요청을 지원하는 다양한 개발 환경에서 쉽게 연동할 수 있습니다.
API 인증
모든 API 요청에는 Authorization 헤더에 API 키가 필요합니다. API 키는 대시보드의 개발자 API 페이지에서 발급받을 수 있습니다.
Authorization: APIKey {Your API Key}주의 사항 (HTTP 403)
원인: 일부 비식별 User-Agent는 보안 정책상 차단될 수 있습니다.
해결: 고유 User-Agent를 회사명 또는 브랜드명으로 명확하게 지정하세요.
User-Agent: MyBrand
모든 API 요청에는 호출 실패시 자동 재시도 로직을 포함하는 것을 권장합니다.
비볼디 개발자 API란?
비볼디 개발자 API는 웹사이트, 모바일 앱, 내부 시스템 등 다양한 환경에서 단축 URL 생성 및 링크 관리 기능을 직접 연동할 수 있도록 제공되는 REST API입니다.
단순 링크 생성뿐 아니라 클릭 통계 조회, 링크 그룹 관리, QR 코드 생성, 쿠폰 및 스탬프 기능 등 다양한 비볼디 기능을 API로 자동화할 수 있습니다.
주요 활용 사례
- 마케팅 자동화 시스템에서 캠페인별 단축 URL 자동 생성
- 이커머스 플랫폼에서 상품 링크 공유 최적화
- 사내 시스템에서 클릭 통계 수집 및 리포트 자동화
- 모바일 앱에서 딥링크와 단축 URL을 결합한 앱 설치 유도
- SNS, 문자, 이메일 발송용 링크 관리 자동화
API 사용 전 준비 사항
비볼디 API를 사용하려면 계정 생성과 API 키 발급이 필요합니다.
발급된 API 키를 Authorization 헤더에 포함하여 HTTPS 기반 REST API를 호출할 수 있습니다.
1단계 — 비볼디 계정 생성
비볼디 회원가입 후 무료 플랜에서도 API 기능을 사용할 수 있습니다.
유료 플랜에서는 더 높은 API 호출 한도와 고급 옵션 등을 지원합니다.
2단계 — API 키 발급
로그인 후 대시보드의 개발자 API 페이지에서 API 키를 발급받을 수 있습니다.
API 키는 외부에 노출되지 않도록 서버 환경 변수 또는 백엔드 서버에서 안전하게 관리하는 것을 권장합니다.
3단계 — 첫 번째 API 호출 테스트
발급받은 API 키를 Authorization 헤더에 포함하여 아래 엔드포인트로 POST 요청을 보내면 단축 URL을 생성할 수 있습니다.
준비가 완료되면 아래 API 호출 방법과 샘플 코드를 참고하여 다양한 서비스 환경에 연동할 수 있습니다.
API 호출 방법
비볼디 API는 HTTPS 기반의 REST API 방식으로 호출합니다.
모든 요청은 HTTP Header에 API Key 인증 정보를 포함해야 하며 Content-Type은 application/json 형식을 사용합니다.
응답 데이터는 항상 JSON 형식으로 반환되며 code, message, result 구조를 제공합니다.
code 값이 0이면 정상 처리이며 오류 발생 시 상태 코드와 메시지를 통해 예외 처리를 구현할 수 있습니다.
Host: https://vivoldi.com/api/{uri}
Authorization: APIKey {Your API Key}
Content-type: application/json
User-Agent: {Your User-Agent}
Accept-Language: en
{
"code": 0,
"message": "",
"result": Object
}| 필드 | 설명 | 유형 |
|---|---|---|
| code | 응답 코드입니다. 값이 0이면 성공, 0이 아니면 실패를 의미합니다.이 응답 코드는 HTTP Status와는 별개이며, HTTP Status가 2xx 또는 3xx 범위일 때만 응답 본문이 반환됩니다. |
int |
| message | code가 0이 아닌 경우에 포함되며, 실패 원인을 설명하는 오류 메시지가 담겨 있습니다.성공 시에는 이 필드가 비어 있거나 생략될 수 있습니다. |
string |
| result | API의 실제 응답 데이터이며, API 유형에 따라 문자열(String) 또는 JSON Object 형식으로 반환됩니다. |
object |
Examples:
비볼디는 JavaScript, PHP, Java 등 다양한 개발 환경에서 사용할 수 있도록 REST API 샘플 코드를 제공합니다.
아래 예제는 단축 URL 생성 API(/api/v2/create) 기준으로 작성되어 있으며 API Key와 도메인 값만 변경하면 바로 테스트할 수 있습니다.
JSON 요청 및 응답 구조를 기반으로 구성되어 있어 웹사이트, 관리자 페이지, 내부 시스템, 마케팅 자동화 플랫폼 등 다양한 서비스에 쉽게 적용할 수 있습니다.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<script src="https://code.jquery.com/jquery-4.0.0.min.js" crossorigin="anonymous"></script>
</head>
<body>
<form id="exampleForm">
<button id="btnCreateLink" type="button">Create Link</button>
</form>
<script type="text/javascript">
$(function(){
$("#btnCreateLink").on('click', function(evt){
evt.preventDefault();
$.ajax({
type: 'POST',
url: 'https://vivoldi.com/api/link/v2/create',
data: JSON.stringify({'url':'https://google.com','domain':'https://vvd.bz'}),
headers: {'Authorization':'APIKey oc3w9m4ytso9mv5e8yse9XXXXXXXXXX'},
contentType: 'application/json; charset=utf-8',
dataType: 'json',
timeout: 5000
}).done(function(res){
if (res.code === 0) {
alert('short url: ' + res.result);
} else {
alert('code: ' + res.code + ', message: ' + res.message);
}
}).fail(function(xhr, textStatus, e){
alert('error: ' + e);
});
});
});
</script>
</body>
</html><?php
$url = "https://vivoldi.com/api/link/v2/create";
$params = array (
"url" => "https://www.facebook.com/vivoldi365",
"domain" => "https://vvd.bz",
);
$body = json_encode($params);
$headers = array(
"Authorization: APIKey oc3w9m4ytso9mv5e8yse9XXXXXXXXXX",
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10000);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
$result = curl_exec($ch);
if ($result === FALSE) {
echo "Error sending: " . curl_error($ch);
} else {
print_r($result);
}
curl_close($ch);
?>package com.example;
import org.json.JSONObject;
import org.springframework.http.HttpStatus;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class CreateLink {
public static void main(String[] args) {
try (HttpClient client = HttpClient.newBuilder().build()) {
JSONObject params = new JSONObject();
params.put("url", "https://www.facebook.com/vivoldi365");
params.put("domain", "https://vvd.bz");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://vivoldi.com/api/link/v2/create"))
.header("Content-Type", "application/json")
.header("Authorization", "APIKey oc3w9m4ytso9mv5e8yse9XXXXXXXXXX")
.POST(HttpRequest.BodyPublishers.ofString(params.toString()))
.build();
HttpResponse<String> response;
try {
response = client.send(request, HttpResponse.BodyHandlers.ofString());
} catch (Exception e) {
throw new RuntimeException(e);
}
if (response != null) {
if (response.statusCode() == HttpStatus.OK.value()) {
String jsonString = response.body();
if (jsonString != null && !jsonString.isEmpty()) {
JSONObject json = new JSONObject(jsonString);
if (json.getInt("code") == 0) {
System.out.println("Short URL: " + json.getString("result"));
} else {
System.out.println("Failed: " + String.format("[%d] %s", json.getInt("code"), json.getString("message")));
}
}
}
}
}
}
}