> For the complete documentation index, see [llms.txt](https://sharelink-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sharelink-docs.toss.im/developers/open-api/api/link.md).
# 쉐어링크 발급
상품·특가지면·오아시스마켓 지면으로 이동하는 추적 링크를 발급합니다. 게시글에 넣을 링크는 반드시 여기서 발급받습니다.
**수익 집계는 이 API로 발급받은 링크로만 이뤄집니다.** 조회 API 응답의 `productUrl`은 추적이 되지 않으므로, 게시글에 넣으실 링크는 반드시 여기서 발급받아 주세요.
```
POST /openapi/links
```
필요 스코프: `sharelink:write`
***
## 요청
상품 링크와 특가지면·오아시스마켓 지면 링크를 같은 API로 발급합니다. 상품 링크를 발급할 때는 `landingType`에 `PRODUCT`를 명시하는 것을 권장합니다. 기존 연동과의 하위 호환성을 위해 `landingType`을 생략하거나 `null`로 보내도 자동으로 `PRODUCT`로 처리됩니다. 특가지면 링크는 `SHOPPING_DEALS`, 오아시스마켓 지면 링크는 `FRESH_FOOD`를 지정합니다.
### 상품 링크 발급
```json
{
"landingType": "PRODUCT",
"tacaItemId": 12345,
"publisherId": "550e8400-e29b-41d4-a716-446655440000"
}
```
| 필드 | 필수 | 설명 |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `publisherId` | **필수** | 발급 주체 식별자(크리에이터 UUID). 쉐어링크 크리에이터 어드민의 API 연동 화면에서 Access Key·Secret Key와 함께 **회원 연동 ID**로 확인하실 수 있습니다 |
| `landingType` | 선택 | 발급 대상 종류. 상품 링크는 `PRODUCT`를 명시하는 것을 권장합니다. 생략하거나 `null`로 보내면 하위 호환을 위해 자동으로 `PRODUCT`로 처리되며, `SHOPPING_DEALS`는 특가지면, `FRESH_FOOD`는 오아시스마켓 지면입니다. |
| `tacaItemId` | 조건부 | 상품 링크를 발급할 상품 옵션 ID. `tacaId`보다 우선합니다 |
| `tacaId` | 조건부 | 상품 그룹 ID. `tacaItemId`가 없을 때 사용하며, 해당 상품의 대표 옵션으로 발급됩니다 |
| `subTagId` | 선택 | 하위 채널(크리에이터) 식별자. **미리 등록해 두신 값이어야 합니다.** 넣지 않으시면 채널 구분 없이 발급됩니다 |
상품 링크(`landingType` 생략·`null`·`PRODUCT`)는 `tacaItemId`와 `tacaId` 중 **최소 하나는 반드시 넣어야 합니다.** `SHOPPING_DEALS`와 `FRESH_FOOD` 요청에는 두 상품 ID를 넣지 마세요.
| 입력 | 처리 |
| --------------- | ---------------------------------------------------------------- |
| `tacaItemId` 제공 | 해당 옵션으로 발급합니다 |
| `tacaId`만 제공 | 대표 옵션이 자동 선택되어 발급됩니다. 실제 발급된 옵션은 응답의 `tacaItemId`로 확인하세요 |
| 둘 다 제공 | `tacaItemId`를 우선합니다 |
| 둘 다 없음 | HTTP 200 + `resultType: "FAIL"` (`errorCode` 없이 `error.reason`만) |
`publisherId` 같은 필수 필드가 없거나 JSON을 읽을 수 없는 경우에는 **HTTP 400**으로 거절될 수 있습니다. 상품 ID를 읽은 뒤 발급 대상을 찾지 못하는 실패와 구분해 주세요.
```bash
curl -X POST \
-H "Authorization: Bearer {액세스 토큰}" \
-H "Content-Type: application/json" \
-d '{"landingType": "PRODUCT", "tacaItemId": 12345, "publisherId": "550e8400-e29b-41d4-a716-446655440000"}' \
"https://sharelink.toss.im/openapi/links"
```
### 특가지면 링크 발급
상품을 하나 지정하지 않고 토스쇼핑 특가지면으로 이동하는 링크입니다. `publisherId`는 인증 정보에 연결된 거래처 소속이어야 하며, 기존 출발지 IP 검증과 발급 자격 검증도 동일하게 적용됩니다.
```json
{
"landingType": "SHOPPING_DEALS",
"publisherId": "550e8400-e29b-41d4-a716-446655440000"
}
```
```bash
curl -X POST \
-H "Authorization: Bearer {액세스 토큰}" \
-H "Content-Type: application/json" \
-d '{"landingType": "SHOPPING_DEALS", "publisherId": "550e8400-e29b-41d4-a716-446655440000"}' \
"https://sharelink.toss.im/openapi/links"
```
* `subTagId`는 상품 링크와 동일하게 선택적으로 넣을 수 있습니다. 미리 등록된 하위 채널만 사용할 수 있습니다.
* `tacaItemId`, `tacaId`는 보내지 마세요. 특가지면은 특정 상품을 지정하지 않습니다.
* `landingRef`를 비롯해 문서에 정의되지 않은 추가 필드를 보내지 마세요. 특가지면의 대상을 임의로 지정할 수 없습니다.
특가지면에 상품 ID를 함께 보내거나, 지원하지 않는 지면 또는 추가 대상 필드를 보내면 `resultType: "FAIL"`, `errorCode: "SHARELINK_OPEN_API_INVALID_LANDING_TARGET"`로 거절됩니다. `landingType`은 대문자로 정확히 입력하세요. 알 수 없는 문자열은 요청 파싱 단계에서 거절될 수 있습니다.
### 오아시스마켓 지면 링크 발급
특정 상품을 지정하지 않고 오아시스마켓 상품 목록으로 이동하는 링크입니다. `landingType`에 `FRESH_FOOD`를 지정합니다. `publisherId`는 인증 정보에 연결된 거래처 소속이어야 하며, 기존 출발지 IP 검증과 발급 자격 검증이 동일하게 적용됩니다.
```json
{
"landingType": "FRESH_FOOD",
"publisherId": "550e8400-e29b-41d4-a716-446655440000"
}
```
```bash
curl -X POST \
-H "Authorization: Bearer {액세스 토큰}" \
-H "Content-Type: application/json" \
-d '{"landingType": "FRESH_FOOD", "publisherId": "550e8400-e29b-41d4-a716-446655440000"}' \
"https://sharelink.toss.im/openapi/links"
```
* `subTagId`는 선택 항목입니다. 미리 등록된 하위 채널만 사용할 수 있습니다.
* `tacaItemId`, `tacaId`는 보내지 마세요. 오아시스마켓 지면은 특정 상품을 지정하지 않습니다.
* `landingRef` 등 문서에 정의되지 않은 추가 필드는 보내지 마세요.
상품 ID나 추가 필드를 함께 보내면 HTTP 200 + `resultType: "FAIL"`, `errorCode: "SHARELINK_OPEN_API_INVALID_LANDING_TARGET"`로 거절됩니다.
***
## 응답
```json
{
"resultType": "SUCCESS",
"success": {
"tacaItemId": 12345,
"publisherId": "550e8400-e29b-41d4-a716-446655440000",
"shortUrl": "https://toss.im/_m/abcDE",
"originUrl": "https://toss.shopping/t/9876?k=6f1c...&referrer=affiliate"
}
}
```
| 필드 | 타입 | 설명 |
| ------------- | -------------- | ----------------------------------------------------- |
| `tacaItemId` | number 또는 null | 상품 링크는 **실제 발급된** 상품 옵션 ID, 특가지면·오아시스마켓 지면 링크는 `null` |
| `publisherId` | string | 발급 주체 식별자 |
| `shortUrl` | string | 단축 링크 |
| `originUrl` | string | 단축 전 원본 추적 링크 |
### 특가지면 응답 예시
```json
{
"resultType": "SUCCESS",
"success": {
"tacaItemId": null,
"publisherId": "550e8400-e29b-41d4-a716-446655440000",
"shortUrl": "https://toss.shopping/_m/abcDE",
"originUrl": "https://toss.shopping/s/deals?k=example_tracking_key&referrer=affiliate"
}
}
```
### 오아시스마켓 지면 응답 예시
```json
{
"resultType": "SUCCESS",
"success": {
"tacaItemId": null,
"publisherId": "550e8400-e29b-41d4-a716-446655440000",
"shortUrl": "https://toss.shopping/_m/abcDE",
"originUrl": "https://toss.shopping/s/fresh-food?k=example_tracking_key&referrer=affiliate"
}
}
```
URL은 설명용 예시입니다. 실제로 사용할 링크는 응답으로 받은 값을 그대로 사용하세요.
**기존 상품 요청의 `tacaItemId`는 계속 숫자로 반환됩니다.** 특가지면·오아시스마켓 지면 기능을 연동하는 클라이언트는 `tacaItemId: null`을 처리할 수 있어야 합니다. 상품 ID가 없다고 발급 실패로 판단하지 말고 `resultType`으로 성공 여부를 확인하세요. 응답에 `landingType` 필드는 추가되지 않으므로, 요청한 발급 대상 종류를 함께 보관하세요.
### `shortUrl`과 `originUrl` 중 무엇을 쓸지
**두 링크는 요청한 대상(상품 페이지·특가지면·오아시스마켓 지면)으로 이동하며 추적 효과가 동일합니다.**
* **`shortUrl`** — 일반적인 경우에 사용하세요. 짧아서 게시글에 넣기 좋습니다.
* **`originUrl`** — 단축 URL을 허용하지 않는 지면에서 사용하세요. 단축 서버를 거치지 않습니다.
***
## 하위 채널별로 실적을 나누려면
거래처 하나에 인증 정보가 1벌만 발급되므로, 아무것도 하지 않으시면 하위 채널이 아무리 많아도 실적이 한 덩어리로 보입니다. 채널별로 나눠 보려면 [subTag 관리](/developers/open-api/api/sub-tags.md)에서 채널을 먼저 등록하고, 발급 요청에 `subTagId`를 함께 넣어 주세요.
```bash
curl -X POST \
-H "Authorization: Bearer {액세스 토큰}" \
-H "Content-Type: application/json" \
-d '{"landingType": "PRODUCT", "tacaItemId": 12345, "publisherId": "550e8400-e29b-41d4-a716-446655440000", "subTagId": "creator_a1"}' \
"https://sharelink.toss.im/openapi/links"
```
| 입력 | 처리 |
| ------------------------ | ---------------------------------------- |
| 등록해 두신 `subTagId` | 그 subTag에 귀속되는 링크가 발급됩니다 |
| `subTagId` 없음 | 채널 구분 없이 발급됩니다 |
| 등록하지 않았거나 삭제된 `subTagId` | `SHARELINK_OPENAPI_ACCESS_DENIED`로 거절됩니다 |
| 다른 거래처가 등록한 `subTagId` | `SHARELINK_OPENAPI_ACCESS_DENIED`로 거절됩니다 |
`subTagId`는 **링크 URL에 실리지 않으므로** 제휴사 내부 식별자가 외부에 노출되지 않습니다. 발급된 링크의 성과는 [실적 조회](/developers/open-api/api/performance.md)·[정산 실적 조회](/developers/open-api/api/settlement.md)에서 `subTagId`로 좁혀 확인하실 수 있습니다.
***
## 제휴사 추적 식별자 붙이기 (`partner_ref_id`)
캐시백·리워드처럼 **어떤 사용자(또는 어떤 신청 건)에서 구매가 났는지**를 제휴사 시스템에서 알아야 한다면, 발급받은 `originUrl`에 `partner_ref_id` 쿼리 파라미터를 직접 붙여 사용자에게 제공하세요. 그 링크로 발생한 구매·취소는 [주문 이벤트](/developers/open-api/api/order-event-callback.md)에 `partnerRefId`로 담겨 전달됩니다.
| 항목 | 규칙 |
| -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 붙이는 대상 | 응답의 **`originUrl`만**. `shortUrl`에 붙이는 방식은 지원하지 않습니다 |
| 기존 쿼리 보존 | `originUrl`에 이미 있는 `k`, `referrer` 등을 지우거나 바꾸지 마세요 |
| 허용 값 | 영문 **소문자**·숫자·하이픈(`-`)·밑줄(`_`) 1\~128자 (`^[a-z0-9_-]{1,128}$`). 규칙에 맞지 않는 값(대문자 등)은 오류 없이 버려져 이벤트의 `partnerRefId`가 `null`로 옵니다 |
| 발급과의 관계 | 링크 발급 요청에 넣는 값이 **아닙니다.** 식별자마다 링크를 다시 발급할 필요가 없고, 같은 링크에 값만 바꿔 붙이면 됩니다 |
| 넣지 말 것 | 이름·전화번호·이메일 등 개인정보, 인증 토큰. 제휴사 안에서만 해석되는 비식별 토큰을 쓰세요 |
문자열을 이어 붙이지 말고 URL 파라미터로 추가하세요. 기존 쿼리가 깨지지 않습니다.
```javascript
const url = new URL(linkResponse.originUrl);
url.searchParams.set("partner_ref_id", "cashback_20260914_a1");
const trackingUrl = url.toString();
```
`partner_ref_id`는 **주문 ID가 아닙니다.** 같은 값에 여러 주문상품 이벤트가 귀속될 수 있고, 유일성이나 1:1 매칭을 보장하지 않습니다. 이벤트를 받는 방법은 [주문 이벤트 수신](/developers/open-api/api/order-event-callback.md), 조회하는 방법은 [주문 이벤트 조회](/developers/open-api/api/order-events.md)를 봐 주세요.
***
## 같은 대상을 다시 발급하면
**같은 `tacaItemId` + 같은 `publisherId` + 같은 `subTagId`로 다시 요청하면 기존 링크를 그대로 돌려드립니다.** 중복 링크가 생성되지 않으므로 안심하고 재요청하셔도 됩니다.
> 같은 상품·같은 발급 주체라도 `subTagId`가 다르면 **다른 링크가 발급됩니다.** 이미 게시하신 링크는 그대로 동작합니다.
지면 링크는 같은 `landingType` + 같은 `publisherId` + 같은 `subTagId`로 다시 요청하면 기존 링크를 반환합니다. `SHOPPING_DEALS`와 `FRESH_FOOD`는 서로 다른 대상이며, 상품 링크와도 구분됩니다. 같은 지면이라도 `subTagId`가 다르면 다른 링크를 발급합니다.
신규 링크가 발급될 때만 일 발급량이 차감됩니다. 다만 일 발급 한도를 이미 소진했다면 기존 링크를 재요청하는 경우에도 거절될 수 있으므로, **발급받은 링크는 저장해 두고 재사용하는 것을 권장합니다.** 매번 발급 API를 호출하면 [호출 제한](/developers/open-api/convention.md)을 불필요하게 소모하게 됩니다.
### `tacaId`로 발급하실 때 주의
링크의 동일성 판단 기준은 `tacaItemId`입니다. 따라서 `tacaId`로 요청하시는 경우, **판매 상황에 따라 대표 옵션이 바뀌면 다른 옵션으로 해석되어 새 링크가 발급됩니다.**
기존에 게시하신 링크는 계속 정상 동작하지만, 성과가 두 링크로 나뉘어 집계됩니다.
***
## 발급되지 않는 경우
일부 상품·판매자는 쉐어링크 발급이 제한됩니다. 이 경우 HTTP 200 + `resultType: "FAIL"`로 내려가며, **`errorCode` 없이 `error.reason` 문구만** 담깁니다. 문구는 바뀔 수 있으니 문자열을 파싱해 분기하지 마세요.
발급 제한 사유는 상품·셀러 정책에 따라 달라지므로, **발급에 실패한 상품은 노출 대상에서 제외**하시면 됩니다. 목록 API로 받으신 상품이라도 발급 시점에 상태가 바뀌었을 수 있습니다.
단, 쉐어링크 점검 중에는 상품·지면 링크 발급과 기존 링크 재요청을 포함한 모든 발급 요청이 HTTP 200 + `resultType: "FAIL"`, `errorCode: "SHARELINK_MAINTENANCE_ISSUE_BLOCKED"`로 거절됩니다. 거절된 요청은 일 발급량에서 차감되지 않습니다. 점검이 끝난 뒤 다시 요청해 주세요. 처리 방법은 [공통 규약](/developers/open-api/convention.md)의 오류 코드를 참고하세요.
***
## 수익 귀속 범위
제휴사 수익으로 집계되는 것은 **제휴사가 직접 발급해 게시한 쉐어링크를 통한 구매**입니다.
사이트에 올라오는 모든 토스 링크를 일괄 변환해 귀속시키는 방식은 제공하지 않습니다. 발급받으신 링크로 게시해 주셔야 정상적으로 집계됩니다.
정산 조건·주기 등 자세한 내용은 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://sharelink-docs.toss.im/developers/open-api/api/link.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.