尋找商品

GET /products 是唯一的進入點，只要您還不知道商品的內部 id（關於「先查找後取得」的模式， 請參閱 API 概覽）。以下是四個實際使用情境，各自搭配不同的參數組合。

情境 1：您已有商品連結

最常見的情況——連結直接從瀏覽器複製，或從表格中取得。

curl -G -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products" \
  --data-urlencode "url=https://www.wildberries.ru/catalog/231151629/detail.aspx?utm_source=instagram"

情境 2：您知道電商平台的 SKU

如果您手上有某個電商平台專屬的 SKU（WB 的 nmId、Ozon 的 sku 等）——請連同 marketplace 一併傳入，否則結果可能出現歧義（同一個 external_id 理論上可能出現在不同平台上）。

curl -G -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products" \
  --data-urlencode "external_id=231151629" \
  --data-urlencode "marketplace=wildberries"

情境 3：您知道賣家貨號

這是一個獨立參數——seller_code——請勿與 external_id 混淆（後者是我們的電商平台 SKU， 而 seller_code 是您自己的、賣家在自家商品頁面上標註的那個貨號）。典型需求是「找出我這個貨號 在哪裡都有販售」，因此該參數刻意不要求必須搭配 seller_id 使用——如果您的商品被多個賣家轉售， 您會看到所有相符結果。

curl -G -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products" \
  --data-urlencode "seller_code=BV2648-010"

如果只想限定在某一位賣家範圍內——請加上 seller_id（可選擇再加上 marketplace）：

curl -G -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products" \
  --data-urlencode "seller_code=BV2648-010" \
  --data-urlencode "seller_id=2557" \
  --data-urlencode "marketplace=wildberries"

情境 4：需要品牌的全部商品

這是一個獨立參數——brand——請勿與情境 3 混淆：seller_code 用於查找您某個特定 貨號在所有轉售管道中的記錄，而 brand 則查找資料集中該品牌的全部商品，與貨號無關， 採用不區分大小寫的精確比對。可用品牌名稱清單與範例請參閱品牌。

其他篩選方式

GET /products 也支援更廣泛的搜尋——例如依名稱（q）或類目（category，與 category_path 做包含比對——某電商平台的類目清單及完整篩選指南請參閱 類目）。完整參數清單請見參考文件。

取得結果之後

回應中已經包含目前價格、圖片、規格參數、可信度狀態與賣家資訊——大多數情境無需再另外呼叫 GET /products/{id}。只有當您需要在某個特定時間點取得保證最新的狀態、且與查找結果本身 彼此獨立時，才直接依 id 呼叫它。