API 概覽

如何取得金鑰、進行身分驗證並開始使用 Market Ninja API——先查找後取得的模式、限制說明和錯誤格式。

Market Ninja API 提供對同一個群眾外包資料集的唯讀程式化存取，也就是您在擴充功能介面中看到的資料：來自 Wildberries、Ozon、Yandex Market 和 Lamoda 的商品、價格（目前與歷史）、賣家和類目。

API 不會自行採集資料，也無法依需求觸發擷取——它只提供對資料集中既有資料的唯讀存取。新商品只能透過 Market Ninja 瀏覽器擴充功能加入資料集：如果資料集中還沒有您需要的商品，請先用擴充功能採集它，之後才能透過 API 取得。

API 僅供伺服器端整合使用（server-to-server）。金鑰是長期有效的憑證，絕不能出現在瀏覽器中執行的程式碼裡（與 Stripe 金鑰的要求相同）。

取得金鑰

金鑰於擴充功能設定的 API 金鑰 區塊簽發，僅 Premium 方案可用。完整的金鑰值（mn_live_...）只會在建立時顯示一次——請立即儲存，之後無法復原（只能撤銷後重新產生）。

每個請求都必須包含以下標頭：

Authorization: Bearer mn_live_your_key

curl -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products?page_size=3"

外部整合方無法預先得知商品在我們資料庫中的內部 id——沒有任何管道能事先取得它。因此您總是從已擁有的資訊開始：

查找商品：呼叫 GET /products，傳入您已擁有的資訊——商品連結（url）、電商平台自身的 SKU（external_id + marketplace），或您自己的內部貨號（seller_code）。

讀取 id：從回應的 data[].id 欄位取得我們的內部識別碼。

如有需要，可透過 id 直接取得該商品（GET /products/{id}）或其價格歷史（GET /products/{id}/price-history）——但請注意，目前價格已包含在第一步的回應中，獨立的請求僅用於分析價格走勢。

詳細情境與範例請參閱：尋找商品、價格歷史、賣家、類目、品牌、批次匯出、擷取工作階段（取得您剛透過擴充功能採集的資料），以及 Webhook（工作階段完成時主動通知，無需輪詢）。每個端點的完整參數與回應說明：參考文件。

所有錯誤都以統一的格式回傳：

{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key" } }

對整合方而言，403 和 401 是兩種不同的問題：「金鑰本身有誤」（需要核對金鑰值）與「需要續訂」（金鑰本身有效，但存取已被暫停）。請不要在程式碼中用同一套邏輯處理它們——顯示給使用者的提示訊息也應有所區分。

請求頻率限制（rate_limited）——限制呼叫頻率，每分鐘重置。相關標頭： X-RateLimit-Limit/X-RateLimit-Remaining/Retry-After。
每日資料量配額（quota_exceeded）——限制您每天可取得的商品記錄數（依回應中實際回傳的記錄數計算，而非請求次數——一次 page_size=500 的請求所消耗的配額，遠高於 page_size=10）。於 UTC 午夜重置。相關標頭：X-Quota-Limit/X-Quota-Used。

這兩組標頭都只會出現在 429 回應中——成功回應中不會包含它們。

快取已解析出的 id。 它不會改變——如果您需要定期查詢同一項商品（例如某個品牌每天核對自己的商品目錄），請在第一次查找後儲存該 id，之後直接依 id 呼叫，而不是重複呼叫 GET /products——同時節省請求次數與配額。
unverified/flagged 資料預設不會被隱藏。 trust_status 欄位一律存在於每筆商品回應中——是否信任一筆尚未獲得佐證的記錄，由您自行判斷，而非由 API 替您決定。
分頁不需要事先得知總頁數——讀取回應中的 meta.total，持續翻頁直到取得所需數量為止。