API Avtoorder для партнёров

1. Откройте форму обратной связи и выберите тему «Сотрудничество».
2. Напишите «API access», название компании, сценарий использования и IP-адреса серверов, с которых будете обращаться.
3. Мы создадим для вас клиента и передадим ключ по закрытому каналу. Ключ показывается один раз, сохраните его надёжно.
4. У ключа есть область действия: весь каталог или только автомобили из собственного наличия Avtoorder. Вызовите GET /me, чтобы увидеть её.

• Передавайте ключ только как Authorization: Bearer avto_live_… в заголовке запроса.
• Ключ в строке запроса отклоняется с кодом 400 key-in-query, а сам ключ помечается как скомпрометированный: адреса попадают в логи и историю браузера. Если это случилось, перевыпустите ключ.
• Ключ можно ограничить списком IP-адресов.
• Ключ можно перевыпустить с переходным периодом, в течение которого старый ключ ещё работает, и в любой момент немедленно отозвать.
• Храните ключи на сервере. Не встраивайте их в браузерный или мобильный код.

Пример

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "minute";q=60;w=60, "day";q=20000;w=86400
RateLimit: "minute";r=0;t=12

{
  "type": "https://avtoorder.com/en/developers#error-rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "requestId": "0f3c…"
}

• Цена «под ключ» (turnkeyEstimate) — оценка, а не предложение. В ней есть isEstimate: true, использованный курс, его источник (fx.rateSource) и время фиксации (fx.capturedAt).
• Все допущения, сделанные при расчёте, перечислены в customs.assumptions. totalIsLowerBound: true (неизвестна мощность двигателя или таможенная пошлина) означает, что реальная сумма может быть выше. Неизвестная дата регистрации отмечается отдельно (registrationUnknown), но не делает сумму нижней границей.
• Если цена автомобиля неизвестна, priceCny равен null, а priceOnRequest равен true. Никогда не 0. Для таких автомобилей оценки нет, а turnkeyUnavailableReason равен price_on_request. Для некоторых объявлений мы вообще не рассчитываем стоимость «под ключ» (например, для объявлений с ценой в USD, см. askingPrice.currency) — тогда turnkeyUnavailableReason равен not_offered_for_listing.
• totalEstimate в списках приблизителен, может меняться между страницами и может быть равен 0, даже когда truncated равно true. Не используйте его, чтобы решить, когда остановить обход.
• sort=recommended (по умолчанию) — смешанное ранжирование, в котором чередуются автомобили из разных частей каталога; newest — тоже смешанное ранжирование, но внутри каждой части каталога более новые автомобили идут первыми, это не строгая сортировка по дате публикации; price_asc и price_desc — по возрастанию и по убыванию цены; mileage_asc — сначала с наименьшим пробегом; year_desc — сначала с наибольшим year. year — год автомобиля в том виде, в каком его указывает объявление: у большинства подержанных автомобилей это год первой регистрации, у некоторых — модельный год. firstRegistration — месяц и год первой регистрации, если они известны.
• fuel берётся из объявления — из указанного в нём типа силовой установки, если он надёжен, иначе из однозначного обозначения технологии или двигателя в названии (например, DM-i — это plugin_hybrid, 280TSI — gasoline) — и равно null, если ни то ни другое его не указывает. Автомобиль с fuel: null не попадает под фильтр fuel, поэтому в выдаче с этим фильтром — автомобили, у которых этот тип известен, а не обязательно все такие. Гибриды с увеличенным запасом хода (EREV) указываются как hybrid. condition: used — автомобиль не отмечен как новый; автомобили с condition: null тоже могут попадать в выдачу, в том числе при фильтре condition=used.
• locale задаёт язык названий и подписей там, где есть перевод; названия автомобилей, комплектации и некоторые значения характеристик часто приходят на английском или китайском независимо от locale.
• GET /brands возвращает ключи марок, известных каталогу: у некоторых сейчас может не быть автомобилей, а count равен null, если количество неизвестно. Ключи марок и моделей могут содержать не только ASCII-символы (например, китайские), поэтому кодируйте их для URL.
• Фото отдаются по нашим собственным ссылкам (размеры 384, 640, 1080 и 1920 через ?w=). Ссылки стабильны, но не гарантированно вечны: после отзыва ключа новые фото по ним больше не загружаются, хотя уже закэшированные изображения могут ещё какое-то время открываться, а ссылка на удалённое фото перестаёт работать. Обновляйте их из API при повторной синхронизации.
• VIN-номера скрыты, кроме автомобилей из собственного наличия Avtoorder.