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. images è l'elenco completo degli URL; coverImage è la copertina, uno di quegli URL.
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). sendWelcomeEmail: false non invia la mail di benvenuto.
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). Mettete gli URL di uploaded[].url nel campo images e scegliete la copertina con coverImage.
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

Conservate ym_partner_... e ym_live_... solo su server vostri, sempre via HTTPS, mai in app, siti pubblici o log. La chiave opera solo sullo stock di quel salone: un id di un altro dealer risponde 404. share_price resta un prezzo B2B e non va pubblicato nell'annuncio verso il cliente finale. Un veicolo blocked non si riattiva con unarchive. In caso di dubbio revocate la chiave con YouMotor.

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.

GET/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>"

200Risposta

json

{
  "items": [
    {
      "id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
      "email": "dealer@autorossi.it",
      "displayName": "Auto Rossi",
      "legalName": "Auto Rossi Srl",
      "phone": "+390212345678",
      "vatNumber": "12345678901",
      "taxCode": null,
      "notes": null,
      "status": "active",
      "createdAt": "2026-01-10T08:00:00.000Z",
      "lastLoginAt": null,
      "totalVehicles": 12,
      "activeVehicles": 10,
      "blockedVehicles": 0,
      "pendingPratiche": 1,
      "externalAccount": {
        "provider": "partner-name",
        "customerReference": "customer-123"
      }
    }
  ]
}

POST/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.
sendWelcomeEmail è opzionale e vale true se omesso. Con false non parte la mail di benvenuto (né link password né chiave).
externalAccount.customerReference collega il dealer al CRM del partner.
Rate limit dedicato: 150 creazioni 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,
    "sendWelcomeEmail": false,
    "apiKeyLabel": "multicaricatore",
    "externalAccount": {
      "provider": "partner-name",
      "customerReference": "customer-123"
    }
  }'

201Risposta

json

{
  "dealer": {
    "id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
    "email": "dealer@autorossi.it",
    "displayName": "Auto Rossi",
    "legalName": "Auto Rossi Srl",
    "phone": "+390212345678",
    "vatNumber": "12345678901",
    "taxCode": null,
    "notes": null,
    "status": "active",
    "createdAt": "2026-01-10T08:00:00.000Z",
    "lastLoginAt": null,
    "totalVehicles": 0,
    "activeVehicles": 0,
    "blockedVehicles": 0,
    "pendingPratiche": 0
  },
  "dealerApiKey": "ym_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4",
  "apiKey": {
    "id": "f0f86ad3-2046-467e-b9d8-1713f4af169c",
    "dealerId": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
    "keyPrefix": "ym_live_a1b2c3d4",
    "label": "multicaricatore",
    "scopes": [
      "vehicles:read",
      "vehicles:write",
      "media:write",
      "submissions:read",
      "stock-status:write"
    ],
    "status": "active",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null,
    "revokedReason": null,
    "metadata": {}
  },
  "apiKeyDeliveredByEmail": false
}

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
coverImage · images	Upload foto	coverImage è la copertina; images è l'elenco completo, copertina inclusa
title · description · highlights	Testo libero	Testi commerciali dell'annuncio
price · share_price · youmotor_fee · km · mileage	Testo libero	Prezzo pubblico, prezzo al rivenditore e gettone visibilità (0 € o multipli di 50 €, default 300 €)
model_year · first_registration · plate	Testo libero	Dati del veicolo dal vostro gestionale

GET/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>"

200Risposta

json

{
  "items": [
    { "code": "9",  "description": "BMW" },
    { "code": "8",  "description": "FIAT" },
    { "code": "74", "description": "VOLKSWAGEN" }
  ]
}

GET/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>"

200Risposta

json

{
  "items": [
    { "code": "7",  "description": "Serie 1" },
    { "code": "11", "description": "Serie 3" },
    { "code": "26", "description": "X3" }
  ]
}

GET/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: Pronta consegna · In trattativa · Su ordinazione · Disponibile a breve

warrantyGaranzia→warrantystring

Valori value: Nessuna · 6 mesi autosalone · 12 mesi legale conformita · 12 mesi autosalone · 12 mesi estensione premium · 24 mesi autosalone · 24 mesi estensione premium · 36 mesi autosalone · 48 mesi autosalone · 60 mesi autosalone · 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>"

200Risposta

json

{
  "groups": [
    {
      "key": "fuel_type",
      "label": "Alimentazione",
      "options": [
        { "key": "fuel_type_a1b2c3d4e5f6", "label": "Benzina", "value": "Benzina", "position": 1, "metadata": {} },
        { "key": "fuel_type_f6e5d4c3b2a1", "label": "Diesel", "value": "Diesel", "position": 2, "metadata": {} },
        { "key": "fuel_type_0123456789ab", "label": "Ibrida", "value": "Ibrida", "position": 3, "metadata": {} },
        { "key": "fuel_type_cdef01234567", "label": "Ibrida Plug-in", "value": "Ibrida Plug-in", "position": 4, "metadata": {} },
        { "key": "fuel_type_89abcdef0123", "label": "Elettrica", "value": "Elettrica", "position": 5, "metadata": {} }
      ]
    },
    {
      "key": "equipment",
      "label": "Equipaggiamento",
      "options": [
        { "key": "equipment_abc123def456", "label": "Cerchi in lega", "value": "Cerchi in lega", "position": 1, "metadata": {} },
        { "key": "equipment_def456abc123", "label": "Fari full-LED", "value": "Fari full-LED", "position": 11, "metadata": {} }
      ]
    }
  ]
}

GET/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>"

GET/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>"

GET/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. Crea, update e bulk usano lo stesso annuncio. Richiede API key con scope appropriati.

Foto: copertina ed elenco

Caricate i file, prendete gli URL e metteteli tutti in images.coverImageindica quale di quelle foto è la copertina.

Minimo 3 · massimo 40

coverImage

Un solo URL, già presente in images. Se manca, la copertina è la prima foto.

Foto 1

Copertina

https://cdn.youmotor.com/foto1.webp

images

Tutte le foto, copertina inclusa, nell'ordine di visualizzazione.

1Frontalefoto1.webpCopertina
2Lateralefoto2.webp
3Internifoto3.webp

In lettura: gli stessi URL in images, la copertina in cover_image.

GET/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"

200Risposta

json

{
  "dealer": {
    "id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
    "email": "dealer-partner-test@example.com",
    "displayName": "Autosalone Demo",
    "legalName": "Autosalone Demo Srl",
    "phone": "+390212345678",
    "vatNumber": "12345678901",
    "taxCode": null,
    "notes": null,
    "status": "active",
    "createdAt": "2026-05-27T07:18:38.974Z",
    "lastLoginAt": null,
    "totalVehicles": 0,
    "activeVehicles": 0,
    "blockedVehicles": 0,
    "pendingPratiche": 0
  },
  "apiKey": {
    "id": "f0f86ad3-2046-467e-b9d8-1713f4af169c",
    "keyPrefix": "ym_live_8VZHv6PMJ3",
    "scopes": [
      "vehicles:read",
      "vehicles:write",
      "media:write",
      "submissions:read",
      "stock-status:write"
    ]
  }
}

GET/partner/vehiclesDealer API key

Lista veicoli del salone

Ritorna solo lo stock del salone della API key, in snake_case, con youmotor_fee, share_price, share_active e sold_notes. Gli importi sono numeri. Non include note interne, featured o metadata.

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"

200Risposta

json

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dealer_id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
      "title": "Volkswagen Golf 8 Life 1.5 TSI",
      "make": "Volkswagen",
      "model": "Golf",
      "version": "1.5 TSI Life",
      "segment": "Berlina",
      "body_type": "Berlina",
      "condition": "usato",
      "model_year": 2022,
      "first_registration": "2022-04-12",
      "price": 27500,
      "youmotor_fee": 300,
      "share_active": true,
      "share_price": 24500,
      "km": 18000,
      "mileage": 1498,
      "fuel_type": "Benzina",
      "transmission": "Manuale",
      "drivetrain": "Anteriore",
      "color": "Grigio Metallizzato",
      "owners": 1,
      "plate": "EF456GH",
      "status": "active",
      "sold": false,
      "sold_price": null,
      "sold_notes": null,
      "cover_image": "https://cdn.youmotor.com/vehicles/…/cover.webp",
      "region": "Lombardia",
      "created_at": "2026-03-01T12:00:00.000Z",
      "updated_at": "2026-03-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}

POST/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 è il gettone visibilità: default 300 €, minimo 0 €, modificabile a passi di 50 €. Un valore maggiore aumenta la priorità dell’annuncio.
share_price è il Prezzo al rivenditore: è sempre valorizzato, non può superare il prezzo pubblico e, se omesso, viene impostato automaticamente al prezzo pubblico meno 90 euro. È visibile solo ad agenzie e autosaloni autorizzati, mai al cliente finale.
max_negotiation_price è legacy: se inviato viene accettato per compatibilità ma non viene più usato.
make e model sono la description di /partner/vehicle-catalog/makes e /models. Gli extra e i campi a scelta sono option.value di /partner/vehicle-options. Un valore fuori catalogo risponde 400 e indica l'endpoint.
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",
  "body_type": "Berlina",
  "condition": "usato",
  "emission_class": "Euro 6d",
  "model_year": 2022,
  "first_registration": "2022-03-01",
  "price": 27500,
  "share_price": 24500,
  "share_active": false,
  "youmotor_fee": 300,
  "km": 18000,
  "mileage": 1498,
  "fuel_type": "Benzina",
  "transmission": "Manuale",
  "drivetrain": "Anteriore",
  "power_kw": 96,
  "power_hp": 131,
  "neopatentato": true,
  "co2_emissions": 124,
  "fuel_consumption_combined": "5.4 l/100km",
  "plate": "EF456GH",
  "vin": "WVWZZZAUZKW123456",
  "owners": 1,
  "warranty": "12 mesi autosalone",
  "service_history": "Tagliandi ufficiali completi",
  "availability": "Pronta consegna",
  "province": "Milano",
  "color": "Grigio Metallizzato",
  "interior": "Tessuto nero",
  "description": "Unico proprietario, tagliandi ufficiali.",
  "highlights": [
    "Unico proprietario",
    "Tagliandi ufficiali",
    "Pronta consegna"
  ],
  "equipment": [
    "Cerchi in lega",
    "Fari LED"
  ],
  "safety": [
    "Frenata d'emergenza assistita"
  ],
  "comfort": [
    "Climatizzatore automatico, 2 zone"
  ],
  "infotainment": [
    "Apple CarPlay"
  ],
  "coverImage": "https://cdn.youmotor.com/foto1.webp",
  "images": [
    "https://cdn.youmotor.com/foto1.webp",
    "https://cdn.youmotor.com/foto2.webp",
    "https://cdn.youmotor.com/foto3.webp"
  ]
}'

201Risposta

json

{
  "id": "c7a1e9f4-2b3d-4c5e-8f6a-1b2c3d4e5f6a",
  "status": "pending",
  "createdAt": "2026-05-18T14:30:00.000Z"
}

GET/partner/vehicles/:idDealer API key

Dettaglio veicolo

Ritorna il veicolo del salone della API key, in snake_case. Include youmotor_fee, share_price, share_active e sold_notes. Un UUID di un altro salone risponde 404. Non include note interne, featured, metadata o prezzi offerta.

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"

200Risposta

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dealer_id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
  "title": "Volkswagen Golf 8 Life 1.5 TSI",
  "make": "Volkswagen",
  "model": "Golf",
  "version": "1.5 TSI Life",
  "segment": "Berlina",
  "body_type": "Berlina",
  "condition": "usato",
  "model_year": 2022,
  "first_registration": "2022-04-12",
  "price": 27500,
  "youmotor_fee": 300,
  "share_active": true,
  "share_price": 24500,
  "max_negotiation_price": null,
  "km": 18000,
  "mileage": 1498,
  "fuel_type": "Benzina",
  "transmission": "Manuale",
  "drivetrain": "Anteriore",
  "power_kw": 110,
  "power_hp": 150,
  "co2_emissions": 128,
  "fuel_consumption_combined": 5.4,
  "color": "Grigio Metallizzato",
  "interior": "Tessuto nero",
  "owners": 1,
  "warranty": "24 mesi autosalone",
  "service_history": "Tagliandi ufficiali completi",
  "availability": "Pronta consegna",
  "province": "Milano",
  "location": "Milano",
  "region": "Lombardia",
  "certified": false,
  "plate": "EF456GH",
  "vin": "WVWZZZAUZKW123456",
  "status": "active",
  "blocked_reason": null,
  "cover_image": "https://cdn.youmotor.com/vehicles/…/cover.webp",
  "images": [],
  "sold": false,
  "sold_price": null,
  "sold_notes": null,
  "created_at": "2026-03-01T12:00:00.000Z",
  "updated_at": "2026-03-01T12:00:00.000Z"
}

PATCH/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: copertina e almeno 3 foto. I punti di forza sono facoltativi; se presenti, da 3 a 6.
share_active true accende YouMotor Share solo con prezzo al rivenditore valido; false lo spegne; se ometti il campo lo stato Share resta quello già pubblicato.
certified e featured non fanno parte del payload di scrittura.
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",
  "body_type": "Berlina",
  "condition": "usato",
  "emission_class": "Euro 6d",
  "model_year": 2022,
  "first_registration": "2022-03-01",
  "price": 26900,
  "share_price": 23900,
  "share_active": false,
  "youmotor_fee": 300,
  "km": 18500,
  "mileage": 1498,
  "fuel_type": "Benzina",
  "transmission": "Manuale",
  "drivetrain": "Anteriore",
  "power_kw": 96,
  "power_hp": 131,
  "neopatentato": true,
  "co2_emissions": 124,
  "fuel_consumption_combined": "5.4 l/100km",
  "plate": "EF456GH",
  "vin": "WVWZZZAUZKW123456",
  "owners": 1,
  "warranty": "12 mesi autosalone",
  "service_history": "Tagliandi ufficiali completi",
  "availability": "Pronta consegna",
  "province": "Milano",
  "color": "Grigio Metallizzato",
  "interior": "Tessuto nero",
  "description": "Unico proprietario, tagliandi ufficiali.",
  "highlights": [
    "Unico proprietario",
    "Tagliandi ufficiali",
    "Pronta consegna"
  ],
  "equipment": [
    "Cerchi in lega",
    "Fari LED"
  ],
  "safety": [
    "Frenata d'emergenza assistita"
  ],
  "comfort": [
    "Climatizzatore automatico, 2 zone"
  ],
  "infotainment": [
    "Apple CarPlay"
  ],
  "coverImage": "https://cdn.youmotor.com/foto1.webp",
  "images": [
    "https://cdn.youmotor.com/foto1.webp",
    "https://cdn.youmotor.com/foto2.webp",
    "https://cdn.youmotor.com/foto3.webp"
  ]
}'

201Risposta

json

{
  "id": "d8b2fa05-3c4e-4d6f-9a7b-2c3d4e5f6a7b",
  "status": "pending",
  "createdAt": "2026-05-18T15:00:00.000Z"
}

POST/partner/vehicles/importDealer API key

Import bulk annunci

Invia fino a 1000 annunci completi, lo stesso payload di POST /partner/vehicles. Prima leggete marche, modelli e opzioni: make, model ed extra fuori catalogo vengono rifiutati sulla singola riga, con l'endpoint da richiamare. Gli altri veicoli del lotto proseguono.

Massimo 1000 veicoli per chiamata. Ogni elemento è il JSON di POST /partner/vehicles, campi inclusi: carrozzeria, classe ambientale, kW/CV, neopatentato, CO2, consumi, VIN, interni, provincia, Share, gettone, foto e le quattro liste extra.
make = description di GET /partner/vehicle-catalog/makes. model = description di GET /partner/vehicle-catalog/models?makeId=... (il code della marca).
equipment, safety, comfort e infotainment vanno copiati identici a option.value di GET /partner/vehicle-options (maiuscole comprese) e messi nel gruppo giusto. «cerchi in lega» o «Fari full LED» sono rifiutati.
Errori di singola riga non bloccano le altre. Un valore fuori catalogo risponde ok: false, code VALIDATION_ERROR, details.fieldErrors con l'API da usare.
Se lo stesso payload è già in stato pending, quella riga risponde ok: false con code DUPLICATE_SUBMISSION.
Foto: coverImage è la copertina e images è l'elenco completo, copertina inclusa. Almeno 3 URL unici. I punti di forza, se presenti, sono da 3 a 6.

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": "Volkswagen Golf 8 Life 1.5 TSI",
      "make": "Volkswagen",
      "model": "Golf",
      "version": "1.5 TSI Life",
      "segment": "Berlina",
      "body_type": "Berlina",
      "condition": "usato",
      "emission_class": "Euro 6d",
      "model_year": 2022,
      "first_registration": "2022-03-01",
      "price": 27500,
      "share_price": 24500,
      "share_active": false,
      "youmotor_fee": 300,
      "km": 18000,
      "mileage": 1498,
      "fuel_type": "Benzina",
      "transmission": "Manuale",
      "drivetrain": "Anteriore",
      "power_kw": 96,
      "power_hp": 131,
      "neopatentato": true,
      "co2_emissions": 124,
      "fuel_consumption_combined": "5.4 l/100km",
      "plate": "EF456GH",
      "vin": "WVWZZZAUZKW123456",
      "owners": 1,
      "warranty": "12 mesi autosalone",
      "service_history": "Tagliandi ufficiali completi",
      "availability": "Pronta consegna",
      "province": "Milano",
      "color": "Grigio Metallizzato",
      "interior": "Tessuto nero",
      "description": "Unico proprietario, tagliandi ufficiali.",
      "highlights": [
        "Unico proprietario",
        "Tagliandi ufficiali",
        "Pronta consegna"
      ],
      "equipment": [
        "Cerchi in lega",
        "Fari LED"
      ],
      "safety": [
        "Frenata d'emergenza assistita"
      ],
      "comfort": [
        "Climatizzatore automatico, 2 zone"
      ],
      "infotainment": [
        "Apple CarPlay"
      ],
      "coverImage": "https://cdn.youmotor.com/foto1.webp",
      "images": [
        "https://cdn.youmotor.com/foto1.webp",
        "https://cdn.youmotor.com/foto2.webp",
        "https://cdn.youmotor.com/foto3.webp"
      ]
    },
    {
      "title": "Volkswagen Golf 8 Life 1.5 TSI",
      "make": "Volkswagen",
      "model": "Golf",
      "version": "1.5 TSI Life",
      "segment": "Berlina",
      "body_type": "Berlina",
      "condition": "usato",
      "emission_class": "Euro 6d",
      "model_year": 2022,
      "first_registration": "2022-03-01",
      "price": 27500,
      "share_price": 24500,
      "share_active": false,
      "youmotor_fee": 300,
      "km": 18000,
      "mileage": 1498,
      "fuel_type": "Benzina",
      "transmission": "Manuale",
      "drivetrain": "Anteriore",
      "power_kw": 96,
      "power_hp": 131,
      "neopatentato": true,
      "co2_emissions": 124,
      "fuel_consumption_combined": "5.4 l/100km",
      "plate": "EF456GH",
      "vin": "WVWZZZAUZKW123456",
      "owners": 1,
      "warranty": "12 mesi autosalone",
      "service_history": "Tagliandi ufficiali completi",
      "availability": "Pronta consegna",
      "province": "Milano",
      "color": "Grigio Metallizzato",
      "interior": "Tessuto nero",
      "description": "Unico proprietario, tagliandi ufficiali.",
      "highlights": [
        "Unico proprietario",
        "Tagliandi ufficiali",
        "Pronta consegna"
      ],
      "equipment": [
        "Cerchi in lega",
        "Fari LED"
      ],
      "safety": [
        "Frenata d'emergenza assistita"
      ],
      "comfort": [
        "Climatizzatore automatico, 2 zone"
      ],
      "infotainment": [
        "Apple CarPlay"
      ],
      "coverImage": "https://cdn.youmotor.com/foto1.webp",
      "images": [
        "https://cdn.youmotor.com/foto1.webp",
        "https://cdn.youmotor.com/foto2.webp",
        "https://cdn.youmotor.com/foto3.webp"
      ]
    }
  ]
}'

200Risposta

json

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "id": "e9c3ab16-4d5f-4e70-8b8c-3d4e5f6a7b8c",
      "status": "pending",
      "createdAt": "2026-05-18T14:30:00.000Z"
    },
    {
      "index": 1,
      "ok": false,
      "code": "DUPLICATE_SUBMISSION",
      "error": "Pratica già presente e in attesa di revisione",
      "retryable": false
    }
  ]
}

POST/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 in images; uno di quelli, di solito il primo, va anche in coverImage. 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"

201Risposta

json

{
  "prefix": "vehicles/pub/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "uploaded": [
    {
      "key": "vehicles/pub/…/20260518-143000-a1b2c3.webp",
      "url": "https://cdn.youmotor.com/vehicles/pub/…/20260518-143000-a1b2c3.webp",
      "contentType": "image/webp",
      "size": 245760,
      "catalogUrl": "https://cdn.youmotor.com/vehicles/pub/…/20260518-143000-a1b2c3-catalog.webp",
      "studioUrl": "https://cdn.youmotor.com/vehicles/pub/…/20260518-143000-a1b2c3-studio.webp"
    }
  ]
}

POST/partner/vehicles/:id/soldDealer API key

Segna veicolo come venduto

Imposta sold=true. sold_channel è obbligatorio: youmotor, oppure other con sold_platform. Prezzo e note restano opzionali. Richiede scope stock-status:write.

La risposta include youmotor_fee: il gettone già salvato sull’annuncio. Registrare la vendita non lo modifica.

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.
sold_channel*	body	enum	youmotor oppure other.
sold_platform	body	string	Obbligatorio se sold_channel è other. Max 80 caratteri. Non indicarlo per YouMotor.

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 su AutoScout24",
    "sold_channel": "other",
    "sold_platform": "AutoScout24"
  }'

200Risposta

json

{
  "ok": true,
  "youmotor_fee": 300,
  "sold_channel": "other",
  "sold_platform": "AutoScout24"
}

DELETE/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"

200Risposta

json

{
  "ok": true
}

POST/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"

200Risposta

json

{
  "ok": true
}

POST/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"

200Risposta

json

{
  "ok": true
}

Partner — Pratiche

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

GET/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"

200Risposta

json

{
  "items": [
    {
      "id": "c7a1e9f4-2b3d-4c5e-8f6a-1b2c3d4e5f6a",
      "dealer_id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
      "target_vehicle_id": null,
      "operation": "create",
      "status": "pending",
      "payload": { "plate": "EF456GH", "title": "Volkswagen Golf 8 Life 1.5 TSI", "price": 27500 },
      "rejection_reason": null,
      "reviewed_at": null,
      "latest_notify_note": null,
      "latest_notify_at": null,
      "created_at": "2026-05-18T14:30:00.000Z",
      "updated_at": "2026-05-18T14:30:00.000Z"
    },
    {
      "id": "a1f2e3d4-5b6c-4d7e-8f90-1a2b3c4d5e6f",
      "dealer_id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
      "target_vehicle_id": null,
      "operation": "create",
      "status": "needs_review",
      "payload": { "plate": "MN789OP", "title": "Fiat Panda 1.0 Hybrid", "price": 13900 },
      "latest_notify_note": "Prezzo fuori mercato per questo segmento. Verificare e aggiornare.",
      "latest_notify_at": "2026-05-15T11:00:00.000Z",
      "created_at": "2026-05-10T09:00:00.000Z",
      "updated_at": "2026-05-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0
  }
}

GET/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"

200Risposta

json

{
  "id": "c7a1e9f4-2b3d-4c5e-8f6a-1b2c3d4e5f6a",
  "dealer_id": "78daa7fe-2409-4c2e-9efc-1b82f16b93f0",
  "target_vehicle_id": null,
  "operation": "create",
  "status": "pending",
  "payload": {
    "title": "Volkswagen Golf 8 Life 1.5 TSI",
    "plate": "EF456GH",
    "price": 27500,
    "km": 18000
  },
  "rejection_reason": null,
  "latest_notify_note": null,
  "latest_notify_at": null,
  "created_at": "2026-05-18T14:30:00.000Z",
  "updated_at": "2026-05-18T14:30:00.000Z"
}

PATCH/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,
    "share_price": 22900,
    "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 autosalone",
    "service_history": "Tagliandi ufficiali completi",
    "availability": "Pronta consegna",
    "location": "Milano",
    "color": "Grigio Metallizzato",
    "description": "Prezzo corretto come richiesto. Auto in ottimo stato.",
    "highlights": ["Unico proprietario", "Tagliandi ufficiali", "Pronta consegna"],
    "body_type": "Berlina",
    "emission_class": "Euro 6d",
    "equipment": ["Cerchi in lega", "Fari LED"],
    "coverImage": "https://cdn.youmotor.com/img/EF456GH/cover.jpg",
    "images": [
      "https://cdn.youmotor.com/img/EF456GH/cover.jpg",
      "https://cdn.youmotor.com/img/EF456GH/01.jpg",
      "https://cdn.youmotor.com/img/EF456GH/02.jpg"
    ]
  }'

200Risposta

json

{
  "ok": true
}

Schema veicolo

Lo stesso payload di POST /partner/vehicles, PATCH /partner/vehicles/:id e POST /partner/vehicles/import. Il formato è snake_case. In lettura gli stessi campi tornano su GET /partner/vehicles, con gli importi come numeri JSON e la copertina in cover_image. I campi con asterisco * sono obbligatori.certifiedefeaturednon si inviano: la certificazione si legge solo nello stock e la assegna il backoffice. Non vengono mai restituiti note interne, conteggio visite, metadata e prezzi offerta.

Foto: copertina ed elenco

Caricate i file, prendete gli URL e metteteli tutti in images.coverImageindica quale di quelle foto è la copertina.

Minimo 3 · massimo 40

coverImage

Un solo URL, già presente in images. Se manca, la copertina è la prima foto.

Foto 1

Copertina

https://cdn.youmotor.com/foto1.webp

images

Tutte le foto, copertina inclusa, nell'ordine di visualizzazione.

1Frontalefoto1.webpCopertina
2Lateralefoto2.webp
3Internifoto3.webp

In lettura: gli stessi URL in images, la copertina in cover_image.

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	Gettone visibilità: default 300 €, minimo 0 €, modificabile a passi di 50 €.
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	Si	Potenza in kW (1-2000).
power_hp*	integer	Si	Potenza in CV (1-2000).
neopatentato	boolean	No	Opt-in: auto adatta ai neopatentati. true solo con power_kw 1-105, oppure power_hp 1-143 se manca il kW. In update, ometterlo non cambia il valore. I 75 kW/t sulla tara restano sul libretto.
corsa	boolean	No	Opt-in: auto classificata per le corse. Compare nel catalogo Corse. In update, ometterlo non cambia il valore.
co2_emissions	integer?	No	Emissioni CO₂ in g/km (0-1500).
fuel_consumption_combined	string?	No	In scrittura: 0-999,99, massimo 2 decimali, es. "5.4 l/100km". In lettura torna solo il numero.
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*	enum	Si	Pronta consegna, In trattativa, Su ordinazione o Disponibile a breve.
province*	string	Si	Provincia canonica da vehicle-options group=province. La risposta include region derivata. Estero vale fuori Italia; Altro e San Marino sono salvati come Estero.
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[]	No	Facoltativi. Se presenti, 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	Si	Prezzo al rivenditore, sempre valorizzato, maggiore di 0 e non superiore a price. Se omesso, è il prezzo pubblico meno 90 €. Riservato ad agenzie e autosaloni autorizzati; non visibile al cliente finale.
coverImage*	string	Si	URL della copertina. Deve essere uno degli URL di images. Se manca, si usa la prima foto dell'elenco.
images*	string[]	Si	Tutte le foto, copertina inclusa. Almeno 3 URL unici, massimo 40. Sono gli URL restituiti dall'upload.

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

Foto: copertina ed elenco

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

Foto: copertina ed elenco

Codici di errore