> 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/developers/open-api/readme.md). # 빠른 시작 토큰 발급부터 게시글에 넣을 링크를 얻기까지, 복사해서 바로 실행할 수 있는 5단계 예제입니다. **토큰 발급 → 상품 목록 조회 → 쉐어링크 발급**까지 한 번에 따라 하는 예제입니다. 아래 명령을 순서대로 복사해 실행하시면 게시글에 넣을 링크가 나옵니다. 시작하기 전에 [연동 시작하기](/developers/developers/open-api/auth.md)에서 **Access Key / Secret Key 발급**과 **출발지 IP 등록**을 먼저 끝내 주세요. 링크 발급까지 해보시려면 \*\*퍼블리셔 UUID(`publisherId`)\*\*도 필요합니다. 인증 정보와 함께 안내드립니다. > Open API는 **운영 환경에서만 제공**됩니다. 별도의 테스트(알파) 환경은 없으므로, 아래 예제도 모두 운영 환경 기준입니다. *** {% stepper %} {% step %} ### 액세스 토큰 발급 발급받은 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`, 링크 발급까지 쓰면 **공백으로 구분해 둘 다** | ```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를 호출할 때마다 새로 발급받지 마세요.** 과도한 재발급 요청은 이용이 제한될 수 있습니다. > {% endstep %} {% step %} ### 연결 확인 인증과 IP 등록이 제대로 됐는지 확인합니다. HTTP 200뿐 아니라 아래처럼 `resultType`이 `SUCCESS`인지도 확인해 주세요. ```bash curl 'https://sharelink.toss.im/openapi/health' \ -H 'Authorization: Bearer {액세스 토큰}' ``` ```json { "resultType": "SUCCESS", "success": { "status": "ok" } } ``` 이 응답이 나오면 준비가 끝난 것입니다. 실패한다면 이 페이지 아래 \_자주 겪는 문제\_를 확인해 주세요. {% endstep %} {% step %} ### 상품 목록 가져오기 지금 많이 팔리는 상품을 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단계에서 발급받는 링크를 사용해 주세요. > {% endstep %} {% step %} ### 쉐어링크 발급 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`이 게시글에 넣을 링크입니다.** 이 링크로 들어온 구매가 수익으로 집계됩니다. > 발급받은 링크는 **저장해 두고 재사용**하세요. 같은 상품을 다시 요청하면 같은 링크가 나오지만, 매번 호출하면 호출 한도를 낭비하게 됩니다. > {% endstep %} {% step %} ### 게시 3단계에서 받은 상품명·가격과 4단계에서 받은 `shortUrl`을 조합해 게시글을 구성하시면 됩니다. 이미지는 사용 가능한 범위를 먼저 확인한 뒤 포함해 주세요. 상세 페이지 이미지 사용 범위를 확인하셨다면 [상품 상세 조회](/developers/developers/open-api/api/product-detail.md)로 `detailImageUrls`를 조회할 수 있습니다. {% hint style="warning" %} **API에서 이미지 URL을 제공한다고 해서 이미지 사용이 허락된 것은 아닙니다.** 이미지 사용 금지가 표시된 상품은 대표 이미지와 썸네일도 사용하지 마세요. 이미지 URL을 외부 앱·사이트에 표시하거나, 이미지를 저장·가공·재배포하거나, 여러 상품의 이미지와 쉐어링크를 자동 연동하려면 사전 확인이 필요합니다. 서비스 URL, 노출할 화면, 사용 범위와 저장·가공 계획을 준비해 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요. [상품 이미지 사용 안내](/help/troubleshooting.md)와 [운영 정책](/help/operations/policy.md)을 확인한 범위 안에서 사용해 주세요. {% endhint %} {% endstep %} {% endstepper %} ### 전체 흐름 정리 ``` 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 ``` *** ### 자주 겪는 문제 | 증상 | 원인과 해결 | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | 응답이 **`SHARELINK_OPENAPI_ACCESS_DENIED`** | HTTP 200이어도 인가 실패입니다. 인증 정보·거래처 상태와 API를 호출하는 **서버의 IP**를 확인해 주세요. 내 PC가 아니라 서버 IP입니다 ([IP 등록](/developers/developers/open-api/auth.md)) | | 호출이 **401**로 막힘 | 토큰이 만료됐거나 잘못됐습니다. 1단계를 다시 실행해 주세요 | | 호출이 **403**으로 막힘 | 응답 사유와 토큰의 스코프를 확인하세요. 링크 발급에는 `sharelink:write`가 필요합니다. 403만 보고 IP 오류로 단정하지 마세요 | | 구매가 발생했는데 **수익이 안 잡힘** | `productUrl`을 게시하셨을 가능성이 큽니다. 발급받은 `shortUrl`·`originUrl`만 집계됩니다 | | 응답은 왔는데 **`resultType`이 `FAIL`** | HTTP 상태와 본문을 함께 확인하세요. 알려진 코드는 `error.errorCode`로 구분하고, 코드가 없으면 `error.reason`도 확인하세요 ([오류 코드](/developers/developers/open-api/convention.md)) | | 목록이 **0건**으로 옴 | 하루특가는 그날 편성이 없으면 0건일 수 있습니다. 오류가 아니므로 정상 처리해 주세요 | | 같은 상품인데 **링크가 두 개** 생김 | `tacaId`로 발급하면 대표 상품이 바뀔 때 새 링크가 나옵니다. `tacaItemId`로 발급해 주세요 ([용어](/developers/developers/open-api/glossary.md)) | *** ### 다음 단계 * [공통 규약](/developers/developers/open-api/convention.md) — 응답 형식·오류 코드·재시도·호출 제한·페이징 * [용어](/developers/developers/open-api/glossary.md) — `tacaId`와 `tacaItemId`의 차이 등 * [API 레퍼런스](/developers/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 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/developers/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 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.