Annunci, prezzi e stato si aggiornano da soli con le API: un annuncio per chiamata, risposte chiare, un ambiente di prova che non scrive nulla. Comprese nel piano Pro+.
{
"prezzo": 18400,
"chilometri": 45210,
"aggiornato_il": "2026-10-06T09:30:00Z"
}Genera un token di prova
Dall'area riservata, in «Integrazioni». Controlla ogni chiamata come un token reale, ma non crea e non cambia nessun annuncio.
Prova le chiamate
Dal playground della stessa pagina o dal tuo gestionale: le risposte sono le stesse che riceverai dopo.
Passa al token reale
Quando tutto torna, genera un token reale con i permessi che servono e sostituiscilo nel gestionale.
Tutte le chiamate partono da un solo indirizzo e portano il token nell'intestazione Authorization. Mai nell'indirizzo.
Un token di prova comincia con pa_test_, uno reale con pa_live_. Si mostrano una volta sola, durano al massimo 12 mesi e si revocano dall'area riservata. Quello degli esempi è finto.
Usa l'indirizzo esatto, senza «www»: un reindirizzamento può far perdere il token al tuo programma. Per ogni token una raffica fino a 60 chiamate, poi una al secondo (60 al minuto a regime); oltre, la risposta è 429 con Retry-After e la chiamata non viene eseguita.
curl -X GET "https://portaleauto.com/api/concessionari/v1/account" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000"
lettura
Leggere i propri annunci e lo stato dell'account
scrittura
Creare bozze e aggiornare gli annunci che non sono online
online
Pubblicare, mettere in pausa, segnare come venduto e modificare gli annunci online
Sei regole che valgono per ogni chiamata: sono fatte perché un errore del gestionale non diventi un danno sui tuoi annunci.
Ogni chiamata riguarda una sola auto, indicata dal riferimento che ha nel tuo gestionale. La risposta dice subito com'è andata.
Il riferimento è unico: la stessa chiamata, ripetuta dopo un errore di rete o un timeout, non crea un secondo annuncio. Nel dubbio, ripeti.
In aggiornamento i campi che non invii restano come sono: la descrizione curata a mano nel sito non viene toccata.
Non esiste un «sostituisci tutto». Un'auto che smetti di inviare resta com'è: la pausa e il venduto si chiedono, annuncio per annuncio.
Un riferimento nuovo crea una bozza. Va online quando lo chiedi, se ha almeno una foto e il piano ha posto.
Un prezzo che salta di oltre il 30% su un annuncio online, un dato vecchio, troppi ritiri in un'ora: l'annuncio resta com'era e la risposta lo dice.
GET/account
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.
Permesso richiesto: lettura
curl -X GET "https://portaleauto.com/api/concessionari/v1/account" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000"
GET/annunci
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.
Permesso richiesto: lettura
curl -X GET "https://portaleauto.com/api/concessionari/v1/annunci" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000"
GET/annunci/{riferimento}
L'annuncio con quel riferimento, con lo stato delle foto in coda.
Permesso richiesto: lettura
curl -X GET "https://portaleauto.com/api/concessionari/v1/annunci/AUTO-1042" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000"
PUT/annunci/{riferimento}
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».
Permesso richiesto: scrittura
curl -X PUT "https://portaleauto.com/api/concessionari/v1/annunci/AUTO-1042" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000" \ -H "Content-Type: application/json" \ -d '{ "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" }'
POST/annunci/{riferimento}/stato
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.
Permesso richiesto: online
curl -X POST "https://portaleauto.com/api/concessionari/v1/annunci/AUTO-1042/stato" \ -H "Authorization: Bearer pa_test_000000000000000000000000000000000000000000000000" \ -H "Content-Type: application/json" \ -d '{ "stato": "online" }'
Gli stessi del modello per il caricamento da file, con lo stesso vocabolario. I numeri si scrivono con sole cifre. Un campo che non è in questo elenco viene rifiutato, non ignorato. Targa e telaio non vengono mai pubblicati e non escono mai dalle API.
Invia solo quelli che cambiano.
Identificano l'auto: dopo, se li invii, vengono ignorati e la risposta lo dice.
Una risposta 200 o 201 significa che la richiesta è stata eseguita. Ogni altra risposta ha la forma qui accanto: code è stabile e si usa nel programma, message è per le persone.
Un annuncio rifiutato non è sul portale: il gestionale deve leggere gli esiti. Li trovi anche nell'area riservata, in «Integrazioni», con il motivo.
{
"error": {
"code": "dati-non-validi",
"message": "Dati da correggere: prezzo (manca)",
"fields": {
"prezzo": "manca"
}
}
}Si indicano con indirizzi https: le copiamo noi nei minuti successivi, nell'ordine indicato. foto_in_coda dice quante mancano. Lo stesso indirizzo inviato di nuovo non viene riscaricato; le foto non si tolgono via API.
Un annuncio resta online 30 giorni per volta. Il rinnovo e l'archiviazione si fanno dall'area riservata: chiedono la conferma di una persona.
Chi genera il token rende una dichiarazione che vale per ogni operazione compiuta con quel token. Ogni pubblicazione e ogni modifica di un annuncio online viene registrata con i dati di quel momento.
I dati inviati non devono contenere dati di clienti o di precedenti proprietari.
Lo generi in un minuto dall'area riservata e provi ogni chiamata senza toccare i tuoi annunci.
Genera un token