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

# 빠른 시작

**토큰 발급 → 상품 목록 조회 → 쉐어링크 발급**까지 한 번에 따라 하는 예제입니다. 아래 명령을 순서대로 복사해 실행하시면 게시글에 넣을 링크가 나옵니다.

시작하기 전에 [연동 시작하기](/guide/open-api/auth.md)에서 **Access Key / Secret Key 발급**과 **출발지 IP 등록**을 먼저 끝내주세요. 링크 발급까지 해보시려면 **퍼블리셔 UUID(`publisherId`)** 도 필요합니다. 인증 정보와 함께 안내드립니다.

{% hint style="info" %}
먼저 **알파(테스트) 환경**에서 확인하신 뒤 운영으로 옮기시길 권장드립니다. 알파는 주소만 `https://alpha-sharelink.toss.im/openapi` 로 바꾸면 됩니다.
{% endhint %}

***

## 1단계 — 액세스 토큰 발급

발급받은 Access Key / Secret Key로 토스 인증 서버에서 액세스 토큰을 받습니다. 토스쇼핑 파트너 API와 동일한 인증 서버·방식(`client_credentials`)을 사용합니다.

| 환경      | 토큰 발급 엔드포인트                                    |
| ------- | ---------------------------------------------- |
| 운영      | `POST https://oauth2.cert.toss.im/token`       |
| 알파(테스트) | `POST https://oauth2-alpha.cert.toss.im/token` |

요청 본문은 `application/x-www-form-urlencoded` 형식입니다.

| 파라미터            | 값                                                    |
| --------------- | ---------------------------------------------------- |
| `grant_type`    | `client_credentials` 고정                              |
| `client_id`     | 발급받은 Access Key                                      |
| `client_secret` | 발급받은 Secret Key                                      |
| `scope`         | 조회만 쓰면 `sharelink:read`, 링크 발급까지 쓰면 **공백으로 구분해 둘 다** |

```bash
curl -X POST https://oauth2.cert.toss.im/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={Access Key}&client_secret={Secret Key}&scope=sharelink:read sharelink:write"
```

응답의 `access_token` 값을 복사해 둡니다.

```json
{
  "access_token": "eyJhbGc...",
  "scope": "sharelink:read sharelink:write",
  "token_type": "Bearer",
  "expires_in": 31535999
}
```

{% hint style="warning" %}
이 토큰은 **저장해 두고 계속 재사용**하세요. `expires_in`(초)이 유효기간이며, 만료 전에 재발급하시면 됩니다. **API를 호출할 때마다 새로 발급받지 마세요.** 과도한 재발급 요청은 이용이 제한될 수 있습니다.
{% endhint %}

***

## 2단계 — 연결 확인

본격적으로 시작하기 전에 인증과 IP 등록이 제대로 됐는지 확인합니다. 이 엔드포인트는 연결성 확인 전용입니다.

```bash
curl 'https://sharelink.toss.im/openapi/health' \
  -H 'Authorization: Bearer {액세스 토큰}'
```

```json
{ "resultType": "SUCCESS", "success": { "status": "ok" } }
```

이 응답이 나오면 인증·출발지 IP·라우팅이 모두 정상입니다. 실패한다면 이 페이지 아래 *자주 겪는 문제*를 확인해 주세요.

***

## 3단계 — 상품 목록 가져오기

지금 많이 팔리는 상품을 5개만 받아 봅니다.

```bash
curl 'https://sharelink.toss.im/openapi/products/best-selling?size=5' \
  -H 'Authorization: Bearer {액세스 토큰}'
```

```json
{
  "resultType": "SUCCESS",
  "success": {
    "items": [
      {
        "rank": 1,
        "tacaItemId": 1234567890,
        "displayName": "예시 상품명",
        "thumbnailUrl": "https://static.toss.im/...",
        "productUrl": "https://toss.shopping/t/56322313",
        "displayPrice": 19900,
        "originalPrice": 25000,
        "discountRate": 20,
        "isSoldOut": false,
        "reviewScore": 4.8,
        "reviewCount": 1234
      }
    ],
    "nextCursor": "eyJyYW5rIjoyMH0=",
    "hasNext": true
  }
}
```

**여기서 `tacaItemId` 를 기억해 두세요.** 다음 단계에서 이 값으로 링크를 발급합니다. (예제에서는 `1234567890`)

{% hint style="warning" %}
응답의 `productUrl` 은 추적이 되지 않는 일반 링크입니다. **이걸 게시글에 넣으면 수익이 집계되지 않습니다.** 4단계에서 발급받는 링크를 사용해 주세요.
{% endhint %}

***

## 4단계 — 쉐어링크 발급

3단계에서 얻은 `tacaItemId` 로 추적 링크를 발급합니다.

```bash
curl -X POST 'https://sharelink.toss.im/openapi/links' \
  -H 'Authorization: Bearer {액세스 토큰}' \
  -H 'Content-Type: application/json' \
  -d '{ "tacaItemId": 1234567890, "publisherId": "{퍼블리셔 UUID}" }'
```

```json
{
  "resultType": "SUCCESS",
  "success": {
    "tacaItemId": 1234567890,
    "publisherId": "550e8400-e29b-41d4-a716-446655440000",
    "shortUrl": "https://toss.im/_m/abcDE",
    "originUrl": "https://toss.shopping/t/56322313?k=6f1c...&referrer=affiliate"
  }
}
```

**`shortUrl` 이 게시글에 넣을 링크입니다.** 이 링크로 들어온 구매가 수익으로 집계됩니다.

{% hint style="info" %}
발급받은 링크는 **저장해 두고 재사용**하세요. 같은 상품을 다시 요청하면 같은 링크가 나오지만, 매번 호출하면 호출 한도를 낭비하게 됩니다.
{% endhint %}

***

## 5단계 — 게시

3단계에서 받은 상품명·이미지·가격과 4단계에서 받은 `shortUrl` 을 조합해 게시글을 구성하시면 됩니다.

상세 페이지 이미지까지 함께 노출하시려면 [상품 상세 조회](/guide/open-api/api/product-detail.md)로 `detailImageUrls` 를 받아 오세요.

***

## 전체 흐름 정리

```
1. 토큰 발급        POST oauth2.cert.toss.im/token
                    → access_token 저장 (재사용)
                              ↓
2. 연결 확인        GET  /openapi/health
                              ↓
3. 상품 목록        GET  /openapi/products/best-selling
                    → tacaItemId 확보
                              ↓
4. 링크 발급        POST /openapi/links  (tacaItemId + publisherId)
                    → shortUrl 확보 (저장해서 재사용)
                              ↓
5. 게시             상품 정보 + shortUrl
```

***

## 자주 겪는 문제

| 증상                                | 원인과 해결                                                                                                               |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 호출이 **권한 오류**로 막힘                 | 출발지 IP가 등록되지 않았습니다. 어드민에서 API를 호출하는 **서버의 IP**를 등록해 주세요. 내 PC가 아니라 서버 IP입니다 ([출발지 IP 등록](/guide/open-api/auth.md))   |
| 호출이 **인증 오류**로 막힘                 | 토큰이 만료됐거나 잘못됐습니다. 1단계를 다시 실행해 주세요                                                                                    |
| 링크 발급만 막힘                         | 1단계에서 `scope` 에 `sharelink:write` 를 넣지 않았습니다. 조회만 되고 발급은 막힙니다                                                        |
| 구매가 발생했는데 **수익이 안 잡힘**            | `productUrl` 을 게시하셨을 가능성이 큽니다. 발급받은 `shortUrl`·`originUrl` 만 집계됩니다                                                   |
| 응답은 왔는데 **`resultType` 이 `FAIL`** | HTTP 상태 코드만 보지 마시고 `resultType` 으로 판별해 주세요. 실패 사유는 `error.errorCode` 에 있습니다 ([오류 코드](/guide/open-api/convention.md)) |
| 목록이 **0건**으로 옴                    | 하루특가는 그날 편성이 없으면 0건일 수 있습니다. 오류가 아니므로 정상 처리해 주세요                                                                     |
| 같은 상품인데 **링크가 두 개** 생김            | `tacaId` 로 발급하면 대표 상품이 바뀔 때 새 링크가 나옵니다. `tacaItemId` 로 발급해 주세요 ([용어](/guide/open-api/glossary.md))                   |

***

## 다음 단계

* [공통 규약](/guide/open-api/convention.md) — 응답 형식·오류 코드·재시도·호출 제한·페이징
* [용어](/guide/open-api/glossary.md) — `tacaId` 와 `tacaItemId` 의 차이 등
* [API 레퍼런스](/guide/open-api/api/categories.md) — 엔드포인트별 상세 명세


---

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