> 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 안내입니다.

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

> **현재 Open API 신규 사용 신청을 잠시 받지 않습니다.** 외부 웹사이트에 상품 가격이 노출되는 문제와 관련해 운영 기준을 정비하는 중입니다. 이미 승인받으신 파트너는 지금처럼 이용하실 수 있습니다.
>
> Open API는 **승인제**로 운영됩니다 — 승인 절차는 연동 시작하기의 **사용 승인 받기**에 있습니다. 계약·정산 조건은 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요.

***

## 제공 기능

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

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

***

## 연동 흐름

```
1. 사용 승인               쉐어링크 크리에이터 어드민에서 사용 신청 → 검수 → 승인
                                    ↓
2. 인증 정보 발급          쉐어링크 크리에이터 어드민에서 Access Key / Secret Key 발급
                          + 퍼블리셔 UUID(회원 연동 ID) 확인 + 호출 서버의 출발지 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/{정산 회차}
                                    ↓
11. 주문 이벤트 (선택)      캐시백·리워드 연동 시. originUrl 에 partner_ref_id 부착 →
                          수신 URL 등록(Push) + GET /openapi/order-events 로 대사(Pull)
```

주문상품별 현재 상태를 자사 서비스에 저장하려면 [주문상품 조회](/developers/open-api/api/order-products.md)를 사용합니다. 구매기간으로 목록을 모은 뒤 `orderProductId`별로 갱신하고, 환불·구매확정을 확인할 때 같은 구매기간이나 단건을 재조회합니다.

1\~2번은 한 번만 하는 준비이고, 3번부터가 코드로 호출하는 부분입니다. 7번·10번·11번은 필요하실 때만 쓰시면 됩니다. 특가지면·오아시스마켓 지면 링크만 발급하실 때는 5\~6번 상품 조회를 생략할 수 있습니다. 요청 방법은 [쉐어링크 발급](/developers/open-api/api/link.md)을 확인하세요.

***

## 시작하기

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

***

## 꼭 확인해 주세요

**게시글 링크는 반드시 쉐어링크 발급으로 받은 `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.