{"openapi":"3.0.3","info":{"title":"portaleauto — API per i concessionari","version":"1","description":"Sincronizzazione degli annunci dal gestionale. Un annuncio per chiamata. Per token: una raffica fino a 60 chiamate, poi 1 al secondo (60 al minuto a regime); oltre, 429 con Retry-After. Con un token di prova (pa_test_…) ogni scrittura viene convalidata e NON eseguita."},"servers":[{"url":"https://portaleauto.com/api/concessionari/v1"}],"security":[{"token":[]}],"paths":{"/account":{"get":{"operationId":"account","summary":"Stato dell'account","description":"Dice a chi appartiene il token, che permessi ha, e quanti annunci il piano lascia ancora inserire. È la chiamata con cui provare che il collegamento funziona.\n\nPermesso richiesto: lettura.","responses":{"200":{"description":"Esito","content":{"application/json":{"example":{"data":{"concessionario":"Autosalone Esempio","token":{"nome":"Gestionale","modalita":"test","permessi":["lettura","scrittura"],"scade_il":"2027-10-06T00:00:00.000Z"},"piano":{"nome":"Pro+","annunci_massimi":200,"annunci_inseriti":42,"posti_liberi":158},"limiti":{"chiamate_al_minuto":60}}}}}},"default":{"description":"Rifiuto: `error.code` dice quale","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["token-mancante","token-non-valido","piano-senza-api","mandato-scaduto","ambito-mancante","non-trovato","annuncio-chiuso","annuncio-riservato","telaio-diverso","targa-diversa","dato-vecchio","salto-di-prezzo","limite-piano","non-ammesso","troppo-grande","dati-non-validi","versione-da-scegliere","troppe-chiamate","tetto-ritiri","errore-nostro"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}}}},"/annunci":{"get":{"operationId":"elenco","summary":"Elenco degli annunci","description":"I tuoi annunci non archiviati, cento per pagina (`?pagina=2`). Quelli creati a mano o da file hanno `riferimento` vuoto finché non li colleghi inviando lo stesso telaio (o la stessa targa, se il telaio manca). Targa e telaio non escono mai.\n\nPermesso richiesto: lettura.","responses":{"200":{"description":"Esito","content":{"application/json":{"example":{"data":{"pagina":1,"totale":1,"annunci":[{"riferimento":"AUTO-1042","id":"0199c1d2-1111-7000-8000-000000000000","stato":"bozza","marca":"Volkswagen","modello":"Golf","versione":"1.5 TSI 150 CV Life","prezzo":18900,"chilometri":45000,"foto":2,"foto_in_coda":0,"scade_il":null,"aggiornato_il":"2026-10-06T09:30:00.000Z","indirizzo":null}]}}}}},"default":{"description":"Rifiuto: `error.code` dice quale","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["token-mancante","token-non-valido","piano-senza-api","mandato-scaduto","ambito-mancante","non-trovato","annuncio-chiuso","annuncio-riservato","telaio-diverso","targa-diversa","dato-vecchio","salto-di-prezzo","limite-piano","non-ammesso","troppo-grande","dati-non-validi","versione-da-scegliere","troppe-chiamate","tetto-ritiri","errore-nostro"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}}}},"/annunci/{riferimento}":{"get":{"operationId":"leggi","summary":"Un annuncio","description":"L'annuncio con quel riferimento, con lo stato delle foto in coda.\n\nPermesso richiesto: lettura.","parameters":[{"name":"riferimento","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"}}],"responses":{"200":{"description":"Esito","content":{"application/json":{"example":{"data":{"riferimento":"AUTO-1042","id":"0199c1d2-1111-7000-8000-000000000000","stato":"bozza","marca":"Volkswagen","modello":"Golf","versione":"1.5 TSI 150 CV Life","prezzo":18900,"chilometri":45000,"foto":2,"foto_in_coda":0,"scade_il":null,"aggiornato_il":"2026-10-06T09:30:00.000Z","indirizzo":null}}}}},"default":{"description":"Rifiuto: `error.code` dice quale","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["token-mancante","token-non-valido","piano-senza-api","mandato-scaduto","ambito-mancante","non-trovato","annuncio-chiuso","annuncio-riservato","telaio-diverso","targa-diversa","dato-vecchio","salto-di-prezzo","limite-piano","non-ammesso","troppo-grande","dati-non-validi","versione-da-scegliere","troppe-chiamate","tetto-ritiri","errore-nostro"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}}},"put":{"operationId":"salva","summary":"Crea o aggiorna un annuncio","description":"Se il riferimento è nuovo nasce una BOZZA (servono tutti i campi obbligatori). Se esiste già, cambiano solo i campi che invii: quelli che non invii restano come sono, e ciò che hai curato a mano nel sito non viene toccato. La stessa chiamata si può ripetere quante volte vuoi: non crea mai un secondo annuncio. Se hai già caricato quell'auto a mano o da file, la prima chiamata con lo stesso telaio la collega al riferimento. I campi che identificano l'auto (marca, modello, targa…) dopo la creazione vengono ignorati e la risposta lo dice; un telaio diverso viene rifiutato. Per modificare un annuncio online il token deve avere il permesso «online».\n\nPermesso richiesto: scrittura.","parameters":[{"name":"riferimento","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Annuncio"},"example":{"marca":"Volkswagen","modello":"Golf","alimentazione":"benzina","potenza_kw":110,"cilindrata_cc":1498,"immatricolazione":"03/2021","condizione":"usata","prezzo":18900,"chilometri":45000,"colore":"grigio","nome_colore":"Grigio Delfino","proprietari":1,"targa":"ESEMPIO1","telaio":"ESEMPIO0000000001","comune":"Milano","provincia":"MI","descrizione":"Tagliandi regolari, unico proprietario.","condizioni_prezzo":"Finanziamento disponibile.","servizi_garanzie":"Garanzia estesa a 24 mesi.","foto":["https://example.com/foto-1.jpg","https://example.com/foto-2.jpg"],"aggiornato_il":"2026-10-06T09:30:00Z"}}}},"responses":{"200":{"description":"Esito","content":{"application/json":{"example":{"data":{"riferimento":"AUTO-1042","id":"0199c1d2-1111-7000-8000-000000000000","stato":"bozza","marca":"Volkswagen","modello":"Golf","versione":"1.5 TSI 150 CV Life","prezzo":18900,"chilometri":45000,"foto":2,"foto_in_coda":0,"scade_il":null,"aggiornato_il":"2026-10-06T09:30:00.000Z","indirizzo":null,"creato":true,"modificati":[],"ignorati":[],"foto_accettate":2,"foto_scartate":[]}}}}},"201":{"description":"Creato: il riferimento era nuovo ed è nata una bozza","content":{"application/json":{"example":{"data":{"riferimento":"AUTO-1042","id":"0199c1d2-1111-7000-8000-000000000000","stato":"bozza","marca":"Volkswagen","modello":"Golf","versione":"1.5 TSI 150 CV Life","prezzo":18900,"chilometri":45000,"foto":2,"foto_in_coda":0,"scade_il":null,"aggiornato_il":"2026-10-06T09:30:00.000Z","indirizzo":null,"creato":true,"modificati":[],"ignorati":[],"foto_accettate":2,"foto_scartate":[]}}}}},"default":{"description":"Rifiuto: `error.code` dice quale","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["token-mancante","token-non-valido","piano-senza-api","mandato-scaduto","ambito-mancante","non-trovato","annuncio-chiuso","annuncio-riservato","telaio-diverso","targa-diversa","dato-vecchio","salto-di-prezzo","limite-piano","non-ammesso","troppo-grande","dati-non-validi","versione-da-scegliere","troppe-chiamate","tetto-ritiri","errore-nostro"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}}}},"/annunci/{riferimento}/stato":{"post":{"operationId":"stato","summary":"Pubblica, metti in pausa, segna come venduto","description":"Cambia lo stato di UN annuncio, solo su richiesta esplicita: non esiste un «sostituisci tutto», e un annuncio che smetti di inviare resta com'è. Per pubblicare servono almeno una foto già scaricata, il concessionario verificato e un posto libero nel piano. «venduto» è definitivo e avvisa chi aveva salvato l'auto. L'archiviazione e il rinnovo alla scadenza si fanno solo dall'area riservata. Ripetere la stessa richiesta non ha effetti.\n\nPermesso richiesto: online.","parameters":[{"name":"riferimento","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stato"},"example":{"stato":"online"}}}},"responses":{"200":{"description":"Esito","content":{"application/json":{"example":{"data":{"riferimento":"AUTO-1042","id":"0199c1d2-1111-7000-8000-000000000000","stato":"online","marca":"Volkswagen","modello":"Golf","versione":"1.5 TSI 150 CV Life","prezzo":18900,"chilometri":45000,"foto":2,"foto_in_coda":0,"scade_il":"2026-11-05T09:30:00.000Z","aggiornato_il":"2026-10-06T09:30:00.000Z","indirizzo":"https://portaleauto.com/annunci/volkswagen-golf-1-5-tsi-150-cv-life-0199c1d2-1111-7000-8000-000000000000","cambiato":true}}}}},"default":{"description":"Rifiuto: `error.code` dice quale","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["token-mancante","token-non-valido","piano-senza-api","mandato-scaduto","ambito-mancante","non-trovato","annuncio-chiuso","annuncio-riservato","telaio-diverso","targa-diversa","dato-vecchio","salto-di-prezzo","limite-piano","non-ammesso","troppo-grande","dati-non-validi","versione-da-scegliere","troppe-chiamate","tetto-ritiri","errore-nostro"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}}}}},"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer"}},"schemas":{"Annuncio":{"type":"object","additionalProperties":false,"properties":{"marca":{"type":"string","description":"Come nel catalogo: Volkswagen, BMW, Fiat… (solo alla creazione)","example":"Volkswagen"},"modello":{"type":"string","description":"Golf, Serie 3, Panda… (solo alla creazione)","example":"Golf"},"alimentazione":{"type":"string","description":"Facoltativa, ma con i kW ci fa trovare la versione: benzina, diesel, mild hybrid benzina, mild hybrid diesel, full hybrid, plug-in, elettrica, gpl, metano, idrogeno (solo alla creazione)","example":"benzina"},"potenza_kw":{"type":"integer","description":"Facoltativa. Potenza in kW come sul libretto (P.2), non in cavalli (solo alla creazione)","example":110},"cilindrata_cc":{"type":"integer","description":"Cilindrata in cc (P.1); vuota per le elettriche (solo alla creazione)","example":1498},"immatricolazione":{"type":"string","description":"Prima immatricolazione: MM/AAAA oppure GG/MM/AAAA (facoltativa) (solo alla creazione)","example":"03/2021"},"condizione":{"type":"string","description":"nuova, km0, usata (serve per pubblicare: senza, l'auto entra come bozza) (solo alla creazione)","example":"usata"},"prezzo":{"type":"integer","description":"In euro, senza decimali e senza simboli: 12500 (serve per pubblicare: senza, l'auto entra come bozza)","example":18900},"chilometri":{"type":"integer","description":"Senza punti: 85000 (facoltativi: se li lasci vuoti l'annuncio dice «non indicati»)","example":45000},"colore":{"type":"string","description":"bianco, nero, grigio, argento, blu, rosso, verde, giallo, arancione, marrone, beige, altro (facoltativo)","example":"grigio"},"nome_colore":{"type":"string","description":"Il nome commerciale del colore (facoltativo)","example":"Grigio Delfino"},"proprietari":{"type":"integer","description":"Numero di proprietari precedenti (facoltativo)","example":1},"targa":{"type":"string","description":"Facoltativa. Se la indichi riconosciamo l'auto ed evitiamo annunci doppi. Non viene mai pubblicata (solo alla creazione)","example":"ESEMPIO1"},"telaio":{"type":"string","description":"Numero di telaio (VIN), 17 caratteri (facoltativo). Se lo indichi riconosciamo l'auto anche se cambia targa. Non viene mai pubblicato (solo alla creazione)","example":"ESEMPIO0000000001"},"comune":{"type":"string","description":"Dove si trova l'auto","example":"Milano"},"provincia":{"type":"string","description":"Sigla: MI, RM, NA…","example":"MI"},"descrizione":{"type":"string","description":"Testo dell'annuncio (facoltativo), senza targa né telaio. Puoi usare **grassetto**, *corsivo* e righe che iniziano con «- » per gli elenchi","example":"Tagliandi regolari, unico proprietario."},"condizioni_prezzo":{"type":"string","description":"Finanziamento e altre condizioni (facoltativo). Il prezzo resta quello che paga chiunque: qui scrivi solo ciò che si aggiunge","example":"Finanziamento disponibile."},"servizi_garanzie":{"type":"string","description":"Servizi e garanzie in più (facoltativo). La garanzia legale è già dovuta per legge: qui solo ciò che offri oltre","example":"Garanzia estesa a 24 mesi."},"foto":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":30,"description":"Indirizzi https delle foto, nell'ordine in cui vuoi mostrarle (al massimo 30). Le scarichiamo noi nei minuti successivi; le foto non vengono mai tolte da qui","example":["https://example.com/foto-1.jpg","https://example.com/foto-2.jpg"]},"versione_id":{"type":"string","description":"Identificativo della versione nel nostro catalogo. Serve solo quando marca, modello, alimentazione e kW corrispondono a più versioni: la risposta te le elenca (solo alla creazione)","example":"0199c1d2-0000-7000-8000-000000000000"},"aggiornato_il":{"type":"string","description":"Istante dell'ultima modifica nel tuo gestionale (ISO 8601). Se lo invii, un dato più vecchio di quello già ricevuto non sovrascrive quello nuovo","example":"2026-10-06T09:30:00Z"}},"description":"Alla creazione sono obbligatori: marca, modello, comune, provincia"},"Stato":{"type":"object","additionalProperties":false,"required":["stato"],"properties":{"stato":{"type":"string","enum":["online","pausa","venduto"]}}}}}}