Документація 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 у відповіді, щоб перейти до решти.