단축 URL API
tlnk.kr API는 이메일 인증을 마친 회원이 X-API-Key·X-API-Secret 헤더를 붙여 POST /api/v1/shorten 을 호출하면 자동 코드 단축 URL을 JSON으로 돌려주는 기능입니다. 글 발행, 뉴스레터, 자동화 워크플로에서 채널별 캠페인 링크를 손대지 않고 만들 때 씁니다.
API 키 받기
무료 회원가입 후 이메일 인증을 마치면 마이페이지 › API 에서 키를 발급받을 수 있습니다.
엔드포인트
POST
https://tlnk.kr/api/v1/shorten인증
발급받은 값을 X-API-Key 와 X-API-Secret 헤더에 넣어 보냅니다. 비밀값은 주소(쿼리 문자열)에 넣지 마세요.
요청
본문은 JSON {"url": "…"} 또는 form(url=…)으로 보냅니다. 서브도메인 이름·코드 지정은 API에서 지원하지 않습니다.
curl -X POST https://tlnk.kr/api/v1/shorten \
-H "X-API-Key: ak_…" \
-H "X-API-Secret: sk_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/very/long/path?utm_source=newsletter"}'
import requests
r = requests.post("https://tlnk.kr/api/v1/shorten",
headers={"X-API-Key": "ak_…", "X-API-Secret": "sk_…"},
json={"url": "https://example.com/very/long/path"}, timeout=30)
print(r.status_code, r.json()["short_url"] if r.ok else r.json())
응답
{
"ok": true,
"code": "Ab3d",
"short_url": "https://tlnk.kr/Ab3d",
"target_url": "https://example.com/very/long/path?utm_source=newsletter",
"created_at": "2026-09-25T09:00:00+09:00",
"daily_remaining": 999
}
오류
{
"ok": false,
"error": "check_failed",
"check": "age",
"message": "…"
}
| 상태 | error 값 | 의미 |
|---|---|---|
400 | url_required | url 값이 필요합니다. |
400 | bad_json | JSON 본문 형식이 올바르지 않습니다. |
401 | auth | API 키 또는 Secret 이 올바르지 않습니다. |
403 | key_blocked | 이 API 키는 차단되었습니다. |
403 | member_blocked | 이 계정의 API 사용이 차단되었습니다. |
405 | method | POST 요청만 받습니다. |
422 | check_failed | 안전 검사를 통과하지 못했습니다 (check 에 사유 코드). |
429 | rate_limited | 요청이 너무 많습니다. 잠시 후 다시 시도하세요. |
429 | daily_limit | 24시간 생성 한도를 넘었습니다. |
429 | too_many_failures | 안전 검사 거부가 너무 많습니다. 잠시 후 다시 시도하세요. |
500 | error | 일시적인 오류입니다. 잠시 후 다시 시도하세요. |
요청 한도: 계정당 1분 60개, 24시간 1,000개.
어떤 워크플로에 연결하면 좋나요?
링크가 필요한 시점이 정해져 있는 작업이라면 어디든 붙일 수 있습니다. 블로그나 CMS에서 글이 발행될 때, 뉴스레터 도구로 캠페인을 준비할 때, Zapier·Make 같은 노코드 도구나 Google Apps Script가 캠페인 시트의 새 행을 처리할 때 HTTP 요청 한 번으로 짧은 주소를 받아 다음 단계에 넘기면 됩니다.
같은 원본 주소라도 utm_source=instagram, utm_source=newsletter 처럼 채널마다 UTM 값을 달리해 따로 줄이면, 마이페이지에서 링크별 클릭과 유입 경로를 나란히 놓고 어느 채널이 효과적이었는지 비교할 수 있습니다. UTM 규칙은 UTM 파라미터 붙이는 법에 정리했습니다.
- CMS·블로그 발행 시 공유용 단축 URL 생성
- 뉴스레터·푸시 캠페인 링크를 발송 전에 미리 준비
- Zapier·Make·Google Apps Script 시나리오의 HTTP 단계
- 채널별 UTM 링크를 만들어 성과 비교
요청은 어떻게 보내나요?
POST /api/v1/shorten 에 원본 주소를 url 값으로 담아 보냅니다. JSON 본문({"url": "https://..."})과 일반 폼 전송을 모두 받으며, 인증은 요청 헤더 X-API-Key 와 X-API-Secret 으로 합니다. 성공하면 short_url, code, target_url 이 담긴 JSON이 돌아옵니다.
API가 만드는 것은 tlnk.kr/Ab3d 같은 자동 코드 링크뿐이라 코드를 고를 수 없고, 브랜드.tlnk.kr 서브도메인 링크가 필요하면 웹 화면에서 만들어야 합니다. 목적지가 안전 검사를 통과하지 못하면 링크 대신 check_failed 오류와 사유 코드가 오므로, 워크플로에서 이 경우를 따로 처리해 두는 것이 좋습니다.
키는 어떻게 발급하고 보관하나요?
무료 회원가입 후 이메일 인증을 끝내면 마이페이지 API 탭에서 키를 만들 수 있습니다. 공개 식별자인 API Key는 ak_, 비밀값인 API Secret은 sk_ 로 시작하며, 동시에 활성 상태로 둘 수 있는 키는 3개입니다. 블로그용, 뉴스레터용, 자동화 도구용처럼 용도별로 나누면 하나를 폐기해도 나머지 워크플로는 멈추지 않습니다.
Secret은 만든 직후 한 번만 보여 주고 서버에는 되돌릴 수 없는 형태로 저장하므로, 나중에 다시 확인할 방법이 없습니다. 분실했다면 그 키를 폐기하고 새로 발급하세요. 자동화 도구의 비밀 변수나 서버 환경 변수에 넣고, 브라우저 자바스크립트·공개 저장소·공유 템플릿에는 남기지 마세요.
API 링크도 웹과 같은 검사를 받나요?
네, 들어오는 경로만 다를 뿐 기준은 같습니다. 도메인 등록 후 1개월(30일) 경과 여부, 실제 접속 여부, 방심위 차단 목록과 URLhaus·OpenPhish 등재 여부, 불법 콘텐츠 키워드를 확인하고, 넘겨주는 주소를 거칠 때마다 다시 보며 내부망 주소는 거절합니다. 만든 뒤에도 3시간마다, 그리고 방문 때마다 재검사하고, 세 명이 따로 신고하면 자동 차단됩니다.
한꺼번에 많이 만들 때 알아 둘 한도는?
계정마다 1분 단위와 24시간 단위 생성 개수, 동시에 처리하는 요청 수에 상한이 있습니다. 검사에서 거부되는 주소를 짧은 시간에 많이 보내면 한동안 요청이 거절됩니다. 한도에 걸리면 응답의 Retry-After 값이 기다릴 시간을 알려 주니, 자동화 시나리오가 그만큼 쉬었다가 재시도하도록 설정하세요.
단시간에 링크를 대량으로 만드는 계정은 운영자가 살펴보며, 스팸이나 스미싱 같은 부정 이용으로 판단되면 해당 키나 계정의 API 이용을 막을 수 있습니다. 운영 원칙은 tlnk.kr 소개에 있습니다.
자주 묻는 질문
API는 무료인가요?
회원이라면 무료입니다. 대신 분당·24시간 생성 한도 안에서 써야 합니다.
API 링크에 브랜드 서브도메인을 붙일 수 있나요?
아니요. API는 자동 코드 링크만 만듭니다. 브랜드.tlnk.kr 같은 이름(소문자·숫자·하이픈 4~32자)은 웹 화면에서 만들면 인증서까지 자동으로 발급됩니다.
Secret을 실수로 공개 저장소에 올렸어요.
곧바로 마이페이지 › API 에서 그 키를 폐기하고 새 키를 발급해 워크플로 설정을 바꾸세요. 폐기된 키로 들어오는 요청은 바로 거부됩니다.
API로 만든 링크의 채널별 성과는 어디서 보나요?
웹에서 만든 링크와 함께 마이페이지 단축 URL 목록에 나타나며, 클릭·유입 경로·국가·기기 통계 확인과 목적지 수정, 일시 중지를 똑같이 할 수 있습니다.
캠페인이 끝난 API 링크도 자동으로 정리되나요?
네. 다른 링크와 마찬가지로 3개월(90일) 동안 클릭이 없으면 삭제되고, 지워진 주소는 1년간 다시 쓰이지 않습니다.