Два API и тестовый ключ

Главное

Требуемые для админки данные по артикулу (габариты, вес, кросс-номера, применимость) есть только в PartsIndex API, а не в Parts-Catalogs (OEM-каталоги). Это подтверждено разбором обеих OpenAPI-спецификаций и живыми запросами.

Parts-Catalogs vs PartsIndex

	Parts-Catalogs	PartsIndex
Base URL	https://api.parts-catalogs.com/v1	https://api.parts-index.com/v1
Спецификация	OpenAPI 3.0.0, v1.18.0	OpenAPI 3.0.3
Модель данных	каталог → модель → авто → группы → детали	по артикулу+бренду
Поиск	по дереву, по VIN/FRAME	по артикулу, по авто (марка→двигатель)
Даёт размеры/вес/аналоги по артикулу	❌	✅
Документация	обзор, эндпоинты	справочник

Авторизация

Оба API используют заголовок (не Bearer):

Authorization: <персональный-ключ>

Ключ выдаёт менеджер Tradesoft. Хранить как секрет (в .env, не в коде, не в БД, не возвращать в ответах).

Тестовый ключ (OEM)

Ключ OEM-API-F1B2A560-… (активен до 2026-07-11):

• Открывает только Parts-Catalogs (OEM-каталоги).
• На PartsIndex → 403 access deny (нужен ключ со scope access, info, relations, old-apply).
• Привязан к IP-whitelist: запрос с не-разрешённого IP → 403 errorCode 1003 "IP not allowed". Боевой сервер должен выходить в интернет с whitelisted-IP.

Лимиты запросов

Ни в OpenAPI-спецификации Parts-Catalogs, ни в живых заголовках ответов числовых лимитов нет — только код ошибки 403 / errorCode 1003 без конкретных цифр, если поставщик всё же откажет по квоте. Цифры «100 VIN» / «10 VIN», ранее указанные здесь, были получены неофициально (со слов менеджера), письменно поставщиком не подтверждены — поэтому админка их больше не использует как жёсткий лимит (см. app/core/sources.py): она только считает фактический расход, без порогов «норма/предупреждение». Если понадобится реальный лимит — уточняйте его у менеджера Tradesoft и письменно фиксируйте здесь.

Коды ошибок

Тело ошибки: { code, message } (PartsIndex) / { code, errorCode, message } (Parts-Catalogs).

Код	Значение
403 / 1003	access deny — IP не в whitelist / нет scope / исчерпана квота / домен
400	некорректный запрос
401	нет данных авторизации
404	не найдено / пустая строка поиска
422	не передан обязательный параметр
500/502/504	ошибки сервера/шлюза

Боевой ключ PartsIndex

Ключ PI-… открывает продукты PartsIndex (scope access, info, relations, cars): «Информация о детали», «Каталог автотоваров», «Детали по VIN». Админка сейчас использует Информацию о детали (размеры, вес, применимость, кроссы).

Аналогично Parts-Catalogs — конкретных суточных квот в документации API PartsIndex нет (ни в OpenAPI-спеке, ни в заголовках ответов), только код 403 / 1004 "quota deny", если поставщик всё же ограничит. Ранее здесь стояли цифры 1000/1000/50 — они были неофициальными (со слов менеджера) и не подтверждены документацией, поэтому убраны и из этого файла, и из app/core/sources.py: система больше не показывает и не считает «% от лимита», только фактический расход запросов.

IP-whitelist и обход VPN

Ключ привязан к IP-whitelist. Сервер сидит за VPN (для сторонних задач), поэтому запросы к PartsIndex должны выходить с whitelisted-IP 85.175.98.244 в обход VPN — иначе 403 "IP not allowed", и задания встают в blocked. На сервере это решено статическими маршрутами /32 к IP API-серверов через физический шлюз (VPN-путь остальных сервисов не затрагивается).

При переносе

На новом сервере нужно внести его внешний IP в whitelist ключа PartsIndex (curl -s https://api.ipify.org), иначе live-режим будет отдавать 403.

Смена ключа и проверка из админки

Ключи обоих источников меняются без рестарта в админке: вкладка Администрирование → API-ключи. Там же:

• статус ключа виден сразу при открытии вкладки — проверяется автоматически, без клика; кнопка «Проверить» просто повторяет ту же живую проверку по запросу и показывает результат по-русски (ключ протух / IP не в whitelist / квота исчерпана / сервис недоступен) с явной подсказкой кому решать проблему — оператору самому (добавить IP в кабинете поставщика), поставщику данных (написать менеджеру) или разработчику (похоже на техническую проблему сервера);
• внешний IP сервера отображается рядом с полями ввода — именно его нужно внести в whitelist в кабинетах PartsIndex и Tradesoft;
• ключ хранится в БД (app_settings) и имеет приоритет над .env; пустое сохранение возвращает ключ из .env. Новый ключ подхватывается воркером в течение ~30 секунд.

Статус ключей видят и операторы, не только admin

Раздел «Администрирование → API-ключи» (маскированный ключ, правка, живая проверка) доступен только роли admin. Но сам факт «источник сейчас не работает» должен быть виден и оператору, который создаёт задания — иначе он не поймёт, почему задание встало blocked, пока не спросит админа.

Для этого есть GET /status — доступен любому авторизованному пользователю. Отдаёт per-источник статус (ok/status/who/who_label/ message) и расход запросов за сегодня, но без ключа (даже маскированного) и без возможности его поменять. На фронте это баннер (SourceStatusBanner.vue) — появляется наверху любой страницы, если у источника проблема или квота близка к исчерпанию, обновляется раз в минуту, молчит, если всё в порядке. Подробности формата — в приложении «События, ошибки, логирование», §6.4.

Вывод для проекта

• Админка сопоставления работает на PartsIndex (боевой ключ, режим live).
• Тестовый OEM-ключ пригоден для разработки/проверки Parts-Catalogs (каталоги, VIN).