> 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/developers/open-api.md).

# 쉐어링크 Open API 연동 가이드

토스쇼핑 상품을 자사 서비스에 노출하고 그 성과를 수익으로 정산받는 서버-투-서버 API 안내입니다.

토스쇼핑 쉐어링크 Open API는 제휴사가 **자사 서비스에서 토스쇼핑 상품을 소개하고, 그 성과를 수익으로 정산받을 수 있도록** 제공하는 서버-투-서버 API입니다.

상품 목록을 받아 게시글·구좌를 구성하고, 소개할 상품마다 쉐어링크(추적 링크)를 발급받아 노출하시면 됩니다. 발급하신 링크를 통해 발생한 구매는 제휴사 수익으로 집계됩니다.

> 이 문서는 제휴사 개발자를 위한 연동 안내입니다. Open API는 **승인제**로 운영됩니다 — 사용 신청과 승인 절차는 [연동 시작하기](/developers/developers/open-api/auth.md)의 **사용 승인 받기**를 봐 주세요. 계약·정산 조건은 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요.

***

### 시범 운영 중입니다

**이 API는 아직 시범적으로 운영하고 있습니다.** 실제 사용 양상을 보며 다듬어 나가는 단계라, 아래 변경이 비교적 짧은 주기로 일어날 수 있습니다.

| 바뀔 수 있는 것 | 내용                             |
| --------- | ------------------------------ |
| 일 사용 상한   | 하루에 가져가실 수 있는 총량이 조정될 수 있습니다   |
| 엔드포인트     | 새 기능이 추가되거나, 제공 방식이 달라질 수 있습니다 |
| 응답 필드     | 필드가 추가될 수 있습니다                 |

변경할 때는 담당자를 통해 안내드립니다.

**연동을 조금만 방어적으로 만들어 두시면 영향을 덜 받으십니다.**

* **모르는 응답 필드는 무시하도록 구현해 주세요.** 필드가 늘었다고 파싱이 깨지지 않아야 합니다.
* **일 사용 상한에 걸렸을 때 연동 전체가 멈추지 않도록 처리해 주세요.** 그날 남은 호출만 건너뛰고 다음 날 이어지면 됩니다.
* **응답과 발급받으신 링크를 저장해 두고 재사용해 주세요.** 상한에 닿는 속도가 크게 줄어듭니다.

상한 값과 초과 시 응답은 [공통 규약](/developers/developers/open-api/convention.md)의 **일 사용 상한**에 정리되어 있습니다.

***

### 제공 기능

| 기능                                                                | 용도                                        |
| ----------------------------------------------------------------- | ----------------------------------------- |
| [카테고리 조회](/developers/developers/open-api/api/categories.md)      | 토스쇼핑 카테고리 트리를 받습니다. 카테고리 베스트 조회에 필요합니다    |
| [카테고리 베스트 상품](/developers/developers/open-api/api/products.md)    | 특정 카테고리에서 잘 팔리는 상품 목록                     |
| [베스트 상품](/developers/developers/open-api/api/best-selling.md)     | 카테고리 구분 없이 지금 많이 팔리는 상품 목록                |
| [하루특가 상품](/developers/developers/open-api/api/today-deals.md)     | 그날 하루만 판매하는 특가 상품 목록                      |
| [상품 상세 조회](/developers/developers/open-api/api/product-detail.md) | 개별 상품의 상세 이미지·최신 가격·품절 여부                 |
| [쉐어링크 발급](/developers/developers/open-api/api/link.md)            | 상품별 추적 링크 발급. **수익 집계는 이 링크로만 이뤄집니다**     |
| [subTag 관리](/developers/developers/open-api/api/sub-tags.md)      | 거래처 하위의 크리에이터·채널을 구분하는 subTag 등록·조회·수정·삭제 |
| [실적 조회](/developers/developers/open-api/api/performance.md)       | 기간별 클릭·판매·예상 수익금 (결제일 기준, 잠정)             |
| [정산 실적 조회](/developers/developers/open-api/api/settlement.md)     | 정산 회차별 확정 수익금 (구매확정 기준)                   |

연결성 확인용 health 엔드포인트는 [빠른 시작](/developers/developers/open-api/readme.md)의 2단계에 있습니다.

***

### 연동 흐름

```
1. 사용 승인               쉐어링크 크리에이터 어드민에서 사용 신청 → 검수 → 승인
                                    ↓
2. 인증 정보 발급          쉐어링크 크리에이터 어드민에서 Access Key / Secret Key 발급
                          + 호출 서버의 출발지 IP 등록
                                    ↓
3. 액세스 토큰 발급        Access Key / Secret Key → 토큰 (유효기간 동안 재사용)
                                    ↓
4. 연결 확인               GET /openapi/health 로 인증·IP 허용 확인
                                    ↓
5. 상품 목록 조회          카테고리 베스트 / 베스트 / 하루특가
                                    ↓
6. 상세 정보 보강 (선택)    상품 상세 조회로 상세 이미지·최신 가격 확보
                                    ↓
7. subTag 등록 (선택)      하위 채널별로 실적을 나눠 보실 때만. POST /openapi/sub-tags/create
                                    ↓
8. 쉐어링크 발급           POST /openapi/links 로 상품별 추적 링크 발급
                                    ↓
9. 게시                    발급받은 링크로 게시글·구좌 구성
                                    ↓
10. 성과 확인 (선택)       GET /openapi/performance · GET /openapi/settlements/{정산 회차}
```

1\~2번은 한 번만 하는 준비이고, 3번부터가 코드로 호출하는 부분입니다. 7번과 10번은 필요하실 때만 쓰시면 됩니다.

***

### 시작하기

처음이시라면 [**연동 시작하기**](/developers/developers/open-api/auth.md) **→** [**빠른 시작**](/developers/developers/open-api/readme.md) 순서로 보시면 됩니다. 사용 승인·인증 정보·출발지 IP가 준비되어야 빠른 시작의 명령을 실행하실 수 있습니다.

| 문서                                                                                                                          | 언제 보나                                                      |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [연동 시작하기](/developers/developers/open-api/auth.md)                                                                          | **가장 먼저.** 사용 승인을 받고, 어드민에서 인증 정보를 발급받고 출발지 IP를 등록합니다      |
| [빠른 시작](/developers/developers/open-api/readme.md)                                                                          | 준비가 끝난 뒤. 토큰 발급부터 링크 획득까지 복사해 실행합니다                        |
| [공통 규약](/developers/developers/open-api/convention.md)                                                                      | 응답 형식·오류 코드·재시도·호출 제한·일 사용 상한·페이징 등 **매 호출에 적용되는 규칙**을 볼 때 |
| [용어](/developers/developers/open-api/glossary.md)                                                                           | `tacaId`와 `tacaItemId`의 차이처럼 용어가 헷갈릴 때                     |
| [subTag 관리](/developers/developers/open-api/api/sub-tags.md)                                                                | 하위 채널(크리에이터)별로 실적을 나눠 봐야 할 때                               |
| [실적 조회](/developers/developers/open-api/api/performance.md) · [정산 실적 조회](/developers/developers/open-api/api/settlement.md) | 발급하신 링크의 성과를 자사 서비스에서 보여줄 때                                |
| API 레퍼런스                                                                                                                    | 특정 엔드포인트의 파라미터·응답을 확인할 때                                   |

***

### 꼭 확인해 주세요

**상품 목록·상세 응답의 `productUrl`은 추적이 되지 않는 일반 링크입니다.** 이 링크로 발생한 구매는 수익으로 집계되지 않습니다.

게시글에 넣으실 링크는 반드시 [쉐어링크 발급 API](/developers/developers/open-api/api/link.md)로 발급받은 `shortUrl` 또는 `originUrl`을 사용해 주세요. 조회 API는 상품 정보를 가져오는 용도이며, 링크 발급을 대체하지 않습니다.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sharelink-docs.toss.im/developers/developers/open-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.