Документация API

Начало работы

1. Запросите доступ в разделе Настройки > Доступ к API.
2. Верифицированные продавцы одобряются мгновенно; в остальных случаях мы рассмотрим ваш запрос в ближайшее время.
3. После одобрения создайте токен -- он показывается только один раз, поэтому сохраните его в надёжном месте.
4. Указывайте его как Bearer-токен в каждом запросе к эндпоинтам ниже.

Аутентификация

Каждый запрос (кроме публичных справочных эндпоинтов) должен содержать ваш токен в заголовке Authorization:

Authorization: Bearer osk_your_token_here

Токены привязаны к вашему аккаунту -- любое объявление, которое вы создаёте, редактируете или читаете через API, относится только к вашему собственному инвентарю.

Жизненный цикл объявления

Объявление, созданное через API, всегда начинается как черновик -- так же, как если бы вы создавали его вручную на сайте: без хотя бы одного фото его нельзя опубликовать, а этот запрос не может содержать фото.

1. Отправьте POST-запрос для нового объявления -- оно будет создано как черновик.
2. Загрузите к нему одно или несколько фото.
3. Отправьте POST-запрос на смену статуса (например, "AV"), чтобы опубликовать его.

Аккаунт, которому принадлежит ваш токен

curl https://onlysalvage.com/api/v1/me/ \
  -H "Authorization: Bearer osk_your_token_here"

Допустимые значения для status, vehicle_type, fuel_type и т.д.

curl https://onlysalvage.com/api/v1/schema/choices/

Все опции, которые можно указать в объявлении: получите id и отправьте их как "options" при создании или обновлении объявления (токен не нужен)

curl https://onlysalvage.com/api/v1/options/

Список всех марок автомобилей (токен не требуется)

curl https://onlysalvage.com/api/inventory/makes/

Список моделей для указанной марки (токен не требуется)

curl "https://onlysalvage.com/api/inventory/models/?make=21"

Список ваших объявлений -- с фильтрами, см. ниже

curl "https://onlysalvage.com/api/v1/listings/?status=AV&min_price=5000" \
  -H "Authorization: Bearer osk_your_token_here"

Создать новое объявление (всегда начинается как черновик)

curl -X POST https://onlysalvage.com/api/v1/listings/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "1HGCM82633A004352",
    "year": 2018,
    "make": 21,
    "model": 186,
    "price": 9500,
    "vehicle_type": "SDN",
    "title_document": "SA"
  }'

Получить одно из ваших объявлений

curl https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here"

Редактировать поля объявления (поддерживаются частичные обновления)

curl -X PATCH https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"price": 8900, "description": "Price reduced -- motivated seller."}'

Безвозвратно удалить объявление и его фото

curl -X DELETE https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Изменить только статус объявления

curl -X POST https://onlysalvage.com/api/v1/listings/123/status/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "AV"}'

Поднять подходящее объявление обратно наверх

curl -X POST https://onlysalvage.com/api/v1/listings/123/renew/ \
  -H "Authorization: Bearer osk_your_token_here"

Список фото объявления

curl https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here"

Загрузить фото -- файлом или через image_url -- добавьте photo_type, чтобы загрузить фото повреждений вместо обычного фото галереи

curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "file=@photo.jpg"

# or, from an existing hosted URL instead of a local file:
curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'

# add photo_type=before_repair to upload a damage photo instead of a
# regular gallery photo (omit it, or send "gallery", for a normal photo):
curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "file=@damage.jpg" \
  -F "photo_type=before_repair"

Удалить одно фото

curl -X DELETE https://onlysalvage.com/api/v1/listings/123/images/456/ \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Прикрепить PDF-отчёт Carfax, развал-схождения или осмотра

# Upload the file...
curl -X POST https://onlysalvage.com/api/v1/listings/123/documents/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "type=carfax" \
  -F "file=@carfax.pdf"

# ...or just send a link and we'll fetch it. The link must be publicly
# reachable and point straight at the PDF, not at a preview page.
curl -X POST https://onlysalvage.com/api/v1/listings/123/documents/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "carfax", "file_url": "https://example.com/reports/carfax.pdf"}'

Удалить отчёт Carfax, развал-схождения или осмотра

curl -X DELETE "https://onlysalvage.com/api/v1/listings/123/documents/?type=carfax" \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Полезно знать

• Запросы ограничены до 120 в минуту на аккаунт.
• Каждый эндпоинт ограничен вашими собственными объявлениями -- через этот API нельзя прочитать или изменить инвентарь другого продавца.
• Ошибки валидации возвращаются в виде JSON-объекта, сопоставляющего имена полей с сообщениями об ошибках -- так же, как и в остальном API сайта.
• Ответы со списками постранично разбиты (по умолчанию 50 на страницу, до 200 с ?page_size=); используйте возвращаемые ссылки next/previous для перехода по страницам.