Documentație API

Primii pași

1. Solicită acces din Setări > Acces API.
2. Un vânzător verificat este aprobat instant; altfel vom analiza cererea ta în curând.
3. Odată aprobat, generează-ți tokenul -- este afișat o singură dată, așa că copiază-l undeva în siguranță.
4. Include-l ca token Bearer la fiecare cerere către endpoint-urile de mai jos.

Autentificare

Fiecare cerere (cu excepția endpoint-urilor publice de referință) trebuie să includă tokenul tău în header-ul Authorization:

Authorization: Bearer osk_your_token_here

Tokenurile sunt asociate contului tău -- fiecare anunț pe care îl creezi, editezi sau citești prin API este limitat doar la propriul tău stoc.

Ciclul de viață al unui anunț

Un anunț creat prin API începe întotdeauna ca ciornă, la fel ca atunci când începi unul manual pe site -- nu poate fi publicat fără cel puțin o fotografie, iar acest apel nu poate include una.

1. Trimite POST pentru un anunț nou -- este creat ca ciornă.
2. Încarcă una sau mai multe fotografii pentru el.
3. Trimite POST pentru o schimbare de status (ex. "AV") pentru a-l publica.

Contul căruia îi aparține tokenul tău

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

Valori valide pentru status, vehicle_type, fuel_type etc.

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

Toate dotările pe care le poate avea un anunț -- citește id-urile și trimite-le ca "options" când creezi sau actualizezi un anunț (nu necesită token)

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

Listează toate mărcile de vehicule (fără token necesar)

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

Listează modelele pentru o marcă dată (fără token necesar)

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

Listează propriile tale anunțuri -- filtrabil, vezi mai jos

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

Creează un anunț nou (începe întotdeauna ca ciornă)

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"
  }'

Obține un singur anunț de-al tău

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

Editează câmpurile unui anunț (sunt acceptate actualizări parțiale)

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."}'

Șterge definitiv un anunț și fotografiile sale

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

# 204 No Content on success

Schimbă doar statusul unui anunț

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"}'

Readu un anunț eligibil în fruntea listei

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

Listează fotografiile unui anunț

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

Încarcă o fotografie, prin fișier sau image_url -- adaugă photo_type pentru a încărca o fotografie de daune în loc de una de galerie

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"

Elimină o singură fotografie

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

# 204 No Content on success

Atașează un PDF Carfax, de aliniere sau de inspecție

# 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"}'

Elimină un raport Carfax, de aliniere sau de inspecție

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

Bine de știut

• Cererile sunt limitate la 120 pe minut per cont.
• Fiecare endpoint este limitat la propriile tale anunțuri -- nu există nicio modalitate de a citi sau modifica stocul altui vânzător prin acest API.
• Erorile de validare revin ca un obiect JSON care asociază numele câmpurilor cu mesajele de eroare, la fel ca restul API-ului site-ului.
• Răspunsurile de tip listă sunt paginate (50 pe pagină implicit, până la 200 cu ?page_size=); folosește linkurile next/previous returnate pentru a parcurge restul.