> 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/api/product-detail.md). # 상품 상세 조회 개별 상품의 상세 페이지 이미지와 최신 가격, 품절 여부를 최대 30건까지 조회합니다. 목록 API는 상품 카드에 필요한 정보만 담고 있어, 상세 페이지 이미지를 함께 노출하기 어렵습니다. 이 API는 두 가지 용도로 사용하실 수 있습니다. * 게시글에 토스쇼핑 상품의 **상세 페이지 이미지**를 함께 노출 * 저장해 둔 상품의 **최신 가격·품절 여부 재확인** {% hint style="warning" %} **썸네일과 상세 페이지 이미지는 쉐어링크 상품을 소개하는 목적으로 표시하실 수 있지만, 가공은 할 수 없습니다.** 크롭·합성·편집·번역 없이 원본 그대로 노출해 주세요. 가급적 썸네일 이미지 사용을 권장드립니다. * 셀러가 요청하면 해당 이미지를 바로 내려야 할 수 있습니다. 상품 단위로 이미지 노출을 중단할 수 있게 구현해 주세요. * 상세 페이지에 이미지 사용 금지가 표시된 상품은 썸네일을 포함해 이미지를 사용하지 마세요. 자세한 기준은 크리에이터 가이드 [운영 정책](/help/operations/policy.md#policy-flow-11)의 **상품 이미지 사용**을 확인해 주세요. {% endhint %} ``` GET /openapi/products/detail ``` 필요 스코프: `sharelink:read` *** ## 요청 `tacaItemIds` 또는 `tacaIds` 중 **하나만** 콤마로 구분해서 넘겨 주세요. | 파라미터 | 설명 | | ------------- | ----------------------------------------- | | `tacaItemIds` | 상품 옵션 ID 목록. 목록 API 응답의 `tacaItemId` 값입니다 | | `tacaIds` | 상품 그룹 ID 목록. 해당 상품의 대표 옵션을 자동으로 찾아 조회합니다 | ```bash curl -H "Authorization: Bearer {액세스 토큰}" \ "https://sharelink.toss.im/openapi/products/detail?tacaItemIds=12345,12346,12347" ``` ### 규칙 * **중복을 제거한 ID 기준으로 한 번에 최대 30건**까지 조회할 수 있습니다. * 두 파라미터를 모두 넘기면 `tacaItemIds`만 사용하고 `tacaIds`는 무시합니다. * 같은 ID를 여러 번 넣으셔도 한 번만 조회합니다. 따라서 `items`와 `notFoundIds`의 합이 넘기신 ID 개수보다 적을 수 있습니다. * 아래 경우는 \*\*HTTP 200 + `resultType: "FAIL"` + `errorCode: "INVALID_ARGUMENT"`\*\*로 거절됩니다. * 두 파라미터가 모두 없는 경우 * 숫자가 아닌 값이 섞인 경우 * 30건을 초과한 경우 > **`tacaItemIds` 사용을 권장드립니다.** `tacaIds`로 조회하시면 판매 상황에 따라 대표 옵션이 바뀔 수 있어, 조회 시점에 따라 다른 옵션이 잡힐 수 있습니다. *** ## 응답 `partnerMallType`의 값과 처리 규칙은 [상품 카드 공통 필드](/developers/open-api/convention.md)의 **제휴몰 유형**을 확인해 주세요. ```json { "resultType": "SUCCESS", "success": { "items": [ { "tacaItemId": 12345, "tacaId": 9876, "displayName": "상품명", "partnerMallType": "NONE", "thumbnailUrl": "https://.../thumb.jpg", "mainImageUrls": [ "https://.../main1.jpg", "https://.../main2.jpg" ], "productUrl": "https://toss.shopping/t/9876", "displayPrice": 19900, "originalPrice": 29900, "discountRate": 33, "isSoldOut": false, "reviewScore": 4.8, "reviewCount": 1523, "categoryIds": [100, 101, 10125], "description": { "detailImageUrls": [ "https://.../detail1.jpg", "https://.../detail2.jpg" ], "noticeImageUrl": "https://.../notice.jpg", "htmlUrl": null } } ], "notFoundIds": [12346] } } ``` ### 필드 | 필드 | 타입 | 설명 | | ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ | | `tacaItemId` | number | 상품 옵션 ID | | `tacaId` | number | 상품 그룹 ID | | `displayName` | string | 상품명 | | `partnerMallType` | string | 판매자 제휴몰 유형. 일반 셀러는 `NONE`, 오아시스는 `OASIS`. 모르는 값은 일반 셀러처럼 처리합니다 | | `thumbnailUrl` | string | 썸네일 이미지 | | `mainImageUrls` | array | 상세 상단 메인 이미지 목록. 첫 번째가 썸네일과 다를 수 있습니다 | | `productUrl` | string | 상품 페이지 주소. **추적이 없는 일반 링크입니다** | | `displayPrice` | number | 판매가 (원). 배송비가 포함된 금액입니다 | | `originalPrice` | number | 정가 (원) | | `discountRate` | number | 할인율 (%) | | `isSoldOut` | boolean | 품절 여부 | | `reviewScore` | number | 리뷰 평점 | | `reviewCount` | number | 리뷰 수 | | `categoryIds` | array | 카테고리 ID 경로. 상위에서 하위 순서. **비어 있을 수 있습니다** ([상품 카드 공통 필드](/developers/open-api/convention.md)의 처리 방법 참고) | | `description.detailImageUrls` | array | **상세 페이지 이미지 목록** | | `description.noticeImageUrl` | string \| null | 셀러 공지 이미지 | | `description.htmlUrl` | string \| null | 상세 설명 HTML 주소 | **가격은 목록 API와 같은 기준으로 계산하므로 목록과 상세의 값이 일치합니다.** > 상세 설명은 셀러가 등록한 방식에 따라 다릅니다. 이미지로 등록했으면 `detailImageUrls`가, HTML로 등록했으면 `htmlUrl`이 채워집니다. 둘 중 하나가 `null`이거나 빈 배열일 수 있으므로 양쪽 모두 처리해 주세요. *** ## `notFoundIds` — 일부만 조회됐을 때 요청하신 상품 중 일부가 조회되지 않아도 **나머지는 정상적으로 내려드립니다.** 조회되지 않은 상품의 ID는 `notFoundIds`에 담깁니다. * 넘기신 ID를 **그대로** 돌려드립니다. `tacaIds`로 요청하셨다면 `tacaId`가 담깁니다. * `items`와 `notFoundIds` 모두 요청하신 순서를 유지합니다. ### 조회되지 않는 경우 | 사유 | | ------------------------------------- | | 카탈로그에 없거나 판매·노출이 종료된 상품 | | 페널티가 적용된 상품 | | `tacaIds`로 요청하셨는데 노출 가능한 대표 옵션이 없는 경우 | | 상세 이미지가 없어 상세를 구성할 수 없는 상품 | | 성인 상품 | ### 처리 방법 `notFoundIds`에 담긴 상품은 상품 상태에서 비롯된 미조회이므로 **같은 요청을 바로 다시 보내셔도 결과가 같습니다.** 재시도하지 마시고 해당 상품은 노출 대상에서 제외해 주세요. 다만 페널티 해제나 재노출로 상품 상태가 복구되면 다시 조회될 수 있습니다. **영구 제외로 고정하지 마시고** 주기적으로 재조회해 주시는 것을 권장드립니다. 일시적인 서버 장애는 `notFoundIds`가 아니라 실패 응답(`errorCode: "500"` 또는 HTTP 5xx)으로 옵니다. [공통 규약](/developers/open-api/convention.md)에 따라 재시도해 주세요. *** ## 사용 팁 게시글에 넣으실 링크는 [쉐어링크 발급](/developers/open-api/api/link.md)으로 발급받아 주세요. 이 API는 이미지·가격 등 **콘텐츠 정보를 가져오는 용도**이며, 링크 발급을 대체하지 않습니다. --- # 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/api/product-detail.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.