Аналоги запчастей через API: IAM-номер ≠ OEM-номер

Эндпоинт GET /v1/aftermarket/crosses возвращает список аналогов для заданного артикула: другие бренды, которые производят ту же деталь. Казалось бы, всё просто — пока не упираешься в один нюанс, который ломает половину запросов.

IAM ≠ OEM: главная ошибка

Параметр article принимает IAM-номер (Aftermarket, послепродажный артикул) — то есть номер, который присваивает сам производитель запчасти: Bosch, MANN, Febi, NGK и т.д.

OEM-номер — это совсем другое. Это номер оригинальной запчасти от автопроизводителя: 03L115562 от Volkswagen, 1J0698151B от VW. Если передать OEM-номер в /crosses, ответ будет пустым или некорректным.

Правило простое:

• Есть IAM-номер (F026407123 от Bosch) → используйте /v1/aftermarket/crosses
• Есть OEM-номер (03L115562 от VW) → используйте /v1/aftermarket/search?type=OENumber

Параметры запроса

GET /v1/aftermarket/crosses
    ?article=F026407123
    &brand=BOSCH
    &lang=en

Authorization: Bearer {your_api_key}

article — IAM-артикул. Регистр не важен, но пробелы и разделители должны совпадать с тем, как хранит производитель. Например, Bosch может хранить как F 026 407 123, поэтому рекомендуется сначала найти артикул через /v1/aftermarket/search?type=ArticleNumber и взять article_nr из ответа.

brand — бренд, который выпустил этот артикул. Это важно: артикул W712/95 у MANN и артикул W712/95 у стороннего производителя — разные сущности в базе. Бренд должен совпадать с тем, кто является автором номера.

Структура ответа

{
  "success": true,
  "data": {
    "found": true,
    "article": {
      "art_id": 6926927,
      "article_nr": "F 026 407 123",
      "brand": "BOSCH",
      "name": null
    },
    "crosses": [
      {
        "art_id": 2001,
        "brand": "MANN",
        "article_nr": "W 712/95",
        "matched_oem": "03L 115 562",
        "cross_type": null,
        "article_url": "/api/v1/aftermarket/search?q=W+712%2F95&type=ArticleNumber"
      },
      {
        "art_id": 2002,
        "brand": "MAHLE",
        "article_nr": "OC 229",
        "matched_oem": "03L 115 562",
        "cross_type": null,
        "article_url": "/api/v1/aftermarket/search?q=OC+229&type=ArticleNumber"
      },
      {
        "art_id": 2003,
        "brand": "VOLKSWAGEN",
        "article_nr": "03L115562",
        "matched_oem": "03L 115 562",
        "cross_type": null,
        "article_url": "/api/v1/aftermarket/search?q=03L115562&type=ArticleNumber"
      }
    ]
  }
}

На что обратить внимание:

name: null — норма. Не все артикулы в базе имеют текстовое название. Строить логику на наличии name не стоит; используйте art_id как устойчивый идентификатор.

matched_oem — OEM-номер, через который установлена связь между аналогами. Все аналоги в массиве crosses имеют одну и ту же оригинальную запчасть в основе. Это поле помогает понять, почему именно эти артикулы попали в список.

article_url — готовый проксированный URL для немедленного follow-up запроса. Нашли аналог MANN W 712/95? Просто дёрните article_url — получите полную карточку этого артикула с характеристиками, применяемостью и изображениями.

Типичный сценарий использования

Допустим, у клиента на складе есть Bosch F026407123 (масляный фильтр), и нужно предложить альтернативы. Цепочка вызовов:

1. Поиск артикула → /v1/aftermarket/search?q=F026407123&type=ArticleNumber — убеждаемся что артикул существует, получаем нормализованный article_nr и art_id
2. Получение аналогов → /v1/aftermarket/crosses?article=F026407123&brand=BOSCH — список аналогов с article_url для каждого
3. Детали аналога → следуем по article_url нужного аналога — получаем полную карточку

Стоимость: 2 токена за /crosses + 2 токена за каждый follow-up по article_url.

Playground

Попробовать эндпоинт можно в Playground — поле Article подписано как «IAM article number» с примерами: F026407123 (BOSCH) и W712/95 (MANN). Ответ отображается в реальном времени прямо в браузере.