Documentazione API Partner

API key dealer

Bearer ym_live_... oppure header X-API-Key con lo stesso valore. Il prefisso keyPrefix identifica la chiave per supporto e rotazione.

Scope granulari

Permessi separati: vehicles:read, vehicles:write, media:write, submissions:read, stock-status:write.

Pratiche pending

Creazioni e update vanno in revisione YouMotor prima della pubblicazione sul portale.

Media multipart

Massimo 40 immagini e 160 MB complessivi per invio. URL restituiti pronti per il payload.

Flusso consigliato

1
Provisioning autosalonePOST /partner/saloni con chiave di provisioning dedicata (es. ym_partner_..., una per integratore). Poi salvare l’API key ym_live_ restituita per lo stock.
2
Verifica API keyGET /partner/me per confermare autenticazione e scope attivi.
3
CatalogoGET /partner/vehicle-catalog/makes e /models per marca e modello, GET /partner/vehicle-options per i campi a scelta obbligata. Auth consigliata: Bearer ym_live_... con scope vehicles:read.
4
Upload fotoPOST /partner/vehicles/:plate/photos e salvare gli URL restituiti.
5
Crea annuncioPOST /partner/vehicles con payload completo. Il veicolo entra in stato pending.
6
Monitora praticheGET /partner/submissions per leggere note e correggere dati richiesti da YouMotor.
7
Gestione stockPOST /partner/vehicles/:id/sold quando il veicolo è venduto.

Autenticazione

Le route /partner/* richiedono token partner e/o API key dealer. Il catalogo pubblico GET /public/vehicle-options è anonimo (solo client YouMotor).

Token provisioning (integratore)

GET /partner/saloni e POST /partner/saloni — una chiave distinta per ogni multicaricatore

Authorization: Bearer ym_partner_xxx

Formato: Bearer ym_partner_...

Dealer API key

Stock, pratiche, upload: scope come da accordo

Authorization: Bearer ym_live_xxx
— oppure —
X-API-Key: ym_live_xxx

Formato: Bearer ym_live_...

Catalogo veicoli

GET /partner/vehicle-catalog/* e /partner/vehicle-options — API key dealer con vehicles:read (consigliato). Con accordo, anche Bearer ym_partner_... sugli stessi endpoint.

Authorization: Bearer ym_live_xxx

Formato: Bearer ym_live_...

Flusso integrazione (end-to-end)

Ordine operativo consigliato: credenziali, catalogo, caricamento media, pratiche e gestione stock.

Fase A — Credenziali e accesso

Viene consegnata una chiave di provisioning ym_partner_..., da usare come Bearer solo sui servizi di creazione ed elenco saloni. È personale del vostro accordo: non condividetela tra integrazioni o ambienti diversi senza coordinamento con YouMotor.
POST /partner/saloni con Authorization: Bearer ym_partner_... crea l'autosalone. La password temporanea per il portale salone arriva solo via email all'indirizzo inviato nel body; non è nel JSON di risposta.
Con issueApiKey: true la risposta include dealerApiKey con la chiave completa ym_live_... (mostrata una sola volta) e l'oggetto apiKey con metadati (id, keyPrefix, scopes).
GET /partner/me con la ym_live_... verifica dealer e scope attivi.

Fase B — Catalogo e payload

Marca e modello: GET /partner/vehicle-catalog/makes, poi /models?makeId= con il code della marca. Scrivete la description nei campi make e model; la version è testo libero.
Campi a scelta obbligata: GET /partner/vehicle-options (alimentazione, cambio, colore, optional…). Nel payload va sempre option.value.
Caricate le foto con POST /partner/vehicles/{TARGA}/photos (multipart, campo images). Usate gli URL in uploaded[].url nel JSON dell'annuncio (coverImage, gallery).
POST /partner/vehicles crea una pratica pending: la risposta contiene l'UUID della submission (id), non l'id del veicolo pubblicato. Dopo l'approvazione YouMotor, il veicolo compare in GET /partner/vehicles con il suo UUID.
Seguite GET /partner/submissions e, se serve, PATCH /partner/submissions/:id per correggere il payload mentre è ancora in pending.
Aggiornamenti a veicoli già esistenti: PATCH /partner/vehicles/:id con l'UUID veicolo. Vendita/archivio: POST /partner/vehicles/:id/sold, DELETE .../sold, POST .../archive, POST .../unarchive (scope stock-status:write).

Sicurezza delle chiavi

Trattate ym_partner_... e ym_live_... come segreti: conservateli solo su server controllati da voi, usate sempre HTTPS, evitate di esporli in app o browser pubblici e non li incluse nei log applicativi. In caso di compromissione o dubbio, revocate la chiave con YouMotor e richiedetene una nuova.

Per provare le chiamate potete usare la Postman collection scaricabile dal pulsante in alto in questa pagina.

Partner provisioning

Creazione e elenco autosaloni tramite token partner. Richiede accordo commerciale con YouMotor.

GEThttps://api.youmotor.com/api/v1/partner/saloniPartner token

Lista autosaloni del partner

Elenco degli autosaloni collegati alla vostra chiave di provisioning: la lista riflette solo i saloni creati con lo stesso Bearer usato in questa richiesta.

Rate limit dedicato: 120 richieste al minuto per indirizzo IP.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/saloni" \
  -H "Authorization: Bearer <partner_token>"

POSThttps://api.youmotor.com/api/v1/partner/saloniPartner token

Crea autosalone da partner autorizzato

Crea un nuovo autosalone collegato alla vostra integrazione, usando la chiave di provisioning (Bearer). Con `issueApiKey: true` la risposta può includere una API key `ym_live_...` mostrata **una sola volta**: va copiata e custodita in modo sicuro.

La chiave completa è nel campo dealerApiKey (non in apiKey). Non è recuperabile in seguito.
externalAccount.customerReference collega il dealer al CRM del partner.
Rate limit dedicato: 60 richieste all'ora per indirizzo IP.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/saloni \
  -H "Authorization: Bearer <partner_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "email": "dealer@autorossi.it",
    "displayName": "Auto Rossi",
    "legalName": "Auto Rossi Srl",
    "phone": "+390212345678",
    "vatNumber": "12345678901",
    "address": {
      "line1": "Via Roma 10",
      "city": "Milano",
      "province": "MI",
      "postalCode": "20100",
      "country": "IT"
    },
    "issueApiKey": true,
    "apiKeyLabel": "multicaricatore",
    "externalAccount": {
      "provider": "partner-name",
      "customerReference": "customer-123"
    }
  }'

Partner — Catalogo

I valori ammessi per gli annunci: marche, modelli e liste di opzioni. Sono gli stessi dati usati dal portale salone, dal sito pubblico e dall'app mobile, quindi ciò che caricate via API è identico a ciò che vede l'utente finale. Autenticazione: API key dealer con scope vehicles:read, oppure token partner di provisioning.

Come si compila un annuncio

Due soli endpoint coprono tutti i campi vincolati. Tutto il resto è testo libero.

Marca e modello

/vehicle-catalog/makes → /models

Leggete l'elenco marche, poi i modelli passando il code della marca in makeId. Nell'annuncio scrivete la description restituita.

Campi a scelta obbligata

/vehicle-options

Alimentazione, cambio, trazione, colore, garanzia e optional. Nell'annuncio scrivete option.value: altri valori vengono rifiutati.

Campi liberi

Versione, titolo, descrizione, prezzo, km e targa arrivano dal vostro gestionale: non c'è nessun catalogo da consultare.

Origine dei campi dell'annuncio

Campo annuncio	Sorgente	Valore da inviare
make	Catalogo veicoli	description da /vehicle-catalog/makes
model	Catalogo veicoli	description da /vehicle-catalog/models?makeId=…
version	Testo libero	Allestimento commerciale, es. «320d xDrive Msport»
fuel_type · transmission · drivetrain · segment · body_type	Opzioni annuncio	option.value del gruppo con lo stesso nome
color · warranty · service_history · availability · owners · condition · emission_class	Opzioni annuncio	option.value del gruppo con lo stesso nome
province	Opzioni annuncio	option.value del gruppo province; region è restituita automaticamente
location	Compatibilità legacy	alias compatibile di province; usare province nelle nuove integrazioni
equipment · safety · comfort · infotainment	Opzioni annuncio	Array di option.value; almeno una lista valorizzata
title · description · highlights	Testo libero	Testi commerciali dell'annuncio
price · km · mileage · model_year · first_registration · plate	Testo libero	Dati del veicolo dal vostro gestionale

GEThttps://api.youmotor.com/api/v1/partner/vehicle-catalog/makesToken / API key

Elenco marche

Elenco completo delle marche riconosciute da YouMotor. È lo stesso catalogo usato dal portale salone, dal sito pubblico e dall'app mobile, quindi garantisce che gli annunci caricati via API siano filtrabili e comparabili come tutti gli altri.

Nel payload annuncio scrivere description (es. "BMW") nel campo make.
Conservare code: serve come makeId per ottenere i modelli.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/vehicle-catalog/makes" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

GEThttps://api.youmotor.com/api/v1/partner/vehicle-catalog/modelsToken / API key

Elenco modelli di una marca

Modelli disponibili per la marca selezionata. Va chiamato dopo l'elenco marche, passando in makeId il code ottenuto da quella risposta.

Nel payload annuncio scrivere description (es. "Serie 3") nel campo model.
L'allestimento non è catalogato: il campo version dell'annuncio è testo libero (es. "320d xDrive Msport").

Parametri

Nome	In	Tipo	Descrizione
makeId*	query	string	Campo code della marca, ottenuto da GET /partner/vehicle-catalog/makes (es. 9 per BMW).

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/vehicle-catalog/models?makeId=9" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

GEThttps://api.youmotor.com/api/v1/partner/vehicle-optionsToken / API key

Opzioni a scelta obbligata dell'annuncio

Restituisce tutti i valori ammessi per i campi a scelta obbligata dell'annuncio: alimentazione, cambio, trazione, colore, garanzia, optional e altri. Copiare option.value nel payload: valori diversi vengono rifiutati in validazione.

Nel payload annuncio va scritto option.value, non option.key.
Senza il parametro groups la risposta contiene tutti i 15 gruppi elencati sotto.
I valori cambiano raramente: consigliata una cache lato vostro con aggiornamento giornaliero.
equipment, safety, comfort e infotainment sono array di stringhe: almeno una delle quattro liste deve essere valorizzata.

Parametri

Nome	In	Tipo	Descrizione
groups	query	string	Filtro opzionale: chiavi gruppo separate da virgola (es. fuel_type,transmission,equipment). Valori ammessi: fuel_type, transmission, segment, body_type, condition, drivetrain, emission_class, availability, warranty, service_history, color, owners, equipment, safety, comfort, infotainment, province. Le province includono metadata code, region, current e legacy.

Gruppi disponibili e valori restituiti

Ogni riga corrisponde a un groups= valido. La risposta include key, label e options[] con oggetti { key, label, value, position, metadata }. Nel payload annuncio usare il campo value (non key).

conditionCondizione→conditionstring

Valori value: nuovo · km0 · usato

emission_classClasse ambientale→emission_classstring

Valori value: Euro 0 · Euro 1 · Euro 2 · Euro 3 · Euro 4 · Euro 5 · Euro 5a · Euro 5b · Euro 6 · Euro 6a · Euro 6b · Euro 6c · Euro 6d-TEMP · Euro 6d · Euro 6d-ISC-FCM · Euro 6e · Euro 6e-bis · Euro 6e-bis-FCM · Euro 7-TEMP · Euro 7A · Euro 7B · Euro 7C

fuel_typeAlimentazione→fuel_typestring

Valori value: Benzina · Diesel · Ibrida · Ibrida Plug-in · Elettrica

transmissionCambio→transmissionstring

Valori value: Manuale · Automatico · Semiautomatico

segmentSegmento→segmentstring

Valori value: SUV · Berlina · City Car · Station Wagon · Coupé

body_typeCarrozzeria→body_typestring

Valori value: SUV · Berlina · City Car · Station Wagon · Coupé · Cabrio · Monovolume · Furgone · Pickup

drivetrainTrazione→drivetrainstring

Valori value: Anteriore · Posteriore · Integrale · AWD · 4x4 inseribile · 4x4 permanente

availabilityDisponibilità→availabilitystring

Valori value: Nuova · KM0 · Usata · Usata garantita · Pronta consegna · Disponibile a breve · In arrivo · Su ordinazione · In trattativa · Prenotata

warrantyGaranzia→warrantystring

Valori value: Nessuna · 6 mesi concessionario · 12 mesi legale conformita · 12 mesi concessionario · 12 mesi estensione premium · 24 mesi concessionario · 24 mesi estensione premium · 36 mesi concessionario · 48 mesi concessionario · 60 mesi concessionario · Garanzia usato certificato · Garanzia ufficiale casa madre · Garanzia ufficiale residua · Garanzia batteria EV residua · Garanzia estendibile fino a 36 mesi · Garanzia estendibile fino a 48 mesi · Garanzia estendibile fino a 60 mesi

service_historyCronologia tagliandi→service_historystring

Valori value: Tagliandi ufficiali completi · Tagliandi certificati ufficiali · Tagliandi certificati indipendenti · Tagliandi regolari documentati · Tagliandi ufficiali + indipendenti · Storico parziale disponibile · Storico digitale disponibile · Cronologia completa con fatture · Nessun storico disponibile · Fatture manutenzione disponibili · Ultimo tagliando appena eseguito · Distribuzione sostituita · Batteria EV verificata

colorColore esterno→colorstring

Valori value: Bianco · Bianco Perla · Bianco Ghiaccio · Nero · Nero Metallizzato · Nero Opaco · Grigio · Grigio Chiaro · Grigio Scuro · Grigio Metallizzato · Argento · Blu · Blu Chiaro · Blu Scuro · Blu Notte · Azzurro · Rosso · Rosso Corsa · Rosso Bordeaux · Arancione · Giallo · Verde · Verde Scuro · Marrone · Bronzo · Oro Champagne · Viola Metallizzato · Rosa Cipria · Bicolore Tetto Nero · Bicolore Nero/Bianco

ownersProprietari precedenti→ownersnumber

Valori value: 0 · 1 · 2 · 3 · 4

equipmentEquipaggiamento→equipmentstring[]

Valori value: 360° camera · Abilitata per E10 · Adatto a persone con disabilità · Cerchi in lega · Cerchioni in acciaio · Certificato della batteria · Conversione biodiesel · Deflettori · Divisori per bagagliaio · Fari al laser · Fari bi-Xeno · Fari di profondità antiabbagliamento · Fari direzionali · Fari full-LED · Fari LED · Fari Xenon · Fendinebbia · Gancio traino · Guida a destra · Kit antipanne · Kit fumatori · Luci diurne · Luci diurne LED · Marmitta catalitica · Pacchetto invernale · Pacchetto sportivo · Parabrezza riscaldato · Pneumatici da neve · Pneumatici estivi · Pneumatici quattro stagioni · Pompa di calore · Porta scorrevole · Porta scorrevole a destra · Porta scorrevole a sinistra · Portapacchi · Portellone posteriore elettrico · Range extender · Ricarica bidirezionale · Riscaldamento ausiliario · Ruota di riserva · Ruotino · Sistema lavafari · Ski bag · Sospensioni pneumatiche · Sospensioni sportive · Spoiler · Taxi o auto a noleggio · Tendalino · Tetto panoramico · Tettuccio apribile · Trazione integrale · Veicolo elaborato · Vetri oscurati

safetySicurezza→safetystring[]

Valori value: ABS · Adaptive Cruise Control · Airbag conducente · Airbag laterali · Airbag passeggero · Airbag posteriore · Airbag testa · Antifurto · Assistente abbaglianti · Blind spot monitor · Controllo automatico trazione · Controllo elettronico della corsia · ESP · Frenata d'emergenza assistita · Hill Holder · Immobilizzatore elettronico · Isofix · Limitatore di velocità · Riconoscimento dei segnali stradali · Sistema di avviso di distanza · Sistema di chiamata d'emergenza · Sistema di controllo pressione pneumatici · Sistema di riconoscimento della stanchezza · Sistema di visione notturna

comfortComfort→comfortstring[]

Valori value: Alzacristalli elettrici · Bracciolo · Carica per smartphone a induzione · Chiusura centralizzata · Chiusura centralizzata senza chiave · Chiusura centralizzata telecomandata · Climatizzatore · Climatizzatore automatico · Climatizzatore automatico, 2 zone · Climatizzatore automatico, 3 zone · Climatizzatore automatico, 4 zone · Computer di bordo · Cruise control · Freno di stazionamento elettrico · Interni in pelle · Leve al volante · Luce d'ambiente · Park Distance Control · Regolazione elettrica del sedile posteriore · Regolazione elettrica sedili · Sedile passeggero ribaltabile · Sedile posteriore sdoppiato · Sedili massaggianti · Sedili posteriori riscaldabili · Sedili riscaldati · Sedili sportivi · Sedili ventilati · Sensore di luminosità · Sensore di pioggia · Sensori di parcheggio assistito anteriori · Sensori di parcheggio assistito posteriori · Servosterzo · Sistema di parcheggio automatico · Specchietti laterali elettrici · Specchietto retrovisore con funzione antiabbagliamento · Start/Stop Automatico · Supporto lombare · Telecamera per parcheggio assistito · Volante in pelle · Volante riscaldato

infotainmentInfotainment→infotainmentstring[]

Valori value: Android Auto · Apple CarPlay · Autoradio · Autoradio digitale · Bluetooth · CD · Controllo vocale · Funzione TV · Head-up display · Hotspot Wi-Fi · MP3 · Schermo multifunzione interamente digitale · Sistema di navigazione · Sound system · Streaming musicale integrato · Touch screen · USB · Vivavoce · Volante multifunzione

provinceProvincia / città→locationstring

Valori value: Agrigento · Alessandria · Ancona · Aosta · Arezzo · Bari · Bergamo · Bologna · Bolzano · Brescia · Cagliari · Catania · Como · Firenze · Genova · Milano · Modena · Napoli · Padova · Palermo · Parma · Roma · Torino · Trento · Treviso · Varese · Venezia · Verona · Vicenza

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/vehicle-options?groups=fuel_type,transmission,equipment" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

GEThttps://api.youmotor.com/api/v1/partner/quattroruote/marcheToken / API key

Marche legacy — deprecato

Endpoint mantenuto solo per compatibilità. Migrare a /partner/vehicle-catalog/makes entro il 31 gennaio 2027; la risposta include gli header Deprecation e Sunset.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/quattroruote/marche" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

GEThttps://api.youmotor.com/api/v1/partner/quattroruote/modelliToken / API key

Modelli legacy — deprecato

Endpoint mantenuto solo per compatibilità. Migrare a /partner/vehicle-catalog/models?makeId=... entro il 31 gennaio 2027.

Parametri

Nome	In	Tipo	Descrizione
codiceMarca*	query	string	Identificativo marca legacy.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/quattroruote/modelli?codiceMarca=9" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

GEThttps://api.youmotor.com/api/v1/partner/quattroruote/allestimentiToken / API key

Allestimenti legacy — deprecato

Endpoint mantenuto solo fino al 31 gennaio 2027. Nel contratto corrente il campo version è testo libero e non esiste un endpoint sostitutivo.

Parametri

Nome	In	Tipo	Descrizione
codiceModello*	query	string	Identificativo modello legacy.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/quattroruote/allestimenti?codiceModello=11" \
  -H "Authorization: Bearer <partner_token_o_ym_live>"

Partner — Veicoli

Gestione stock, annunci e foto del salone. Richiede API key con scope appropriati.

GEThttps://api.youmotor.com/api/v1/partner/meDealer API key

Verifica API key e autosalone

Restituisce i dati del dealer associato alla API key corrente e le informazioni sulla chiave stessa inclusi scope attivi. Usato per verificare autenticazione e permessi.

bash · cURL

curl https://api.youmotor.com/api/v1/partner/me \
  -H "Authorization: Bearer ym_live_xxx"

GEThttps://api.youmotor.com/api/v1/partner/vehiclesDealer API key

Lista veicoli del salone

Ritorna lo stock corrente del dealer con paginazione tramite limit e offset. Richiede scope vehicles:read. I campi veicolo sono in formato snake_case.

Parametri

Nome	In	Tipo	Descrizione
limit	query	integer	Max risultati. Default 100, max 200.
offset	query	integer	Risultati da saltare. Default 0.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/vehicles?limit=50&offset=0" \
  -H "Authorization: Bearer ym_live_xxx"

POSThttps://api.youmotor.com/api/v1/partner/vehiclesDealer API key

Crea pratica nuovo annuncio

Invia il payload annuncio completo. Crea una pratica in stato pending che YouMotor revisiona prima della pubblicazione. La risposta contiene l'UUID della submission (campo id). In caso di errore di validazione, la risposta include details.fieldErrors.

Il veicolo non viene pubblicato subito: resta in revisione fino all’approvazione da parte di YouMotor.
condition è obbligatorio: nuovo, km0 o usato.
youmotor_fee è legacy: se inviato viene accettato ma ignorato; YouMotor calcola la fee a scaglioni dal prezzo.
max_negotiation_price è legacy: se inviato viene accettato per compatibilità ma non viene più usato.
Almeno uno tra equipment, safety, comfort, infotainment deve essere valorizzato.
Se la stessa pratica (stesso payload) è già pending risponde 409 Conflict.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles \
  -H "Authorization: Bearer ym_live_xxx" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "Volkswagen Golf 8 Life 1.5 TSI",
    "make": "Volkswagen",
    "model": "Golf",
    "version": "1.5 TSI Life",
    "segment": "Berlina",
    "model_year": 2022,
    "first_registration": "2022-03-01",
    "price": 27500,
    "max_negotiation_price": 26000,
    "youmotor_fee": 300,
    "km": 18000,
    "mileage": 1498,
    "condition": "usato",
    "fuel_type": "Benzina",
    "transmission": "Manuale",
    "drivetrain": "Anteriore",
    "power_kw": 96,
    "power_hp": 131,
    "co2_emissions": 124,
    "fuel_consumption_combined": "5.4 l/100km",
    "plate": "EF456GH",
    "owners": 1,
    "warranty": "12 mesi concessionario",
    "service_history": "Tagliandi ufficiali completi",
    "availability": "Pronta consegna",
    "location": "Milano",
    "color": "Grigio Metallizzato",
    "interior": "Tessuto nero",
    "highlights": [
      "Unico proprietario",
      "Tagliandi ufficiali",
      "Pronta consegna"
    ],
    "description": "Auto in ottimo stato, pronta consegna con storico manutenzione completo.",
    "equipment": ["Cerchi in lega 17\"", "Fari full LED"],
    "comfort": ["Clima automatico bi-zona", "Sedili riscaldati"],
    "safety": ["Frenata autonoma di emergenza", "Mantenimento corsia"],
    "infotainment": ["App-Connect (Android Auto/CarPlay)"],
    "coverImage": "https://cdn.youmotor.com/img/EF456GH/cover.jpg",
    "gallery": [
      "https://cdn.youmotor.com/img/EF456GH/01.jpg",
      "https://cdn.youmotor.com/img/EF456GH/02.jpg"
    ]
  }'

GEThttps://api.youmotor.com/api/v1/partner/vehicles/:idDealer API key

Dettaglio veicolo

Ritorna il record completo del veicolo (snake_case) identificato dall'UUID. Richiede scope vehicles:read.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer ym_live_xxx"

PATCHhttps://api.youmotor.com/api/v1/partner/vehicles/:idDealer API key

Crea pratica aggiornamento annuncio

Invia un payload completo per aggiornare un annuncio esistente. Come per la creazione, genera una pratica pending che YouMotor deve approvare. L'annuncio corrente rimane pubblicato fino all'approvazione.

Richiede il payload completo, non solo i campi modificati.
L'annuncio pubblicato non cambia fino all'approvazione dell'update.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo da aggiornare.

bash · cURL

curl -X PATCH https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ym_live_xxx" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "Volkswagen Golf 8 Life 1.5 TSI — Prezzo ribassato",
    "make": "Volkswagen",
    "model": "Golf",
    "version": "1.5 TSI Life",
    "segment": "Berlina",
    "model_year": 2022,
    "first_registration": "2022-03-01",
    "price": 26900,
    "max_negotiation_price": 25500,
    "youmotor_fee": 300,
    "km": 18500,
    "mileage": 1498,
    "condition": "usato",
    "fuel_type": "Benzina",
    "transmission": "Manuale",
    "drivetrain": "Anteriore",
    "plate": "EF456GH",
    "owners": 1,
    "warranty": "12 mesi concessionario",
    "service_history": "Tagliandi ufficiali completi",
    "availability": "Pronta consegna",
    "location": "Milano",
    "color": "Grigio Metallizzato",
    "description": "Prezzo aggiornato. Auto in ottimo stato pronta consegna.",
    "equipment": ["Cerchi in lega 17\"", "Fari full LED"]
  }'

POSThttps://api.youmotor.com/api/v1/partner/vehicles/importDealer API key

Import bulk annunci

Invia fino a 1000 veicoli in una singola richiesta. Ogni elemento crea una pratica pending indipendente. La risposta riporta l'esito per ogni riga: gli errori di validazione per singola riga non bloccano le altre.

Massimo 1000 veicoli per chiamata.
Errori di singola riga non bloccano l'elaborazione delle altre.
Pratiche duplicate (stesso payload già pending) restituiscono ok: false con code DUPLICATE_SUBMISSION.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles/import \
  -H "Authorization: Bearer ym_live_xxx" \
  -H "Content-Type: application/json" \
  --data '{
    "vehicles": [
      {
        "title": "Fiat Panda 1.0 Hybrid",
        "make": "Fiat",
        "model": "Panda",
        "version": "1.0 Hybrid",
        "segment": "City Car",
        "model_year": 2023,
        "first_registration": "2023-05-01",
        "price": 13900,
        "max_negotiation_price": 13000,
        "youmotor_fee": 300,
        "km": 9500,
        "mileage": 999,
        "condition": "usato",
        "fuel_type": "Ibrida",
        "transmission": "Manuale",
        "drivetrain": "Anteriore",
        "plate": "GH123JK",
        "owners": 1,
        "warranty": "12 mesi concessionario",
        "service_history": "Tagliandi regolari documentati",
        "availability": "Pronta consegna",
        "location": "Torino",
        "color": "Bianco",
        "description": "City car ibrida efficiente, pronta consegna.",
        "equipment": ["Cerchi in lega 15\""]
      },
      {
        "title": "Fiat Panda 1.0 Hybrid",
        "make": "Fiat",
        "model": "Panda",
        "version": "1.0 Hybrid",
        "segment": "City Car",
        "model_year": 2023,
        "first_registration": "2023-05-01",
        "price": 13900,
        "km": 9500,
        "mileage": 999,
        "condition": "usato",
        "fuel_type": "Ibrida",
        "transmission": "Manuale",
        "drivetrain": "Anteriore",
        "plate": "GH123JK",
        "owners": 1,
        "warranty": "12 mesi concessionario",
        "service_history": "Tagliandi regolari documentati",
        "availability": "Pronta consegna",
        "location": "Torino",
        "color": "Bianco",
        "description": "Stessa targa e payload già inviati in precedenza: verrà rifiutata come duplicato.",
        "equipment": ["Cerchi in lega 15\""]
      }
    ]
  }'

POSThttps://api.youmotor.com/api/v1/partner/vehicles/:plate/photosDealer API key

Upload foto veicolo

Carica fino a 40 immagini via multipart/form-data (campo images). Gli URL in uploaded[].url vanno nel payload annuncio (coverImage, gallery/images). Richiede scope media:write.

Massimo 40 immagini per upload, 160 MB complessivi.
Formati accettati: JPEG, PNG, WebP.
Gli URL restituiti in uploaded[].url puntano al CDN pubblico (formato WebP).

Parametri

Nome	In	Tipo	Descrizione
plate*	path	string	Targa del veicolo (5-10 caratteri A-Z0-9).
kind	query	string	Passa kind=cover per impostare la prima immagine come cover.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles/EF456GH/photos \
  -H "Authorization: Bearer ym_live_xxx" \
  -F "images=@frontale.jpg" \
  -F "images=@interni.jpg" \
  -F "images=@laterale.jpg"

POSThttps://api.youmotor.com/api/v1/partner/vehicles/:id/soldDealer API key

Segna veicolo come venduto

Imposta sold=true sul veicolo con data, prezzo e note opzionali. Prezzo non negativo con massimo 2 decimali; note max 2.000 caratteri. Richiede scope stock-status:write.

La risposta include youmotorFee: la fee YouMotor applicata alla vendita, calcolata a scaglioni sul prezzo (di listino o, se più alto, sul prezzo effettivo indicato qui).

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo.
price	body	number	Prezzo effettivo opzionale, ≥ 0 e max 2 decimali.
notes	body	string	Note opzionali, max 2.000 caratteri.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sold \
  -H "Authorization: Bearer ym_live_xxx" \
  -H "Content-Type: application/json" \
  --data '{
    "price": 26500,
    "notes": "Venduta tramite portale partner"
  }'

DELETEhttps://api.youmotor.com/api/v1/partner/vehicles/:id/soldDealer API key

Annulla stato venduto

Ripristina un veicolo precedentemente segnato come venduto (sold=false). Richiede scope stock-status:write.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo.

bash · cURL

curl -X DELETE https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sold \
  -H "Authorization: Bearer ym_live_xxx"

POSThttps://api.youmotor.com/api/v1/partner/vehicles/:id/archiveDealer API key

Archivia veicolo

Archivia un veicolo active. È idempotente; gli stati diversi da active/archived restituiscono 409. Richiede scope stock-status:write.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive \
  -H "Authorization: Bearer ym_live_xxx"

POSThttps://api.youmotor.com/api/v1/partner/vehicles/:id/unarchiveDealer API key

Ripristina veicolo archiviato

Riattiva esclusivamente un veicolo archived. Un veicolo blocked resta bloccato e restituisce 409. Richiede scope stock-status:write.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID del veicolo.

bash · cURL

curl -X POST https://api.youmotor.com/api/v1/partner/vehicles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unarchive \
  -H "Authorization: Bearer ym_live_xxx"

Partner — Pratiche

Monitoraggio pratiche di pubblicazione. Eventuali richieste di correzione compaiono su latest_notify_note.

GEThttps://api.youmotor.com/api/v1/partner/submissionsDealer API key

Lista pratiche dealer

Ritorna tutte le pratiche (creazioni e update) del salone. Campi in snake_case; latest_notify_note contiene l'ultima richiesta di correzione da YouMotor. Richiede scope submissions:read.

bash · cURL

curl https://api.youmotor.com/api/v1/partner/submissions \
  -H "Authorization: Bearer ym_live_xxx"

GEThttps://api.youmotor.com/api/v1/partner/submissions/:idDealer API key

Dettaglio pratica

Ritorna il dettaglio completo di una pratica, incluso il payload del veicolo e la cronologia delle note di notifica.

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID della pratica.

bash · cURL

curl "https://api.youmotor.com/api/v1/partner/submissions/c7a1e9f4-2b3d-4c5e-8f6a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer ym_live_xxx"

PATCHhttps://api.youmotor.com/api/v1/partner/submissions/:idDealer API key

Aggiorna payload pratica pending

Aggiorna il payload di una pratica in stato pending. Dopo l'aggiornamento la pratica resta pending per nuova revisione.

Funziona solo su pratiche in stato pending.
Richiede scope vehicles:write (non submissions:read).

Parametri

Nome	In	Tipo	Descrizione
id*	path	uuid	UUID della pratica da aggiornare.

bash · cURL

curl -X PATCH https://api.youmotor.com/api/v1/partner/submissions/c7a1e9f4-2b3d-4c5e-8f6a-1b2c3d4e5f6a \
  -H "Authorization: Bearer ym_live_xxx" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "Volkswagen Golf 8 Life 1.5 TSI — Prezzo corretto",
    "make": "Volkswagen",
    "model": "Golf",
    "version": "1.5 TSI Life",
    "segment": "Berlina",
    "model_year": 2022,
    "first_registration": "2022-03-01",
    "price": 25900,
    "max_negotiation_price": 24500,
    "youmotor_fee": 300,
    "km": 18000,
    "mileage": 1498,
    "condition": "usato",
    "fuel_type": "Benzina",
    "transmission": "Manuale",
    "drivetrain": "Anteriore",
    "plate": "EF456GH",
    "owners": 1,
    "warranty": "12 mesi concessionario",
    "service_history": "Tagliandi ufficiali completi",
    "availability": "Pronta consegna",
    "location": "Milano",
    "color": "Grigio Metallizzato",
    "description": "Prezzo corretto come richiesto. Auto in ottimo stato.",
    "equipment": ["Cerchi in lega 17\""]
  }'

Schema veicolo

Payload completo richiesto da POST /partner/vehicles, PATCH /partner/vehicles/:id e POST /partner/vehicles/import: il formato canonico è snake_case, come negli esempi e nell'OpenAPI. Alcuni alias camelCase restano accettati solo per compatibilità. Anche le risposte di lista/dettaglio veicolo e pratiche usano snake_case. I campi con asterisco * sono obbligatori.certified non è impostabile tramite questa API; contattare il supporto YouMotor se necessario.

Campo	Tipo	Obbl.	Descrizione
title*	string	Si	Titolo annuncio (2-200 caratteri).
make*	string	Si	Marca: usare la description da GET /partner/vehicle-catalog/makes (catalogo ufficiale YouMotor).
model*	string	Si	Modello: usare la description da GET /partner/vehicle-catalog/models?makeId=...
version*	string	Si	Versione/allestimento commerciale in testo libero (max 200 caratteri). Non esiste un catalogo select ufficiale.
segment*	string	Si	Segmento da vehicle-options group=segment.
body_type	string?	No	Carrozzeria da vehicle-options group=body_type (max 80 caratteri). Se omesso viene derivato dal segmento.
model_year*	integer	Si	Anno modello: da 1886 all'anno corrente + 1.
first_registration*	date	Si	Prima immatricolazione reale, formato YYYY-MM-DD; deve essere una data calendario valida.
price*	number	Si	Prezzo pubblico: 0-9.999.999.999,99 €, massimo 2 decimali.
max_negotiation_price	number	No	Legacy: accettato per compatibilità, non più usato.
youmotor_fee	number	No	Legacy: accettato ma ignorato; fee automatica: 160/290/390/450€ in base al prezzo.
km*	integer	Si	Chilometraggio odometro: 0-2.147.483.647, senza decimali.
mileage*	integer	Si	Cilindrata in cc: 0-2.147.483.647, senza decimali.
condition*	enum	Si	Condizione: nuovo, km0 o usato (obbligatorio per le API partner).
emission_class	enum?	No	Classe ambientale canonica da vehicle-options group=emission_class; non dedurla dall'anno.
fuel_type*	string	Si	Alimentazione da vehicle-options group=fuel_type.
transmission*	enum	Si	Cambio: Manuale, Automatico o Semiautomatico (da vehicle-options group=transmission).
drivetrain*	string	Si	Trazione da vehicle-options group=drivetrain.
power_kw	integer?	No	Potenza in kW (0-2000).
power_hp	integer?	No	Potenza in CV (0-2000).
co2_emissions	integer?	No	Emissioni CO₂ in g/km (0-1500).
fuel_consumption_combined	string?	No	Consumo 0-999,99, massimo 2 decimali; es. "5.4 l/100km".
plate*	string	Si	Targa normalizzata, pattern [A-Z0-9]{5,10}.
vin	string?	No	Numero telaio VIN: 17 caratteri alfanumerici, standard ISO 3779 (esclude le lettere I, O, Q).
owners*	integer	Si	Proprietari precedenti: da 0 a 4.
warranty*	string	Si	Garanzia da vehicle-options o testo libero.
service_history*	string	Si	Cronologia tagliandi da vehicle-options o testo libero.
availability*	string	Si	Disponibilità da vehicle-options.
province*	string	Si	Provincia canonica da vehicle-options group=province. La risposta include region derivata.
location	string	No	Alias legacy di province, mantenuto per compatibilità.
color*	string	Si	Colore esterno da vehicle-options group=color.
interior	string?	No	Colore o materiale interno.
highlights*	string[]	Si	Da 3 a 6 punti di forza (max 300 caratteri ciascuno).
description*	string	Si	Descrizione pubblica (1-5000 caratteri).
equipment	string[]	No	Dotazioni generali, max 200 elementi (300 caratteri ciascuno). Almeno una lista tra equipment, safety, comfort, infotainment deve essere valorizzata.
safety	string[]	No	Dotazioni sicurezza, max 200 elementi (300 caratteri ciascuno).
comfort	string[]	No	Dotazioni comfort, max 200 elementi (300 caratteri ciascuno).
infotainment	string[]	No	Dotazioni infotainment, max 200 elementi (300 caratteri ciascuno).
share_active	boolean	No	Se true, richiede anche la condivisione nel catalogo B2B YouMotor Share.
share_price	number?	No	Obbligatorio quando share_active=true: maggiore di 0 e inferiore a price.
coverImage	string?	No	URL immagine di copertina, HTTP/HTTPS senza credenziali incorporate, max 2048 caratteri (dall'upload foto).
gallery	string[]	No	URL immagini galleria (max 40, stesse regole di coverImage; dall'upload foto).
images	string[]	No	URL immagini aggiuntive (max 40, stesse regole di coverImage).

Codici di errore

Tutti gli errori sono JSON con i campi code ed error. Le risposte di validazione includono anche details.fieldErrors; gli errori temporanei indicano retryable: true e vanno ritentati con backoff.

json · esempio errore validazione

{
  "code": "VALIDATION_ERROR",
  "error": "Dati veicolo non validi",
  "details": {
    "fieldErrors": {
      "price": ["Campo obbligatorio"],
      "plate": ["Targa non valida"]
    }
  }
}

Limiti di frequenza (rate limiting)

Limite globale: 100 richieste ogni 15 minuti per indirizzo IP su tutte le rotte /api/v1. Le rotte di provisioning hanno limiti dedicati più stringenti (vedi note sui singoli endpoint). Ogni risposta include gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; al superamento del limite la risposta è 429 con header Retry-After (secondi di attesa consigliati).

Codice	Status	Causa
400	Bad Request	Payload non valido (validazione fallita). La risposta include details.fieldErrors con i campi problematici.
401	Unauthorized	Autenticazione mancante o API key non valida.
403	Forbidden	Scope insufficiente per l'operazione richiesta (code: missing_scope).
404	Not Found	Risorsa non trovata (veicolo, pratica o autosalone inesistente).
409	Conflict	Risorsa duplicata (es. pratica identica già in pending, o veicolo in stato non compatibile).
413	Payload Too Large	Upload foto oltre i limiti: più di 40 immagini o oltre 160 MB complessivi.
429	Too Many Requests	Rate limit superato. Riprovare dopo il periodo indicato nell'header Retry-After (retryable: true).
500	Server Error	Errore interno. Contattare il supporto YouMotor se persiste.
502	Bad Gateway	Catalogo veicoli temporaneamente non disponibile (code: VEHICLE_CATALOG_UNAVAILABLE, retryable: true).

Torna al sito

API YouMotor

API key dealer

Scope granulari

Pratiche pending

Media multipart

Flusso consigliato

Autenticazione

Flusso integrazione (end-to-end)

Fase A — Credenziali e accesso

Fase B — Catalogo e payload

Partner provisioning

Lista autosaloni del partner

Crea autosalone da partner autorizzato

Partner — Catalogo

Come si compila un annuncio

Marca e modello

Campi a scelta obbligata

Campi liberi

Elenco marche

Elenco modelli di una marca

Opzioni a scelta obbligata dell'annuncio

Marche legacy — deprecato

Modelli legacy — deprecato

Allestimenti legacy — deprecato

Partner — Veicoli

Verifica API key e autosalone

Lista veicoli del salone

Crea pratica nuovo annuncio

Dettaglio veicolo

Crea pratica aggiornamento annuncio

Import bulk annunci

Upload foto veicolo

Segna veicolo come venduto

Annulla stato venduto

Archivia veicolo

Ripristina veicolo archiviato

Partner — Pratiche

Lista pratiche dealer

Dettaglio pratica

Aggiorna payload pratica pending

Schema veicolo

Codici di errore