CTAurl API로 무엇을 할 수 있게 되나요?
CTAurl API는 아직 쓸 수 없어요. 켜지면 직접 만든 소프트웨어로 단축 URL과 QR코드를 만들 수 있어요. https://app.ctaurl.com/api/v1에 있는, HTTPS와 JSON 본문을 쓰는 작은 REST API예요. 모든 요청은 워크스페이스에서 발급한 Bearer 토큰으로 인증하고, 받게 될 요청은 다음과 같아요.
| 요청 | 하는 일 |
|---|---|
POST /links | CTA 도메인이나 ctaurl.me에 링크 만들기. 링크 뒷부분, 제목, 태그, 만료 시각(expiresAt)은 선택 |
GET /links/{id} | 링크 하나 조회 |
PATCH /links/{id} | 링크 비활성화({"disabled": true}) |
POST /qr-codes | 기존 링크의 QR코드 만들기, 또는 새 링크와 QR코드를 한 번에 만들기 |
GET /qr-codes/{id} | QR코드 조회 |
PATCH /qr-codes/{id} | QR코드 색상과 스타일 변경 |
GET /qr-codes/{id}/svg, /png | QR코드를 SVG나 PNG로 다운로드 |
API 토큰과 권한
CTAurl API 토큰은 워크스페이스 소유자가 앱의 Settings → API keys에서 만들어요. 토큰마다 Read only(조회만) 또는 Manage(조회와 생성) 권한이 있어요. 토큰은 만들 때 한 번만 보여 주고, 언제든 폐기할 수 있어요. 워크스페이스 하나에 활성 토큰을 최대 20개까지 둘 수 있어요. 토큰은 Authorization 헤더에 넣어 보내세요.
Authorization: Bearer cta_live_…API로 단축 URL 만드는 방법
API가 켜진 뒤 단축 URL을 만들려면 POST /links 요청에 Bearer 토큰, Idempotency-Key, JSON 본문을 담아 보내세요. 생성 요청에는 모두 Idempotency-Key가 붙어요. 형식은 유닉스 밀리초 시각, 점, UUID v4예요. 요청이 시간 초과되면 24시간 안에 같은 키로 다시 보내세요. 링크가 하나 더 생기지 않고 처음 결과를 돌려받아요.
curl https://app.ctaurl.com/api/v1/links \
-H "Authorization: Bearer $CTAURL_TOKEN" \
-H "Idempotency-Key: 1761638400000.7f8c2a54-3b1e-4c6d-9a0f-2e5b8c1d4f60" \
-H "Content-Type: application/json" \
-d '{"domain":"구매하기.me","shortCode":"sneaker","destinationUrl":"https://shop.abc.yz/sneaker"}'요청이 성공하면 201로 응답하고, shortUrl을 포함한 링크를 돌려줘요. shortCode를 빼면 링크 뒷부분을 자동으로 만들어 줘요. API로 만든 링크도 앱에서 만든 링크와 같은 월 제공량에 포함될 예정이에요.
요청 한도와 오류
CTAurl API는 워크스페이스당 분당 요청 60회를 허용하고, 오류는 고정된 코드와 함께 JSON으로 돌려주며, app.ctaurl.com에서만 요청을 받을 예정이에요.
- 워크스페이스당 분당 요청 60회. 넘으면
429로 응답하고Retry-After를 함께 보내요. - 오류는 JSON으로 돌아와요:
{"error": {"code": "…", "message": "…"}}. 코드는INVALID_REQUEST,FORBIDDEN_SCOPE,RESOURCE_UNAVAILABLE같은 고정 코드가 함께 와요. - 요청은
app.ctaurl.com에서만 받아요.
API가 아직 하지 못하는 것
아직 켜지지 않았다는 점 외에도, CTAurl API로는 전체 링크 목록 불러오기, 링크의 도착 URL 변경(앱에서 하세요), 클릭·스캔 수 받아 오기를 할 수 없어요. 웹훅과 SDK도 없고, 자체 도메인도 쓸 수 없어요. 이 중 무엇이든 생기면 이 페이지에 알릴게요.
API에 관해 자주 묻는 질문
CTAurl에 API가 있나요?
아직이에요. CTAurl API는 만들어져 있지만 켜지지 않았어요. 켜지면 단축 URL과 QR코드를 만들고 조회하고, 링크를 비활성화하고, QR코드를 SVG나 PNG로 받을 수 있어요. 토큰은 워크스페이스 소유자가 Settings의 API keys에서 만들어요. 링크 목록, 도착 URL 변경, 클릭 수, 웹훅은 API로 지원하지 않아요.
CTAurl API에 요청 한도가 있나요?
네. API가 켜지면 CTAurl API는 워크스페이스당 분당 요청 60회까지 허용해요. 한도를 넘은 요청은 Retry-After 헤더와 함께 429 응답을 받아요. API로 만든 링크도 앱에서 만든 링크처럼 요금제의 월 링크 제공량에 포함돼요.