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，持续翻页直到获取到所需数量为止。