Commerce Product를 소개해요

Amazon, Walmart, Sephora, 올리브영, Rakuten, Zalando 등 쇼핑몰 17곳의 상품 페이지 URL을 넣으면 가격, 재고, 대표 이미지와 상세 이미지, 상품 정보, 옵션을 같은 형식으로 받아요.

받는 결과

• COMMERCE_PRODUCT: 태스크 하나가 상품 페이지 하나를 읽습니다. 미국, 한국, 일본, 인도, 독일의 쇼핑몰 17곳을 지원하고, 페이지의 url을 넣으면 쇼핑몰이 정해집니다.
• 페이지에 나온 그대로 title, brand, currency와 함께 price, listPrice를 받고, inStock, seller, rating, reviewCount도 받습니다.
• images는 상품 갤러리입니다. descriptionImages는 판매자 상세 페이지나 Amazon A+ 콘텐츠처럼 상품 설명에 들어간 이미지를 페이지 순서대로 담습니다.
• description, specs, options, categories, gtin도 모든 쇼핑몰에서 같은 필드로 받습니다.

쇼핑몰

• 미국(US): Amazon amazon, Walmart walmart, Target target, Sephora sephora, Ulta ulta
• 한국(KR): 올리브영 oliveyoung, 11번가 11st, 롯데ON lotteon, 무신사 musinsa, 컬리 kurly
• 일본(JP): 라쿠텐 rakuten, Yahoo! 쇼핑 yahoo_shopping, Qoo10 qoo10
• 인도(IN): Flipkart flipkart, Myntra myntra, Nykaa nykaa
• 독일(DE): Zalando zalando

동작 방식

태스크마다 쇼핑몰의 나라에서 상품 페이지를 읽고, 페이지가 처음 열리는 선택지 기준으로 값을 돌려줍니다. price는 쿠폰과 배송비 전에 내는 가격이고, options에는 다른 용량, 색상, 구성이 담깁니다.

images는 갤러리 사진을 최대 30장, descriptionImages는 상품 설명의 이미지를 페이지 순서대로 최대 300장 담습니다. 상세 이미지는 Amazon, Ulta, 올리브영, 11번가, 롯데ON, 무신사, 컬리, 라쿠텐, Yahoo! 쇼핑, Qoo10에서 받습니다. 판매자가 넣은 배너와 공지도 함께 오고, 이미지 안의 글자는 이미지로 남습니다.

title, price, currency, images는 모든 쇼핑몰에서 오고, 나머지 필드는 페이지에 나올 때 옵니다. 필드별로 받는 쇼핑몰은 엔진 문서에 있습니다. 쇼핑몰이 판매 종료처럼 삭제된 페이지로 답하면 태스크가 PAGE_UNAVAILABLE로 끝납니다.

이렇게 활용하세요

• Commerce Search 상위 상품을 가격, 재고, 판매자, 옵션까지 자세히 읽습니다.
• Amazon, 올리브영, 라쿠텐에서 내 상품 페이지의 가격, 정가, 재고를 매일 추적합니다.
• 경쟁 상품의 대표 이미지와 상세 이미지를 모아 브랜드마다 같은 상품을 어떻게 보여 주는지 비교합니다.
• 상품 정보, 옵션, 상세 이미지를 카탈로그나 AI 쇼핑 답변 점검에 넣습니다.

요청 보내기

API 키를 Authorization 헤더에 넣어 요청을 보냅니다.

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" }
  }'

요청 필드

taskTypestring필수

실행할 엔진입니다. CHATGPT, GOOGLE 같은 값을 넣습니다.

payload.urlstring필수

쇼핑몰 17곳 중 한 곳의 상품 페이지 주소입니다. 최대 2,048자. URL로 쇼핑몰과 나라가 정해집니다.

payload.countrystring

쇼핑몰의 나라입니다. Amazon은 US, 올리브영은 KR입니다. 넣지 않으면 이 값이 기본값입니다.

webhook.urlstring

서버의 HTTPS 주소입니다. 태스크가 끝나는 즉시 결과를 이 주소로 보냅니다.

응답

완료된 태스크는 이런 형태입니다. 길이를 줄여 보여 드립니다.

{
  "success": true,
  "task": {
    "id": "3f0f65f4-bb08-492b-8652-7037fe7cba0d",
    "taskType": "COMMERCE_PRODUCT",
    "status": "COMPLETED",
    "createdAt": "2026-10-22T09:27:29.765Z"
  },
  "credits": { "creditsToCharge": 3, "creditsCharged": 3 },
  "response": {
    "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": 18.39,
    "currency": "USD",
    "inStock": true,
    "seller": "Amazon.com",
    "rating": 4.7,
    "reviewCount": 149176,
    "images": [
      "https://m.media-amazon.com/images/I/61EidjXUBrL._SL1000_.jpg",
      "https://m.media-amazon.com/images/I/61-Ut3jOyyL._SL1500_.jpg",
      "…"
    ],
    "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": "Brand Name", "value": "CeraVe" },
      { "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", "…"]
  }
}

task.statusstring

QUEUED, PROCESSING을 거쳐 답변과 함께 COMPLETED로, 또는 error와 함께 FAILED로 끝납니다.

credits.creditsChargedinteger

끝난 태스크에 청구된 크레딧입니다. 실패한 태스크는 0입니다.

response.pricenumber

페이지가 처음 보여 주는 상품을 쿠폰과 배송비 전에 사는 가격이고, 단위는 currency(ISO 4217)입니다. listPrice는 price보다 높을 때 페이지가 줄을 그어 보여 주는 정가입니다.

response.imagesarray

상품 갤러리의 사진을 페이지 순서대로 최대 30장 담습니다.

response.descriptionImagesarray

판매자 상세 페이지나 Amazon A+ 콘텐츠처럼 상품 설명에 들어간 이미지를 페이지 순서대로 최대 300장 담습니다.

response.specsarray

상품 정보의 { name, value } 쌍을 최대 100개 담습니다. options에는 용량이나 색상 같은 선택지가 values와 함께 담깁니다.

결과 받기

요청하면 status가 QUEUED인 태스크가 바로 돌아옵니다. status가 COMPLETED나 FAILED가 될 때까지 GET /v1/async/task/{id}로 조회하거나, webhook.url을 넣어 같은 task, credits, response를 서버로 받으세요. 결과는 태스크가 끝난 뒤 24시간 동안 조회됩니다.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

오류

VALIDATION_ERRORHTTP 422

url이 없거나, 2,048자를 넘거나, 쇼핑몰 17곳의 상품 페이지 밖에 있거나, payload에 url과 country 외의 필드가 있습니다. details에 해당 필드가 나옵니다.

REGION_UNSUPPORTEDHTTP 422

country가 쇼핑몰의 나라와 다릅니다. 예: Amazon URL에 KR.

MISSING_API_KEYHTTP 401

Authorization 헤더가 빠졌거나, 키가 잘못됐거나 만료 또는 폐기됐습니다.

INSUFFICIENT_CREDITSHTTP 402

잔액이 태스크 가격보다 적습니다. 크레딧을 충전하거나 플랜을 올린 뒤 다시 보내세요.

요금

모든 쇼핑몰에서 완료된 상품 페이지 읽기마다 3크레딧이 차감됩니다. 크레딧은 태스크가 완료될 때 차감됩니다.