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

# API 연동하기

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

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

{% hint style="info" %}
이 문서는 제휴사 개발자를 위한 연동 안내입니다. 계약·정산 조건은 담당자에게 문의해 주세요.
{% endhint %}

***

## 제공 기능

| 기능                                                | 용도                                     |
| ------------------------------------------------- | -------------------------------------- |
| [카테고리 조회](/guide/open-api/api/categories.md)      | 토스쇼핑 카테고리 트리를 받습니다. 카테고리 베스트 조회에 필요합니다 |
| [카테고리 베스트 상품](/guide/open-api/api/products.md)    | 특정 카테고리에서 잘 팔리는 상품 목록                  |
| [베스트 상품](/guide/open-api/api/best-selling.md)     | 카테고리 구분 없이 지금 많이 팔리는 상품 목록             |
| [하루특가 상품](/guide/open-api/api/today-deals.md)     | 그날 하루만 판매하는 특가 상품 목록                   |
| [상품 상세 조회](/guide/open-api/api/product-detail.md) | 개별 상품의 상세 이미지·최신 가격·품절 여부              |
| [쉐어링크 발급](/guide/open-api/api/link.md)            | 상품별 추적 링크 발급. **수익 집계는 이 링크로만 이뤄집니다**  |

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

***

## 연동 흐름

```
1. 인증 정보 발급          쉐어링크 크리에이터 어드민에서 Access Key / Secret Key 발급
                          + 호출 서버의 출발지 IP 등록
                                    ↓
2. 액세스 토큰 발급        Access Key / Secret Key → 토큰 (유효기간 동안 재사용)
                                    ↓
3. 연결 확인               GET /openapi/health 로 인증·IP 허용 확인
                                    ↓
4. 상품 목록 조회          카테고리 베스트 / 베스트 / 하루특가
                                    ↓
5. 상세 정보 보강 (선택)    상품 상세 조회로 상세 이미지·최신 가격 확보
                                    ↓
6. 쉐어링크 발급           POST /openapi/links 로 상품별 추적 링크 발급
                                    ↓
7. 게시                    발급받은 링크로 게시글·구좀 구성
```

1번은 어드민에서 한 번만 하는 준비이고, 2번부터가 코드로 호출하는 부분입니다.

***

## 시작하기

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

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

***

## 꼭 확인해 주세요

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

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


---

# 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/guide/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.