---
title: "Marketplace API"
description: "Amazon, Shopify, Walmart, TikTok Shop, AliExpress를 하나의 오퍼레이션 세트와 하나의 응답 스키마로 제공합니다."
---

Marketplace API는 네 개의 마켓플레이스를 **같은 오퍼레이션과 하나의 응답 스키마**로 제공합니다. Amazon의
상품과 Shopify의 상품은 같은 `Product`로 오므로, 하나를 읽는 코드가 모두를
읽습니다. 마켓플레이스는 경로의 한 구간입니다.

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
```

## 오퍼레이션

| 오퍼레이션 | 반환 | 하는 일 |
|---|---|---|
| `search` | `SearchResult` | 키워드에 맞는 상품, 필터 지원 |
| `image-search` | `SearchResult` | 사진에 맞는 상품 |
| `browse` | `SearchResult` | 키워드 없이 한 카테고리의 상품 |
| `categories` | `CategoryList` | 카테고리 트리의 한 단계. `browse`가 받는 id를 찾는 데 씁니다 |
| `catalog` | `SearchResult` | 한 스토어의 모든 상품 |
| `product` | `Product` | 상품 하나의 전체 정보: 옵션, 이미지, 사양, 판매자, 배송 |
| `reviews` | `ReviewPage` | 상품 리뷰, 한 페이지씩 |
| `shipping` | `ShippingQuote` | 상품 하나를 특정 국가로 보내는 배송비, 운송사별 |

모든 타입은 [Response Schema](/docs/api-reference/marketplaces/response-schema)에 필드별로 설명되어 있습니다.

## 마켓플레이스별 지원 범위

| | search | image-search | browse | categories | catalog | product | reviews | shipping |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| [Amazon](/docs/api-reference/amazon) | ✓ | ✓ | ✓ | ✓ | | ✓ | | |
| [Shopify](/docs/api-reference/shopify) | ✓ | ✓ | | | ✓ | ✓ | ✓ | |
| [Walmart](/docs/api-reference/walmart) | ✓ | | ✓ | ✓ | | ✓ | ✓ | |
| [TikTok Shop](/docs/api-reference/tiktokshop) | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | |
| [AliExpress](/docs/api-reference/aliexpress) | ✓ | ✓ | ✓ | ✓ | | ✓ | | ✓ |

빈 칸은 해당 마켓플레이스에 그 오퍼레이션에 해당하는 기능이 없다는 뜻이며, 예정되어 있다는 뜻이 아닙니다. Amazon
리뷰는 제공하지 않습니다. Shopify는 공통 카테고리 트리가 없는 수백만 개의 독립 스토어이므로 `browse`와 `categories`가
없습니다. 대신 `catalog`로 한 스토어를 나열하세요.

eBay는 **일시적으로 사용할 수 없습니다**. 다시 제공될 때까지 엔드포인트는 `404 UNKNOWN_MARKETPLACE`로 응답합니다.

## 같은 것과 다른 것

| | 모든 곳에서 동일 | 마켓플레이스마다 다름 |
|---|---|---|
| 응답 **타입** | ✓ `SearchResult`, `Product`, `ReviewPage` | |
| 필드 **이름과 의미** | ✓ `price`는 항상 구매자가 오늘 내는 금액입니다 | |
| 필터 **이름과 단위** | ✓ `priceMin`은 항상 주 통화 단위의 소수 금액입니다 | |
| 어떤 **필드가 채워지는지** | | `reviewSummary`는 Amazon과 Walmart만 돌려주고, `stock`을 숫자로 밝히는 곳은 AliExpress뿐입니다 |
| 어떤 **오퍼레이션**이 있는지 | | 위 표를 참고하세요 |
| 어떤 **필터**를 받는지 | | Amazon은 `brands`에 2단위를 과금하고, AliExpress는 `ratingMin`을 받지 않습니다 |
| **페이지네이션** | | Shopify는 `cursor`로, 나머지는 `page`로 넘깁니다 |
| **상품 id** 형식 | | ASIN, 숫자 id, 또는 `shop/handle` |

파서는 한 번만 작성하되, 요청을 작성하기 전에 마켓플레이스 페이지를 읽으세요. 각 페이지에 정확히
무엇을 받는지, 각 선택 필드가 실제로 얼마나 자주 오는지가 나와 있습니다. 공통 필터 어휘는
[Filters](/docs/api-reference/marketplaces/filters)에 있습니다.

## 카테고리와 탐색

`browse`는 키워드 없이 카테고리를 나열하고, `categories`는 어떤 id가 있는지 알려 줍니다. `categoryId` 없이
`categories`를 호출하면 최상위 단계가, id를 넘기면 그 하위 카테고리가 나옵니다. 다른 것은 id의 종류입니다.
Amazon의 부서는 스토어 슬러그이고, Walmart는 밑줄로 이은 체인으로 탐색하는 숫자 id이며,
AliExpress는 일반 카테고리 id입니다.

모든 카테고리에 상품이 있는 것은 아닙니다. 많은 카테고리가 탐색용 단계입니다. `categories?browsableOnly=true`는
`browse`가 받는 id만 돌려줍니다. 카테고리를 탐색할 수 있는지 알 수 없으면 `browsable`은 `false`가 아니라
생략됩니다. 해당 데이터가 없는 마켓플레이스는 `400 BROWSABLE_ONLY_UNAVAILABLE`로 응답합니다.

## 런타임에 확인하기

`GET /v1/marketplaces`는 전체 카탈로그를 공개합니다. 모든 플랫폼, 그 오퍼레이션, 각 비용, 그리고
**각 오퍼레이션 입력의 JSON Schema**입니다. 이 문서를 하드코딩하지 말고 이것을 기준으로 생성하세요.
줄이면 다음과 같습니다.

```json
{
  "success": true,
  "data": {
    "marketplaces": [
      {
        "id": "walmart",
        "kind": "marketplace",
        "operations": ["search", "browse", "categories", "product", "reviews"],
        "regions": ["US"],
        "cost": { "search": { "base": 1, "max": 1 }, "product": { "base": 1, "max": 1 } },
        "params": {
          "search": {
            "type": "object",
            "required": ["query"],
            "properties": { "query": { "type": "string", "minLength": 1, "description": "Keywords to search for. …" } }
          }
        }
      }
    ],
    "pricing": {
      "currency": "USD",
      "unitPrice": { "marketplace": "0.001000", "image-translate": "0.003000" },
      "dayBoundary": "UTC",
      "dailyBrackets": [{ "fromUnits": 0, "ratePct": 100 }, { "fromUnits": 1000, "ratePct": 90 }]
    }
  }
}
```

오퍼레이션 이름은 URL과 똑같이 쓰여 있으므로(`image-search`) 그대로
`/v1/{platform}/{operation}`에 넣으면 됩니다. `kind`는 `marketplace` 또는 `sns`입니다.

## 가격

정가 기준 **단위당 $0.001**이며, 하루 사용량이 늘수록 단계적으로 내려갑니다([Pricing](/pricing) 참고). 대부분의
호출은 1단위입니다. 다음은 더 비쌀 수 있으며, 각각 상한이 있습니다.

| 오퍼레이션 | 가격 | 추가되는 경우 |
|---|---|---|
| Amazon `search`, `browse` | $0.001, 최대 $0.002 | `brands`나 `facets`를 쓰면 2단위 |
| Amazon `image-search` | $0.001, 최대 $0.002 | 사진이 일치하면 2단위, 아무것도 일치하지 않으면 1단위 |
| Amazon `product` | $0.002, 최대 $0.032 | 항상 2단위: 상품 페이지와 하단 정보(사양, 베스트셀러 순위, 평점 분포). `include=offers`: 오퍼 10개 페이지당 1단위 추가, 최대 30페이지 |
| Shopify `reviews` | $0.001, 최대 $0.007 | 첫 페이지는 단위가 추가될 수 있고, `cursor` 페이지는 추가되지 않습니다 |
| AliExpress `product` | $0.001, 최대 $0.002 | `include=shipping`을 쓰면 2단위 |
| AliExpress `shipping` | $0.001, 최대 $0.002 | `sku`가 숫자 SKU id가 아니면 2단위 |

카탈로그는 같은 수치를 단위로 밝힙니다. `cost.base`는 호출이 과금하는 단위, `cost.max`는 최대 과금 단위이며,
1단위는 `pricing.unitPrice`입니다. 실패한 호출은 과금되지 않습니다.

## 레퍼런스

- [Response Schema](/docs/api-reference/marketplaces/response-schema): 모든 타입의 모든 필드
- [Filters](/docs/api-reference/marketplaces/filters): 필터 어휘와 마켓플레이스별로 받는 필터
- [Errors](/docs/errors): 모든 에러 코드