Response Schema

다섯 가지 타입이 모든 마켓플레이스 오퍼레이션을 덮습니다. 한 필드는 어디에 나타나든 같은 것을 뜻하며, 모든 개념에는 이름이 정확히 하나입니다 — 배송은 검색 카드, 상품, 오퍼, 배송 견적 어디서나 같은 형태입니다.

선택 필드는 말 그대로 선택입니다. 없다는 것은 마켓플레이스가 말하지 않았다는 뜻이지, 기본값이 아닙니다. price가 없는 것은 무료 상품이 아니라 현재 판매 오퍼가 없는 리스팅입니다. delivery.cost가 없는 것은 무료배송이 아니라 배송비가 아직 산정되지 않았다는 뜻입니다 — 무료배송은 delivery.free: true, 전혀 다른 주장입니다.

어떤 선택 필드가 실제로 채워지는지는 마켓플레이스마다 크게 다릅니다. 각 마켓플레이스 문서에 측정된 비율이 있습니다.

SearchResult

{
  "marketplace": "amazon",
  "query": "running shoes",
  "page": { "index": 1, "size": 48, "total": 1200 },
  "items": [ /* SearchItem */ ],
  "cursor": "…"
}

Facet

이 질의에 대한 사이트 자체의 필터 레일입니다. 없으면 레일이 돌아오지 않은 것이고, []는 이 질의에 레일이 없다는 뜻입니다.

value는 facets 요청 파라미터로 그대로 돌려보내는 값입니다. 내부 id가 아니라 사람이 읽는 표시 이름입니다.

maps_to가 있으면 그 타입 있는 파라미터를 쓰세요. 모든 마켓플레이스에서 같은 것을 뜻합니다.

SearchItem과 Product

둘 다 하나의 아이템 형태를 확장하므로, 한 필드는 결과 카드에서나 상품 페이지에서나 같은 것을 뜻합니다. Product는 상세 화면에만 있는 것을 더합니다.

둘이 공유하는 필드

Money는 {currency, amount}이며 amount는 십진 주단위입니다.

ext는 최후의 수단입니다. 같은 뜻의 공통 필드가 있으면 언제나 그 필드에 담고, 다른 마켓플레이스에는 없는 사실만 그 마켓플레이스의 이름 그대로 ext에 담습니다. 상품, 변형, 판매자, 오퍼, 리뷰, 리뷰 페이지, 카테고리 노드에 붙을 수 있습니다.

DeliveryOption

모든 배송이 쓰는 하나의 형태입니다 — delivery, shippingOptions의 각 항목, 오퍼의 delivery, ShippingQuote의 각 옵션.

cost가 없는 것은 무료가 아니라 밝혀지지 않은 것입니다. 무료는 free: true입니다. available: false는 답이며, 결코 0원 배송비가 아닙니다. 마켓플레이스가 보여 준다면 delivery는 언제나 모든 구매자에게 해당하는 옵션입니다 — 멤버 전용 무료 배송(Prime)은 membership과 함께 shippingOptions에 있고, 모두의 조건으로 표시되지 않습니다.

Seller

rating.grouped: true는 이 집계가 요청한 하나의 변형이 아니라 변형 패밀리 전체를 다룬다는 뜻입니다. 이 값이 없다는 것은 묶여 있는지 알 수 없다는 뜻이며, "변형별임이 확인되었다"보다 약한 진술입니다.

SearchItem에만 있는 필드

Product에만 있는 필드

변형, 그리고 반드시 확인할 한 가지

세상에는 두 가지 변형 모델이 있고, 그 둘을 가르는 것은 한 필드입니다.

• variant.productId가 있음 — 그 조합 자체가 조회 가능한 상품입니다. 그 id를 product에 그대로 넘기세요. Amazon이 이 방식입니다.
• variant.productId가 없음 — 그 조합은 이 상품 안에서만 존재하며, 필요한 것은 이미 다 받았습니다. Shopify·Walmart·AliExpress가 이 방식입니다.

어느 마켓플레이스와 이야기하는지 알 필요는 없습니다. 필드를 확인하세요.

Offer

마켓플레이스가 열거하는 경우의 경쟁 판매자: {seller?, price, listPrice?, condition?, conditionNote?, fulfilledBy?, inStock?, status?, delivery?}. 더 싸지만 더 늦게 배송되는 오퍼는 다른 오퍼이므로 delivery는 DeliveryOption입니다.

ReviewPage

{
  "marketplace": "walmart",
  "productId": "996425081",
  "summary": { "average": 4.6, "count": 1204, "distribution": { "5": 78 } },
  "page": { "index": 1, "size": 10, "total": 990 },
  "reviews": [ /* Review */ ],
  "grouped": true
}

리뷰가 없는 상품

명시적인 0과 함께 200으로 답하므로, "리뷰 0건"을 자신 있게 표시할 수 있습니다.

{ "marketplace": "shopify", "productId": "shop.com/handle", "page": { "index": 1, "size": 0, "total": 0 }, "reviews": [] }

page.total: 0은 상품에 정말로 리뷰가 하나도 없을 때만 보냅니다. 상품에 리뷰가 있는데 가져올 수 없다는 증거가 있다면 — 개수나 평점이 보고되거나 상품 페이지에 리뷰가 보인다면 — 0이 아니라 에러가 돌아옵니다. 따라서 빈 reviews 배열은 두 가지 중 하나를 뜻하며, 어느 쪽인지는 page.total이 말해 줍니다.

0으로 답할 때는 summary가 없습니다. 보고할 평균이 없기 때문입니다.

grouped는 부가 정보가 아니라 반드시 밝혀야 할 사실입니다. 판매자는 한 색상의 페이지에 패밀리 전체의 리뷰 9,000건으로 답할 수 있고, 리뷰 자체에는 그런 표시가 전혀 없습니다 — 묶인 페이지에서 "이 상품의 평점"을 계산하면 패밀리의 평점이 나옵니다.

review.incentivized: true는 마켓플레이스가 대가(무료 제품, 샘플, 보상)를 받고 쓴 리뷰로 표시한 경우입니다. 없으면 표시가 없다는 뜻일 뿐, "대가 없이 썼다"는 뜻은 아닙니다. review.reply는 판매자의 공개 답글이며 {body, date?, author?} 형태입니다.

review.variant는 마켓플레이스가 밝히는 경우 그 리뷰가 어느 형제 상품에 쓰였는지를 알려줍니다. 묶인 페이지 안에서 variant가 비어 있다면 마켓플레이스가 말하지 않았다는 뜻이지, "요청한 상품의 것"이라는 뜻은 결코 아닙니다.

page.total과 summary.count는 세는 대상이 다릅니다. 어떤 상품은 평점 7,654건을 표시하면서 리뷰 목록에는 글이 있는 리뷰 990건만 담고 있을 수 있습니다. count는 상품에 대해, total은 목록에 대해 참입니다. 어느 쪽도 모든 리뷰를 끝까지 받을 수 있다는 약속은 아닙니다. 마켓플레이스마다 페이지를 넘길 수 있는 깊이에 한도가 있고, 목록은 cursor가 끝나는 곳에서 끝납니다.

CategoryList

categories가 돌려주는 것: 하나의 평평한 목록이며, 모든 노드가 자신의 부모를 밝힙니다. 중첩이 아니라 평평한 이유는 흔한 요청이 "분류 전체"이고, 중첩하면 전송량이 커지고 페이지로 나누기도 어려워지기 때문입니다. 트리를 다시 만드는 일은 parentId 기준 groupBy 한 번입니다.

{
  "marketplace": "aliexpress",
  "path": [ { "id": "200000345", "name": "Women's Clothing" } ],
  "categories": [
    { "id": "349", "name": "Skirts", "parentId": "200000345" },
    { "id": "201531101", "name": "Matching Sets", "parentId": "200000345" }
  ]
}

CategoryNode

이 스키마의 대부분과 달리 id와 name은 둘 다 필수입니다. 카테고리 목록은 무언가를 하기 위해 존재합니다. id가 없는 항목은 쓸 수 없고, 이름이 없는 항목은 읽을 수 없습니다.

browsable — 특히 주의해서 읽을 값

없으면 가능하다는 뜻이고, 그것이 일반적인 경우입니다. false는 실재하고 탐색할 수 있지만 뒤에 상품 목록 페이지가 없는 단계를 표시합니다.

여기 있는 모든 마켓플레이스에 그런 단계가 있으며, 예외적인 경우가 아닙니다.

그런 단계를 만나면 categories로 한 단계 더 내려가세요. 거기 있는 id들은 나열됩니다.

categories에 browsableOnly=true 를 넘기면 browse가 받아들이는 id만 돌아옵니다 — 비용과 400이 나는 조건은 마켓플레이스 개요를 보세요.

이 플래그를 믿을 필요는 없습니다

browsable은 확인된 경우에만 채워지므로, 나열할 수 없는 단계가 이 필드 없이 — 즉 낙관적으로 — 돌아올 수 있습니다. Walmart에서는 피할 수 없습니다. Electronics(3944)와 Toys(4171)는 둘 다 자식이 있는 부문인데 하나는 상품을 나열하고 다른 하나는 나열하지 않으며, 분류 정보만으로는 구별할 방법이 없습니다.

그래서 browse가 직접 말해 줍니다. 상품 목록 페이지가 없는 카테고리를 요청하면 빈 목록이 아니라

{ "success": false, "error": { "code": "CATEGORY_NOT_BROWSABLE", "message": "Walmart category 4171 is a navigation hub…" } }

가 돌아옵니다. 빈 목록은 품절된 카테고리도 돌려주는 값이어서, "자식으로 내려가라"와 "여기에는 팔 것이 없다"를 구별할 방법이 없기 때문입니다. 이 코드는 같은 id로 categories를 부르고 그 자식 중 하나를 나열하라는 지시로 받아들이세요. 요청의 실패가 아니라 400이며, 재시도해도 답은 달라지지 않습니다.

ShippingQuote

shipping이 돌려주는 것: 한 상품을 한 지역으로 보내는 모든 방법, 가장 저렴한 것부터.

{
  "marketplace": "aliexpress",
  "productId": "1005012143419303",
  "skuId": "12000057632572864",
  "region": "US",
  "quantity": 1,
  "available": true,
  "options": [
    { "carrier": "YunExpress Standard Shipping", "cost": { "currency": "USD", "amount": 3.13 },
      "free": false, "minDays": 7, "maxDays": 15, "guaranteedDays": 60,
      "estimate": "Oct. 30 - Nov. 07", "tracking": true, "shipsFrom": "CN" }
  ]
}

options는 DeliveryOption입니다. 옵션 없이 available: false이면 마켓플레이스가 그 지역으로 배송하지 않는다는 뜻이며, 에러가 아니라 답입니다.

에러

{ "success": false, "error": { "code": "INVALID_PARAMS", "message": "…" } }

501이 404가 아닌 것은 의도적입니다. "이 리뷰는 제공되지 않습니다"가 "이 상품에는 리뷰가 없습니다"로 읽혀서는 안 됩니다.