> 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/readme.md). # 빠른 시작 토큰 발급부터 게시글에 넣을 링크를 얻기까지, 복사해서 바로 실행할 수 있는 5단계 예제입니다. 시작하기 전에 연동 시작하기에서 **Access Key / Secret Key 발급**과 **출발지 IP 등록**을 먼저 끝내주세요. 링크 발급에는 **퍼블리셔 UUID(`publisherId`)** 도 필요합니다. 어드민의 API 연동 화면에서 Access Key 아래 **회원 연동 ID**로 확인하실 수 있습니다. > 아래 예제는 모두 **운영 환경** 기준입니다. 별도의 테스트 환경은 없습니다. *** ## 1단계 — 액세스 토큰 발급 발급받은 Access Key / Secret Key로 토스 인증 서버에서 액세스 토큰을 받습니다. 토스쇼핑 파트너 API와 동일한 인증 서버·방식(`client_credentials`)을 사용합니다. 토큰 발급 엔드포인트는 `POST https://oauth2.cert.toss.im/token` 입니다. 요청 본문은 `application/x-www-form-urlencoded` 형식입니다. | 파라미터 | 값 | | --------------- | ------------------------------------------------------------------------------ | | `grant_type` | `client_credentials` 고정 | | `client_id` | 발급받은 Access Key | | `client_secret` | 발급받은 Secret Key | | `scope` | 조회만: `sharelink:read` / 조회 + 링크 발급: `sharelink:read sharelink:write` (공백으로 구분) | ```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 } ``` > 이 토큰은 **저장해 두고 계속 재사용**하세요. `expires_in`(초)이 유효기간이며, 만료 전에 재발급하시면 됩니다. **API를 호출할 때마다 새로 발급받지 마세요.** 과도한 재발급 요청은 이용이 제한될 수 있습니다. *** ## 2단계 — 연결 확인 인증과 IP 등록이 제대로 됐는지 확인합니다. HTTP 200뿐 아니라 아래처럼 `resultType`이 `SUCCESS`인지도 확인해 주세요. 이 엔드포인트는 연결성 확인 전용입니다. ```bash curl 'https://sharelink.toss.im/openapi/health' \ -H 'Authorization: Bearer {액세스 토큰}' ``` ```json { "resultType": "SUCCESS", "success": { "status": "ok" } } ``` 이 응답이 나오면 준비가 끝난 것입니다. 실패한다면 이 페이지 아래 *자주 겪는 문제*를 확인해 주세요. *** ## 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, "categoryIds": [100, 101, 10125] } ], "nextCursor": "eyJyYW5rIjoyMH0=", "hasNext": true } } ``` **여기서 `tacaItemId` 를 기억해 두세요.** 다음 단계에서 이 값으로 링크를 발급합니다. (예제에서는 `1234567890`) > 응답의 `productUrl` 은 추적이 되지 않는 일반 링크입니다. **이걸 게시글에 넣으면 수익이 집계되지 않습니다.** 4단계에서 발급받는 링크를 사용해 주세요. *** ## 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` 이 게시글에 넣을 링크입니다.** 이 링크로 들어온 구매가 수익으로 집계됩니다. > 발급받은 링크는 **저장해 두고 재사용**하세요. 같은 상품을 다시 요청하면 같은 링크가 나오지만, 매번 호출하면 호출 제한을 불필요하게 소모합니다. > 캐시백·리워드 연동이라면 `shortUrl` 대신 `originUrl`에 `partner_ref_id`를 붙여 제공해야 합니다. 주문 이벤트 수신을 봐 주세요. *** ## 5단계 — 게시 3단계에서 받은 상품명·가격과 4단계에서 받은 `shortUrl` 을 조합해 게시글을 구성하시면 됩니다. 이미지를 넣으시려면 먼저 [공통 규약](/developers/open-api/convention.md)의 **공통 주의사항**에서 사용 범위를 확인해 주세요. 상세 페이지 이미지는 상품 상세 조회의 `description.detailImageUrls`로 받을 수 있습니다. 게시글에는 제휴 링크임을 알리는 대가성 문구를 함께 넣어 주세요. 표시 방법은 [운영 정책](https://sharelink-docs.toss.im/help/operations/policy)의 **경제적 이해관계 표시**에 있습니다. *** ## 자주 겪는 문제 | 증상 | 원인과 해결 | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `resultType` 이 `FAIL` 이고 `errorCode` 가 **`SHARELINK_OPENAPI_ACCESS_DENIED`** | 출발지 IP가 등록되지 않았거나 인증 정보가 유효하지 않습니다. 어드민에서 API를 호출하는 **서버의 IP**를 등록해 주세요. 내 PC가 아니라 서버 IP입니다 (IP 등록) | | 호출이 **401**로 막힘 | 토큰이 만료됐거나 잘못됐습니다. 1단계를 다시 실행해 주세요 | | 호출이 **403**으로 막힘 | 응답 사유와 토큰의 스코프를 확인하세요. 링크 발급에는 `sharelink:write`가 필요합니다. 403만 보고 IP 오류로 단정하지 마세요 | | 구매가 발생했는데 **수익이 안 잡힘** | `productUrl` 을 게시하셨을 가능성이 큽니다. 발급받은 `shortUrl`·`originUrl` 만 집계됩니다 | | 응답은 왔는데 **`resultType` 이 `FAIL`** | HTTP 상태와 본문을 함께 확인하세요. 알려진 코드는 `error.errorCode` 로 구분하고, 코드가 없으면 `error.reason` 도 확인하세요 (오류 코드) | | 목록이 **0건**으로 옴 | 하루특가는 그날 편성이 없으면 0건일 수 있습니다. 오류가 아니므로 정상 처리해 주세요 | | 같은 상품인데 **링크가 두 개** 생김 | `tacaId` 로 발급하면 대표 상품이 바뀔 때 새 링크가 나옵니다. `tacaItemId` 로 발급해 주세요 (용어) | *** ## 다음 단계 * 공통 규약 — 응답 형식·오류 코드·재시도·호출 제한·페이징 * 용어 — `tacaId` 와 `tacaItemId` 의 차이 등 * [API 레퍼런스](/developers/open-api/api.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 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/readme.md?ask=&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.