> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce Product API (COMMERCE_PRODUCT)

> Amazon, Walmart, Target, Sephora, Ulta, 올리브영, 11번가, 무신사, 컬리, Rakuten, Flipkart, Zalando 등 쇼핑몰의 상품 페이지 하나를 읽어 가격, 재고, 판매자, 평점, 이미지, 상세 사양, 옵션을 같은 형식으로 받습니다.

쇼핑몰 상품 페이지 하나를 읽고 상품 정보를 비동기 task API로 받습니다. 페이지의 `url`을 넣으면 URL로 쇼핑몰을 고르며, 모든 쇼핑몰이 같은 필드를 돌려줍니다. 완료된 읽기당 **3크레딧**입니다.

## 요청

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_PRODUCT", "payload": { "url": "https://www.amazon.com/dp/B00TTD9BRC" } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](/ko/concepts/async-tasks.md).

## 입력

* `url`: 필수. 아래 쇼핑몰의 상품 페이지이며 2,048자 이하입니다. [Commerce Search](/ko/engines/commerce-serp.md)가 이 쇼핑몰들에서 돌려준 상품 `url`을 그대로 넣을 수 있습니다. 단, Yahoo! Shopping의 LOHACO 페이지(`lohaco.yahoo.co.jp`)는 받지 않습니다. 추적 코드처럼 결과에 영향이 없는 파라미터는 읽기 전에 뺍니다.
* `country`: 선택. 기본값은 쇼핑몰의 국가입니다. 다른 국가는 `422 REGION_UNSUPPORTED`로 거절합니다.

| `site` | 상품 페이지 | `country` |
| - | - | - |
| `amazon` | `amazon.com/dp/{ASIN}` | `US` |
| `walmart` | `walmart.com/ip/{name}/{id}` | `US` |
| `target` | `target.com/p/{name}/-/A-{TCIN}` | `US` |
| `sephora` | `sephora.com/product/{name}-P{id}` | `US` |
| `ulta` | `ulta.com/p/{name}-{id}` | `US` |
| `11st` | `11st.co.kr/products/{id}` | `KR` |
| `lotteon` | `lotteon.com/p/product/{id}` | `KR` |
| `musinsa` | `musinsa.com/products/{id}` | `KR` |
| `kurly` | `kurly.com/goods/{id}` | `KR` |
| `oliveyoung` | `oliveyoung.co.kr/store/goods/getGoodsDetail.do?goodsNo={id}` | `KR` |
| `rakuten` | `item.rakuten.co.jp/{shop}/{item}/` | `JP` |
| `yahoo_shopping` | `store.shopping.yahoo.co.jp/{store}/{item}.html` | `JP` |
| `qoo10` | `qoo10.jp/g/{id}` | `JP` |
| `flipkart` | `flipkart.com/{name}/p/{itm}?pid={pid}` | `IN` |
| `myntra` | `myntra.com/{category}/{brand}/{name}/{id}/buy` | `IN` |
| `nykaa` | `nykaa.com/{name}/p/{id}` | `IN` |
| `zalando` | `zalando.de/{name}-{sku}.html` | `DE` |
| `google_shopping` | `google.com/search?q={query}&udm=28#product={productId}&title={title}` | `US` |

Amazon의 `/gp/product/{ASIN}`, 11번가 모바일 페이지처럼 같은 페이지의 다른 주소도 받습니다.

## 응답 예시

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "country": "US",
  "url": "https://www.amazon.com/dp/B00TTD9BRC",
  "productId": "B00TTD9BRC",
  "title": "CeraVe Moisturizing Cream, Face & Body Moisturizer for Dry Skin, 19oz",
  "brand": "CeraVe",
  "price": 16.77,
  "listPrice": 18.96,
  "currency": "USD",
  "inStock": true,
  "seller": "Amazon.com",
  "rating": 4.7,
  "reviewCount": 149149,
  "images": ["https://m.media-amazon.com/images/I/61EidjXUBrL._SL1000_.jpg"],
  "description": "[ HYALURONIC ACID MOISTURIZER ] With hyaluronic acid, ceramides and MVE technology for 24 hour hydration.",
  "descriptionImages": ["https://m.media-amazon.com/images/S/aplus-media-library-service-media/8c56d081-e316-4b57-9731-fcf4eda0821f.__CR0,0,1464,600_PT0_SX1464_V1___.jpg"],
  "specs": [
    { "name": "Item Form", "value": "Cream" },
    { "name": "Skin Type", "value": "All, Dry, Sensitive" }
  ],
  "options": [{ "name": "Size", "values": ["8 Ounce", "16 Ounce (Pack of 1)", "19 Ounce (Pack of 1)"] }],
  "categories": ["Beauty & Personal Care", "Skin Care", "Face", "Creams & Moisturizers", "Face Moisturizers"]
}
```

## 결과 필드

* `site`, `country`, `url`, `productId`는 읽은 페이지를 나타냅니다. `url`은 실제로 읽은 페이지입니다. `productId`는 쇼핑몰 자체 상품 ID이며(Amazon은 ASIN, Rakuten은 `shop:item`) Commerce Search가 돌려주는 ID와 같습니다. 단, Nykaa에서 색상이나 용량 옵션이 있는 상품은 Commerce Search가 옵션 하나의 ID를, 이 읽기는 상품 페이지의 ID를 돌려줍니다.
* `title`은 항상 있습니다. 나머지 필드는 페이지에 있을 때 담으며, 필드별로 값을 돌려주는 쇼핑몰은 아래 표에 있습니다.
* `price`는 페이지가 처음 보여 주는 상품을 쿠폰과 배송비 전에 사는 가격이고, 통화는 `currency`(ISO 4217)입니다. `listPrice`는 페이지에 취소선으로 표시된 정가이며 `price`보다 높을 때 담습니다. `inStock`은 그 상품의 재고 여부, `seller`는 판매자입니다.
* `rating`은 5점 만점이며 소수점 둘째 자리까지입니다. `reviewCount`는 리뷰 수입니다.
* `images`는 상품 사진 목록의 사진 URL을 페이지 순서대로 최대 30개 담습니다. 11번가와 롯데온은 대표 사진 1장만, Sephora는 2장까지 주고, Rakuten과 Yahoo! Shopping은 판매자가 사진 목록에 올린 배너나 안내 이미지도 함께 옵니다. `description`은 문단마다 한 줄인 일반 텍스트이며 최대 10,000자입니다. 이미지 안에만 있는 글자는 담지 않습니다.
* `descriptionImages`는 판매자 상세페이지나 Amazon A+ 콘텐츠처럼 상품 설명 영역에 있는 이미지 URL을 페이지 순서대로 최대 300개 담습니다. 판매자가 설명에 넣은 배너와 안내 이미지도 함께 오고, 이미지 안의 글자는 읽지 않습니다.
* `specs`는 상품 상세 정보의 `{ name, value }` 쌍을 최대 100개 담습니다. `options`는 사이즈, 색상 같은 선택지를 최대 20개 담고, 선택지마다 `values`는 최대 100개입니다. 다른 필드는 페이지가 처음 여는 선택지를 기준으로 합니다. `categories`는 넓은 카테고리부터 좁은 카테고리 순이며 최대 10단계입니다. `gtin`은 페이지에 적힌 UPC, EAN, JAN입니다.
* `google_shopping`은 [Commerce Search](/ko/engines/commerce-serp.md)가 돌려준 상품을 읽습니다. `url`에 검색어, Google 상품 ID, 상품명이 들어 있습니다. 같은 검색어로 Google Shopping을 다시 검색하고, 그 검색어에서 상품이 보이지 않으면 상품명으로 검색해 상품 패널을 열기 때문에 다른 쇼핑몰보다 오래 걸립니다. `offers`는 Google이 보여 주는 판매처 목록이고, Google이 최저가로 표시한 판매처가 첫 번째입니다. 각 판매처에는 `seller`, `title`(판매처의 상품명), `url`(판매처 상품 페이지), `price`, `listPrice`, `currency`, `inStock`이 있습니다. 상품의 `price`, `listPrice`, `seller`, `inStock`은 첫 판매처의 값입니다. `reviewCount`는 Google이 정확한 개수를 보여 줄 때(1,000개 미만)만 담습니다. 검색어와 상품명 어느 쪽에서도 상품이 보이지 않으면 `PAGE_UNAVAILABLE`로 끝납니다.
* 쇼핑몰이 404나 410으로 답하는 페이지(삭제된 상품 등)는 `PAGE_UNAVAILABLE`로 끝나고, 메시지에 쇼핑몰의 응답을 담습니다. 그 밖의 읽기 실패는 `ENGINE_NO_RESULT`입니다. 과금은 완료된 읽기마다 적용됩니다.

| 필드 | 값을 돌려주는 쇼핑몰 |
| - | - |
| `title`, `price`, `currency`, `images` | 전체 |
| `brand` | Rakuten을 뺀 전체 |
| `inStock` | Target, Sephora를 뺀 전체 |
| `rating` | 롯데온, 컬리, Zalando를 뺀 전체 |
| `reviewCount` | 롯데온, Zalando를 뺀 전체 |
| `categories` | Sephora, Qoo10, Flipkart, Google Shopping을 뺀 전체 |
| `description` | 11번가, Qoo10을 뺀 전체. 롯데온, 무신사, 올리브영은 상품 설명 대부분을 이미지로 보여 주어 일부 페이지에만 있습니다. Flipkart와 Zalando는 검색 엔진용으로 게시한 짧은 요약을 돌려줍니다. |
| `descriptionImages` | Amazon, Ulta, 11번가, 롯데온, 무신사, 컬리, 올리브영, Rakuten, Yahoo! Shopping, Qoo10 |
| `specs` | Amazon, Walmart, Target, Ulta, 롯데온, 무신사, 컬리, Myntra, Nykaa, Google Shopping |
| `options` | Amazon, Walmart, Ulta, 무신사, 컬리, 올리브영, Rakuten, Myntra, Nykaa, Zalando |
| `seller` | Amazon, Walmart, 롯데온, 컬리, Rakuten, Myntra, Nykaa, Google Shopping |
| `listPrice` | Amazon, Walmart, Target, Sephora, 무신사, 컬리, 올리브영, Qoo10, Myntra, Nykaa, Google Shopping |
| `offers` | Google Shopping |
| `gtin` | Amazon, Walmart, Target, Ulta, 올리브영, Rakuten, Yahoo! Shopping |

## 관련 문서

* [Commerce Search](/ko/engines/commerce-serp.md)
* [엔진 목록](/ko/engines/overview.md)
* [크레딧과 한도](/ko/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.