Apinoa Docs

Marketplace API

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

원본 .mdx 보기

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

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"

오퍼레이션

오퍼레이션반환하는 일
searchSearchResult키워드에 맞는 상품, 필터 지원
image-searchSearchResult사진에 맞는 상품
browseSearchResult키워드 없이 한 카테고리의 상품
categoriesCategoryList카테고리 트리의 한 단계. browse가 받는 id를 찾는 데 씁니다
catalogSearchResult한 스토어의 모든 상품
productProduct상품 하나의 전체 정보: 옵션, 이미지, 사양, 판매자, 배송
reviewsReviewPage상품 리뷰, 한 페이지씩
shippingShippingQuote상품 하나를 특정 국가로 보내는 배송비, 운송사별

모든 타입은 Response Schema에 필드별로 설명되어 있습니다.

마켓플레이스별 지원 범위

searchimage-searchbrowsecategoriescatalogproductreviewsshipping
Amazon✓✓✓✓✓
Shopify✓✓✓✓✓
Walmart✓✓✓✓✓
TikTok Shop✓✓✓✓✓✓
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에 있습니다.

카테고리와 탐색

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입니다. 이 문서를 하드코딩하지 말고 이것을 기준으로 생성하세요. 줄이면 다음과 같습니다.

{
  "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 참고). 대부분의 호출은 1단위입니다. 다음은 더 비쌀 수 있으며, 각각 상한이 있습니다.

오퍼레이션가격추가되는 경우
Amazon search, browse$0.001, 최대 $0.002brands나 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.002include=shipping을 쓰면 2단위
AliExpress shipping$0.001, 최대 $0.002sku가 숫자 SKU id가 아니면 2단위

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

레퍼런스

  • Response Schema: 모든 타입의 모든 필드
  • Filters: 필터 어휘와 마켓플레이스별로 받는 필터
  • Errors: 모든 에러 코드

버전 관리

버전은 경로에 있습니다. 현재 버전은 v1입니다. v1에 추가될 수 있는 것과, 버전 없는 이전 URL의 동작을 설명합니다.

Response Schema

SearchResult, Product, ReviewPage, CategoryList, ShippingQuote — 모든 마켓플레이스가 돌려주는 정규화된 타입을 필드 단위로.

이 페이지 내용

오퍼레이션마켓플레이스별 지원 범위같은 것과 다른 것카테고리와 탐색런타임에 확인하기가격레퍼런스