> 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.md).

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

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

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

> **API 연동 키(Access Key / Secret Key)는 신청이나 심사 없이 바로 만드실 수 있습니다.** 쉐어링크 가입을 마친 크리에이터는 쉐어링크 크리에이터 어드민의 **연동 → API 키 발급**에서 만듭니다. 단, 아래 표에서 토스쇼핑 인증이 **필요**로 표시된 상품 조회 API 5개는 토스쇼핑이 인증한 크리에이터만 쓸 수 있습니다. 인증 신청 방법은 [연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.md)에 있습니다.

***

## 제공 기능

| 기능                                                                                                 | 토스쇼핑 인증 | 용도                                                                |
| -------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| [카테고리 조회](https://sharelink-docs.toss.im/developers/open-api/api/categories.md)                    | 필요      | 토스쇼핑 카테고리 트리를 받습니다. 카테고리 베스트 상품 조회에 필요합니다                         |
| [카테고리 베스트 상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/products.md)               | 필요      | 특정 카테고리에서 잘 팔리는 상품 목록                                             |
| [베스트 상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/best-selling.md)                | 필요      | 카테고리 구분 없이 지금 많이 팔리는 상품 목록                                        |
| [하루특가 상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/today-deals.md)                | 필요      | 그날 하루만 판매하는 특가 상품 목록                                              |
| [상품 상세 조회](https://sharelink-docs.toss.im/developers/open-api/api/product-detail.md)               | 필요      | 개별 상품의 상세 이미지·최신 가격·품절 여부                                         |
| [쉐어링크 발급](https://sharelink-docs.toss.im/developers/open-api/api/link.md)                          | –       | 상품·쇼핑홈·특가지면·오아시스마켓 지면·뷰티 지면 추적 링크 발급. **수익 집계는 이 링크로만 이뤄집니다**     |
| [subTag 관리](https://sharelink-docs.toss.im/developers/open-api/api/sub-tags.md)                    | –       | 거래처 하위의 크리에이터·채널을 구분하는 subTag 등록·조회·수정·삭제                         |
| [실적 조회](https://sharelink-docs.toss.im/developers/open-api/api/performance.md)                     | –       | 기간별 클릭·판매·예상 수익금 (결제일 기준, 잠정)                                     |
| [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md)                    | –       | 정산 회차별 확정 수익금 (구매확정 기준)                                           |
| [주문 이벤트 수신 (Push)](https://sharelink-docs.toss.im/developers/open-api/api/order-event-callback.md) | –       | 구매·전체 취소·구매확정 이벤트를 제휴사 서버로 전달(포스트백). 캐시백·리워드 연동용. 2026-09-16부터 기록 |
| [주문 이벤트 조회 (Pull)](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)         | –       | 보관 중인 주문 이벤트를 커서로 조회. Push 누락 대사용                                 |
| [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)                | –       | 구매 기간별 주문상품 목록과 단건의 현재 상태(구매·누적 환불·구매확정), 예상 수익금, 확정 수익금·정산 회차    |

연결성 확인용 health 엔드포인트는 빠른 시작의 2단계에 있습니다.

***

## 시작하기

| 문서                                                                                                                                                                                | 읽는 시점                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.md)                                                                                                             | **가장 먼저.** 어드민에서 인증 정보를 발급받고 출발지 IP를 등록합니다                  |
| [빠른 시작](https://sharelink-docs.toss.im/developers/open-api/readme.md)                                                                                                             | 준비가 끝난 뒤. 토큰 발급부터 링크 획득까지 복사해 실행합니다                         |
| [공통 규약](https://sharelink-docs.toss.im/developers/open-api/convention.md)                                                                                                         | 응답 형식·오류 코드·재시도·호출 제한·일 사용 상한·페이징 등 **매 호출에 적용되는 규칙**을 볼 때  |
| [용어](https://sharelink-docs.toss.im/developers/open-api/glossary.md)                                                                                                              | `tacaId`와 `tacaItemId`의 차이처럼 용어가 헷갈릴 때                      |
| [subTag 관리](https://sharelink-docs.toss.im/developers/open-api/api/sub-tags.md)                                                                                                   | 하위 채널(크리에이터)별로 실적을 나눠 봐야 할 때                                |
| [실적 조회](https://sharelink-docs.toss.im/developers/open-api/api/performance.md) · [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md)                  | 기간·정산 회차별 상품 합계를 자사 서비스에서 보여줄 때. 주문별 수익과 수수료 유형은 구분할 수 없습니다 |
| [주문 이벤트 수신](https://sharelink-docs.toss.im/developers/open-api/api/order-event-callback.md) · [주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md) | 구매·전체 취소·구매확정이 발생한 사실을 제휴사 시스템에서 바로 알아야 할 때 (캐시백·리워드)       |
| [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)                                                                                               | 주문상품별 현재 상태(환불·구매확정)나 예상·확정 수익금을 연동하거나 수수료 유형을 구분해야 할 때     |
| [API 레퍼런스](https://sharelink-docs.toss.im/developers/open-api/api.md)                                                                                                             | 특정 엔드포인트의 파라미터·응답을 확인할 때                                    |

실적 조회·정산내역 조회·주문상품 조회의 비교 표는 [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)의 **실적 조회·정산내역 조회와의 차이**에 있습니다.

***

## 꼭 확인해 주세요

**게시글 링크는 반드시 쉐어링크 발급으로 받은 `shortUrl` 또는 `originUrl`을 써야 수익이 집계됩니다.** 상품 목록·상세 응답의 `productUrl`은 추적이 되지 않는 일반 링크입니다.

**발급 링크로 상품 페이지에 들어간 뒤 24시간 안에 일어난 구매가 제휴사 실적으로 집계됩니다.** 링크가 가리킨 상품이 아닌 다른 상품을 사도 집계됩니다.


---

# 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.md?ask=<question>&goal=<user_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.
