---
url: /api-sdk/share/short-url.md
description: 카카오톡 공유 SDK 호출 전에 공유용 단축 URL을 발급하는 API
---

# 단축 URL 생성

공유 피커에서 URL 복사 기능을 사용하려면 공유 SDK 호출 전에 단축 URL을 발급받아야 합니다. 응답의 `short_url`을 공유 SDK 호출 시 `templateArgs.BUTTON_URL`과 `pickerSettings.args.copy_url`에 주입합니다.

> **관련 가이드**: [공유 설정](/docs/share/settings)

## Endpoint

```http
GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url
```

## 헤더

| Header | 설명 |
| --- | --- |
| `Authorization` | 필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키 |
| `Content-Type` | 필수`application/json` |

## 인증

* Authorization 헤더의 APP\_KEY 검증
* IP ACL 기반(사전 등록된 IP만 허용) 이중 인증

파트너사 정보 전달 양식에서 제출한 IP를 사용합니다.

## 파라미터

| 위치 | 이름 | 타입 | 설명 |
| --- | --- | --- | --- |
| path | `gameCode` | `string` | 필수파트너사 기준 게임 ID |
| query | 파트너사 정의 키 | `string` | 공유 링크에 실어 게임으로 다시 전달할 딥링크 파라미터. `key=value` 형태로 0~N개 전달합니다. 제약은 [딥링크 파라미터](#딥링크-파라미터)를 참고하세요. |

전달한 딥링크 파라미터는 발급된 단축 URL에 포함되어, 사용자가 공유 링크로 게임에 진입할 때 게임으로 다시 전달됩니다.
파라미터를 전달하지 않으면 기존과 동일하게 동작합니다(하위 호환).

### 딥링크 파라미터

게임 진입 시 함께 넘기고 싶은 값을 쿼리 파라미터로 전달하면, 카카오가 검증한 뒤 공유 링크에 추가합니다.
아래 제약을 벗어나면 `-2` 에러가 반환됩니다.

| 제약 항목 | 값 |
| --- | --- |
| 예약 키(사용 불가) | `referer`, `t_src`, `t_ch`, `t_obj` (대소문자 무시) |
| 키 허용 문자 | `A~Z`, `a~z`, `0~9`, `_`, `-` |
| 최대 파라미터 개수 | 20개 |
| 키 최대 길이 | 64자 |
| 값 최대 길이 | 512자 |
| 파라미터 전체 길이 | 2,048자 |
| 값 인코딩 | UTF-8 URL 인코딩되어 추가됩니다 |
| 동일 키 중복 | 첫 번째 값만 사용합니다 |

예약 키(`referer`·`t_src`·`t_ch`·`t_obj`)는 카카오 공유 트래킹용으로 예약되어 있어 파트너사 파라미터로 사용할 수 없습니다.

**요청 예시**

```http
GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url?stage=3&invite=abc123
```

위 요청으로 발급한 단축 URL로 사용자가 진입하면 `stage=3`·`invite=abc123`이 게임으로 전달됩니다.

## 응답

```json
{
  "short_url": "https://gameplay.kakao.com/s/xxxxxxx"
}
```

## 에러 코드

| code | 설명 |
| --- | --- |
| `-2` | `gameCode`가 전달되지 않았거나, 딥링크 파라미터가 [제약](#딥링크-파라미터)을 벗어난 경우(예약 키 사용, 허용 문자 위반, 개수·길이 초과 등) |
| `-852` | `gameCode`로 조회되는 게임이 없는 경우 |
| `-900` | 허용되지 않은 IP에서 접근한 경우 |

## Rate Limit

모든 API에 공통으로 요청 IP 기준 Rate Limit이 적용됩니다.

| 항목 | 값 |
| --- | --- |
| 제한 기준 | 요청 IP 단위 |
| 허용량 | 최대 1,000 RPS |
| Burst | 순간 최대 2,000 requests |

제한 초과 시 `503 Service Temporarily Unavailable`이 반환됩니다.

## 참고 문서

* [공유 설정](/docs/share/settings): 공유 SDK 호출과 단축 URL 적용 위치
* [공유 웹훅 연동](/api-sdk/share/reward-result): 공유 성공 후 파트너사 서버로 결과 통지
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)