Gestione degli annunci
======================

Un annuncio di un veicolo all'interno di GestionaleAuto.com è composto da più entità.

.. figure:: _static/ads_schema.png
   :scale: 75 %
   :alt: Schema strutturale di un annuncio
   :figclass: align-center

   Schema strutturale di un annuncio.

Ogni entità ha un suo *entry point* nelle API per gestire le
`operazioni CRUD <https://it.wikipedia.org/wiki/Tavola_CRUD>`_ e creare un annuncio consistente. |br|
Di seguito l'elenco delle operazioni possibili sugli annunci e i relativi *entry point* con i parametri da utilizzare.


Lettura
-------

Lista veicoli
~~~~~~~~~~~~~

.. function:: /<userid>/ads/

    **Metodo:** GET

    :param bool trashed: stato di eliminazione dell'annuncio selezionabile tra *true* o *false*. **Default:** *non impostato*.
    :param int offset: posizione del primo annuncio da estrarre. **Default:** *non impostato*.
    :param int limit: numero massimo di annunci da estrarre. **Default:** *non impostato*.
    :param str status: stato di attivazione dell'annuncio selezionabile tra *online* e *offline*. **Default:** *online*.
    :param str sort: parametri di ordinamento degli annunci separati da *|*. **Default:** *makemodel:asc*

    :return: lista degli annunci filtrati e paginati se richiesto; conteggio globale degli annunci (non paginato)

        .. code-block:: js

            {
              "count": 65,
              "ads": [
                {
                  "id": 7245757,
                  "macro": {
                    "id": 1,
                    "name": "Auto e commerciali leggeri"
                  },
                  "class": {
                    "id": 1,
                    "name": "Auto e commerciali leggeri"
                  },
                  "online": true,
                  "lastModified": 1482155414,
                  "startDate": 1504538122,
                  "internalCode": "AF252",
                  "usage": {
                    "id": 1,
                    "name": "usato"
                  },
                  "registrationDate": {
                    "month": 1,
                    "year": 2005
                  },
                  "km": 66228,
                  "plate": "EA028KF",
                  "vin": "012345678901",
                  "prices": {
                    "customers": 12000,
                    "dealers": 13000,
                    "new": 14500,
                    "partners": 10800,
                    "rent": 350,
                    "website": 11700
                  },
                  "model": {
                    "make": {
                      "id": 41,
                      "name": "LAMBORGHINI"
                    },
                    "model": {
                      "id": 16618,
                      "name": "Murciélago"
                    },
                    "version": {
                      "id": 13510614,
                      "name": "6.2 V12"
                    },
                    "body": {
                      "id": 6,
                      "name": "Coupè"
                    },
                    "fuel": {
                      "id": 1,
                      "name": "Benzina"
                    },
                    "gearbox": {
                      "id": 1,
                      "name": "Manuale"
                    },
                    "engineSize": 6192,
                    "powerKw": 426
                  },
                  "color": {
                    "exterior": {
                      "color": {
                        "id": 29,
                        "name": "Beige",
                        "hex": "#FFCC66"
                      },
                      "paint": {
                        "id": 1,
                        "name": "metallizzato"
                      }
                    }
                  },
                  "imagesCount": 20,
                  "mainImage": {
                    "small": "//cdn/8385911_T_59afb47996970.jpg",
                    "medium": "//cdn/8385911_N_59afb47990358.jpg",
                    "large": "//cdn/8385911_E_59afb4782d909.jpg",
                    "original": "//cdn/8385911_O_59afb478076d3.jpg",
                    "hd": "//cdn/8385911_O_59afb478076d3.jpg"
                  },
                  "labels": [
                    {
                      "id": 228,
                      "name": "conto vendita",
                      "color": {
                        "background": "#000000",
                        "text": "#FFFFFF"
                      }
                    }
                  ],
                  "videos": [
                    {
                        "id": 4261,
                        "url": "https://www.youtube.com/watch?v=3w9XzmGVGvA"
                    },
                    {
                        "id": 580,
                        "url": "https://www.youtube.com/watch?v=BRNK_h3MOxk"
                    }
                  ],
                  "websites": {
                    "active": 2,
                    "available": 20
                  }
                }
              ]
            }

    **Significato dei campi**

    Di seguito il significato dei campi e i possibili valori che possono assumere:

    * **count**: Il conteggio complessivo degli annunci del cliente (a prescindere dalla paginazione richiesta)
    * **ads**: *array* che contiene gli annunci che corrispondono al criterio di ricerca indicato.

    Nell'array **ads** sono contenute le strutture dell'annuncio, che hanno i seguenti campi:

    * **id**: Identificativo univoco dell'annuncio di GestionaleAuto.com
    * **macro**: Area di appartenenza del veicolo, con struttura di tipo *lookup* [#lookup]_
    * **class**: Classe di appartenenza del veicolo, una *class* appartiene ad una *macro*, una *macro* può contenere più *class*, anche in questo caso la struttura è di tipo *lookup* [#lookup]_
    * **online**: Valore *booleano* che indica se l'annuncio è stato pubblicato (o deve essere pubblicato) sui portali
    * **lastModified**: Data e ora di ultima modifica dell'annuncio, espressa come |unix_timestamp_link|_
    * **startDate**: Data di primo inserimento dell'annuncio, espressa come |unix_timestamp_link|_
    * **internalCode**: Codice di riferimento interno usato dal cliente, in formato stringa
    * **usage**: *Lookup* [#lookup]_ che indica lo stato d'uso del veicolo
    * **registrationDate**: Dizionario che contiene il mese (**month**) e l'anno (**year**) di immatricolazione
    * **km**: Chilometri attuali del veicolo
    * **plate**: Targa del veicolo
    * **vin**: Telaio del veicolo
    * **price**: Dizionario che contiene i prezzi del veicolo, più nel dettaglio:

        * **customer**: Prezzo riservato ai privati
        * **dealer**: Prezzo riservati ai commercianti
        * **new**: Prezzo di listino
        * **partners**: Prezzo riservato ai partners commerciali
        * **rental**: Prezzo di noleggio
        * **website**: Prezzo da visualizzare sul sito web del *dealer*

    * **model**: Struttura che contiene le caratteristiche associate al modello del veicolo, in particolare:

        * **make**: *Lookup* [#lookup]_ che indica la marca del veicolo
        * **model**: *Lookup* [#lookup]_ che indica il modello del veicolo
        * **version**: *Lookup* [#lookup]_ che indica la versione del veicolo
        * **body**: *Lookup* [#lookup]_ che indica la carrozzeria del veicolo
        * **fuel**: *Lookup* [#lookup]_ che indica il tipo di alimentazione del veicolo
        * **gearbox**: *Lookup* [#lookup]_ che indica il tipo di cambio del veicolo
        * **engineSize**: Cilindrata del veicolo
        * **powerKw**: Potenza, espressa in *kilowatt* del veicolo

    * **colors**: Struttura che contiene i colori dell'interno e degli esterni del veicolo

        * **external**: Colori dell'esterno del veicolo:

            * **color**: *Lookup* [#lookup]_ che indica il colore esterno del veicolo
            * **paint**: *Lookup* [#lookup]_ che indica il tipo di verniciatura esterna del veicolo

    * **imagesCount**: Indica quante foto sono state caricate per questo veicolo (escludendo le varie risoluzioni disponibili)
    * **mainImage**: Struttura che contiene la foto principale del veicolo [#photo]_
    * **options**: Struttura che contiene le *etichette* [#label]_ associate ad un veicolo
    * **videos**: Array che contiene identificativi univoci dei video di `Youtube <https://www.youtube.com>`_ (gli unici attualmente supportati su GestionaleAuto.com) e l'identificativo interno associato
    * **destinations**: Struttura che contiene un riassunto sui portali di pubblicazione disponibili e attivi per l'annuncio

        * **active**: Indica il numero di portali in cui l'annuncio sarà pubblicato
        * **available**: Indica il numero di portali disponibili per questo tipo di annuncio dove è possibile pubblicare

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/?offset=25&limit=25&status=online&container=list&sort=price:desc|year:asc
             -X GET
             -H "Authorization: <token>"

    **Struttura del parametro 'sort'**

    **Esempio:** *year:asc|makemodel:desc|price*

    **Valori accettati**
      - *makemodel*: marca / modello del veicolo; i valori nulli vengono visualizzati a inizio lista.
      - *price*: prezzo del veicolo; i valori nulli vengono visualizzati a inizio lista.
      - *year*: anno di immatricolazione del veicolo; i valori nulli vengono visualizzati a inizio lista.
      - *startdate*: data di inserimento del veicolo nell'archivio annunci.
      - *lastmodified*: data di ultima modifica del veicolo.

    **Versi di ordinamento accettati**
      - *asc*: crescente
      - *desc*: decrescente

    Se non specificato, il verso di default è *asc*.

    **Formati del parametro accettati**
      - *parametro:verso*
      - *parametro*

.. _ads-get:

Veicolo singolo
~~~~~~~~~~~~~~~

.. function:: /<userid>/ads/<id>

    **Metodo:** GET

    :return: dizionario dei dati in relazione *1-1* con l'annuncio.

        .. code-block:: js

            {
              "id": 8385386,
              "userid": "user1",
              "online": false,
              "startDate": 1504681060,
              "lastModified": 1505286169,
              "internalCode": "EEK12",
              "year": 2009,
              "macro": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "class": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "usage": {
                "id": 0,
                "name": "usato"
              },
              "registrationDate": {
                "month": 5,
                "year": 2009
              },
              "km": 30000,
              "plate": "EA028KF",
              "vin": "012345678901",
              "prices": {
                "customers": 12000,
                "dealers": 13000,
                "new": 14500,
                "partners": 10800,
                "rent": 350,
                "website": 11700
              },
              "priceType": {
                "id": 1,
                "name": "lordo"
              },
              "vatAmount": 22,
              "model": {
                "body": {
                  "id": 1,
                  "name": "2/3-Porte"
                },
                "engineSize": 1248,
                "consumption": {
                  "combined": 4.5,
                  "extraUrban": 3.9,
                  "urban": 5.9
                },
                "cylinders": 4,
                "doors": 3,
                "emissionClass": {
                  "id": 3,
                  "name": "E3"
                },
                "emissionCo2": 119.0,
                "fiscalPower": 15,
                "fuel": {
                  "id": 4,
                  "name": "Diesel"
                },
                "gearbox": {
                  "id": 1,
                  "name": "Manuale"
                },
                "gearsNumber": 6,
                "infocarCode": "080177200812",
                "powerKw": 66,
                "make": {
                  "id": 6,
                  "name": "ALFA ROMEO"
                },
                "model": {
                  "id": 191,
                  "name": "MiTo"
                },
                "seats": 4,
                "traction": {
                  "id": 2,
                  "name": "anteriore"
                },
                "version": {
                  "id": 15686294,
                  "name": "1.3 JTDm 16V 90 CV Distinctive"
                },
                "weight": 1150
              },
              "color": {
                "exterior": {
                  "color": {
                    "id": 29,
                    "name": "Beige",
                    "hex": "#FFCC66"
                  },
                  "paint": {
                    "id": 1,
                    "name": "metallizzato"
                  }
                },
                "interior": {
                  "color": {
                    "id": 1,
                    "name": "Nero",
                    "hex": "#000000"
                  },
                  "material": {
                    "id": 1,
                    "name": "Pelle"
                  }
                }
              },
              "imagesCount": 1,
              "mainImage": {
                "large": "//cdn/8385386_E_59af9c6433252.jpg",
                "medium": "//cdn/8385386_N_59af9c643db13.jpg",
                "original": "//cdn/8385386_O_59af9c6411611.jpg",
                "small": "//cdn/8385386_T_59af9c6443f7d.jpg",
                "hd": "//cdn/8385911_O_59afb478076d3.jpg"
              },
              "revisionExpireDate": {
                "month": 2020,
                "year": 9
              },
              "occasion": false,
              "businessVehicle": false,
              "claimableVat": false,
              "financingAvailable": false,
              "negotiable": false,
              "nonSmoking": false,
              "warranty": {
                "available": true,
                "months": 36,
                "type": {
                  "id": 1,
                  "name": "casa"
                }
              },
              "damaged": false,
              "subtitle": "Grande promozione su questa vettura",
              "additionalInformations": {
                "html": "<b>Descrizione della vettura</b>",
                "plain": "Descrizione della vettura"
              },
              "contractType": {
                "id": 1,
                "name": "vendita"
              },
              "availability": {
                "type": {
                  "id": 1,
                  "name": "In stock"
                },
                "from": 1505681060
              },
              "destination": [
                {
                  "id": 2,
                  "name": "Commercianti"
                }
              ],
              "qualitySeal": [
                {
                  "id": 1,
                  "name": "BMW, Premium Selection"
                }
              ],
              "wheel": {
                "status": "70",
                "type": {
                  "id": 3,
                  "name": "pista"
                }
              }
            }

    **Significato dei campi**

    Di seguito il significato dei campi e i possibili valori che possono assumere:

    * **id**: Identificativo univoco dell'annuncio all'interno di GestionaleAuto.com
    * **userid**: Identificativo univoco del proprietario dell'annuncio all'interno di GestionaleAuto.com
    * **online**: Valore *booleano* che indica se l'annuncio è stato pubblicato (o deve essere pubblicato) sui portali
    * **startDate**: Data di primo inserimento dell'annuncio, espressa come |unix_timestamp_link|_
    * **lastModified**: Data e ora di ultima modifica dell'annuncio, espressa come |unix_timestamp_link|_
    * **internalCode**: Codice di riferimento interno usato dal cliente, in formato stringa
    * **macro**: Area di appartenenza del veicolo, con struttura di tipo *lookup* [#lookup]_
    * **class**: Classe di appartenenza del veicolo, una *class* appartiene ad una *macro*, una *macro* può contenere più *class*, anche in questo caso la struttura è di tipo *lookup* [#lookup]_
    * **usage**: *Lookup* [#lookup]_ che indica lo stato d'uso del veicolo
    * **model**: Struttura che contiene le caratteristiche associate al modello del veicolo, in particolare:

        * **make**: *Lookup* [#lookup]_ che indica la marca del veicolo
        * **model**: *Lookup* [#lookup]_ che indica il modello del veicolo
        * **version**: *Lookup* [#lookup]_ che indica la versione del veicolo
        * **body**: *Lookup* [#lookup]_ che indica la carrozzeria del veicolo
        * **fuel**: *Lookup* [#lookup]_ che indica il tipo di alimentazione del veicolo
        * **gearbox**: *Lookup* [#lookup]_ che indica il tipo di cambio del veicolo
        * **engineSize**: Cilindrata del veicolo
        * **powerKw**: Potenza, espressa in *kilowatt* del veicolo
        * **consumption**: Struttura che contiene i consumi del veicolo, in particolare:

            * **urban**: Indica il ciclo del consumo urbano del veicolo
            * **combined**: Indica il ciclo del consumo misto del veicolo
            * **extraUrban**: Indica il ciclo del consumo extra - urbano del veicolo

        * **cylinders**: Indica il numero di cilindri del motore del veicolo
        * **doors** Indica il numero di porte del veicolo
        * **emissionClass**: *Lookup* [#lookup]_ che indica il tipo di emissioni del veicolo
        * **emissionCo2**: Emissioni di CO2 certificate del veicolo
        * **fiscalPower**: Potenza fiscale del veicolo
        * **gears**: Numero di marce del veicolo
        * **infocarCode**: Codice `Infocar <http://www.ibi.it/infocar.php>`_ che identifica il modello del veicolo
        * **seats**: Numero di posti per cui è omologato il veicolo
        * **traction**: *Lookup* [#lookup]_ che indica il tipo di trazione del veicolo
        * **weight**: Peso del veicolo, espresso in *kg*

    * **registrationDate**: Dizionario che contiene il mese (**month**) e l'anno (**year**) di immatricolazione
    * **km**: Chilometri attuali del veicolo
    * **plate**: Targa del veicolo
    * **vin**: Telaio del veicolo
    * **price**: Dizionario che contiene i prezzi del veicolo, più nel dettaglio:

        * **customer**: Prezzo riservato ai privati
        * **dealer**: Prezzo riservati ai commercianti
        * **new**: Prezzo di listino
        * **partners**: Prezzo riservato ai partners commerciali
        * **rental**: Prezzo di noleggio
        * **website**: Prezzo da visualizzare sul sito web del *dealer*

    * **priceType**: *Lookup* [#lookup]_ che indica la tipologia del prezzo indicato per il veicolo
    * **vatAmount**: Indica l´ `IVA <https://it.wikipedia.org/wiki/Imposta_sul_valore_aggiunto>`_ applicata a questo veicolo
    * **colors**: Struttura che contiene i colori del veicolo, in particolare:

        * **exterior**: Struttura che contiene i colori esterni del veicolo, in particolare:

            * **color**: *Lookup* [#lookup]_ che indica il colore della carrozzeria del veicolo, con la `rappresentazione esadecimale <https://it.wikipedia.org/wiki/RGB>`_ del colore
            * **paint**: *Lookup* [#lookup]_ che indica il tipo di vernice del veicolo

        * **interior**: Struttura che contiene i colori degli interni del veicolo, in particolare:

            * **color**: *Lookup* [#lookup]_ che indica il colore degli interni del veicolo, con la `rappresentazione esadecimale <https://it.wikipedia.org/wiki/RGB>`_ del colore
            * **material**: *Lookup* [#lookup]_ che indica il tipo di materiali dell'interno del veicolo

    * **imagesCount**: Indica quante foto sono state caricate per questo veicolo (escludendo le varie risoluzioni disponibili)
    * **mainImage**: Struttura che contiene la foto principale del veicolo [#photo]_
    * **revisionExpire**: Dizionario che contiene il mese (**month**) e l'anno (**year**) di scadenza della revisione
    * **occasion**: Valore *booleano* che indica se il veicolo è in offerta o meno
    * **businessVehicle**: Valore *booleano* che indica se il veicolo è di tipo aziendale
    * **claimableVat**: Valore *booleano* che indica se l'IVA è esposta o meno
    * **financingAvailable**: Valore *booleano* che indica se sul veicolo è possibile attivare un finanziamento
    * **negotiable**: Valore *booleano* che indica se il prezzo del veicolo è negoziabile o meno
    * **nonSmoking**:  Valore *booleano* che indica se il veicolo è per non fumatori
    * **warranty**: Struttura che indica lo stato della garanzia del veicolo, in particolare:

        * **available**: Valore *booleano* che indica se il veicolo è coperto da garanzia o meno
        * **months**: Numero di mesi per cui il veicolo è coperto da garanzia
        * **type**: *Lookup* [#lookup]_ che indica il tipo di garanzia applicata al veicolo

    * **damaged**: Valore *booleano* che indica se il veicolo è danneggiato o meno
    * **subtitle**: Stringa che contiene il sottotitolo dell'annuncio del veicolo, viene applicato sui portali che lo supportano
    * **additionalInformations**: Struttura che contiene le informazioni addizionali sul veicolo, in particolare:

        * **plain**: Informazioni addizionali in testo semplice (supportati da tutti i portali)
        * **html**: Informazioni addizionali in HTML [#strippedHTML]_ (supportati da alcuni portali)

    * **contractType**: *Lookup* [#lookup]_ che indica il tipo di contratto di vendita applicato al veicolo
    * **availability**: Struttura che contiene i dati di disponibilità del veicolo, in particolare:

        * **type**: *Lookup* [#lookup]_ che indica il tipo di disponibilità del veicolo
        * **from**: Inizio della disponibilità del veicolo, espresso come |unix_timestamp_link|_

    * **destination**: *Lookup* [#lookup]_ che indica a chi è destinato il veicolo per la vendita
    * **qualitySeal**: Lista che contiene le *lookup* [#lookup]_ dei *quality seal* certificati per il veicolo
    * **wheel**: Struttura che contiene le informazioni sui pneumatici del veicolo, in particolare:

        * **status**: Stato di usura dei pneumatici, espressi come percentuale di utilizzo
        * **type**: *Lookup* [#lookup]_ che indica il tipo di pneumatici


    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>
             -X GET
             -H "Authorization: <token>"

.. _get-ad-photos:

Foto
''''

.. function:: /<userid>/ads/<id>/photos

    **Metodo:** GET

    :return: lista delle immagini disponibili definite come da struttura [#photo]_ e relativo conteggio.

        .. code-block:: js

            {
              "count": 22,
              "photos": [
                {
                    "id": 23451,
                    "small": "//cdn/8385911_T_59afb47996970.jpg",
                    "medium": "//cdn/8385911_N_59afb47990358.jpg",
                    "large": "//cdn/8385911_E_59afb4782d909.jpg",
                    "original": "//cdn/8385911_O_59afb478076d3.jpg",
                    "hd": "//cdn/8385911_O_59afb478076d3.jpg"
                },
                ...
              ]
            }


    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos
             -X GET
             -H "Authorization: <token>"

Posizione foto
''''''''''''''

.. function:: /<userid>/ads/<id>/photos/<photoid>/order

    **Metodo:** GET

    :return: struttura contenente la posizione della foto all'interno della lista foto del singolo veicolo.

        .. code-block:: js

            {
                "order": 10
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos/<photoid>/order
             -X GET
             -H "Authorization: <token>"

    *photoid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-photos>`.

.. _get-ad-videos:

Video
'''''

.. function:: /<userid>/ads/<id>/videos

    **Metodo:** GET

    :return: lista dei video associati e relativo conteggio.

        .. code-block:: js

            {
              "count": 4,
              "videos": [
                {
                    "id": 7620,
                    "url": "https://www.youtube.com/watch?v=qBqC_bP2rd4"
                },
                ...
              ]
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/videos
             -X GET
             -H "Authorization: <token>"

Etichette
'''''''''

.. function:: /<userid>/ads/<id>/labels

    **Metodo:** GET

    :return: lista delle etichette associate definite come da struttura [#label]_ e relativo conteggio.

        .. code-block:: js

            {
              "count": 7,
              "labels": [
                {
                  "id": 1,
                  "name": "conto vendita",
                  "color": {
                    "background": "#000000",
                    "text": "#FFFFFF"
                  }
                },
                ...
              ]
            }


    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/labels
             -X GET
             -H "Authorization: <token>"

Accessori
'''''''''

.. function:: /<userid>/ads/<id>/options

    **Metodo:** GET

    :return: lista degli accessori associati e relativo conteggio.

        .. code-block:: js

            {
              "count": 16,
              "options": [
                {
                    "id": 6,
                    "name": "ABS"
                },
                {
                    "id": 132,
                    "name": "Airbag"
                },
                ...
              ]
            }


    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/options
             -X GET
             -H "Authorization: <token>"

.. _get-ad-websites:

Stato di pubblicazione
''''''''''''''''''''''

.. function:: /<userid>/ads/<id>/websites

    **Metodo:** GET

    :return: lista dei portali di pubblicazione disponibili e relativo conteggio.

        .. code-block:: js

            {
              "count": 25,
              "options": [
                {
                    "id": 6,
                    "name": "sito personale",
                    "activated": true
                },
                {
                    "id": 99,
                    "name": "automobile.it",
                    "activated": false
                },
                ...
              ]
            }

    Il campo *activated* indica il corrente stato di pubblicazione dell'annuncio sullo specifico portale.

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/websites
             -X GET
             -H "Authorization: <token>"


Inserimento
-----------

.. _insert-car-ad:

Automobile
~~~~~~~~~~

.. function:: /<userid>/ads/car

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **POST** un *JSON* che contiene tutti i parametri di un annuncio.

    .. code-block:: javascript

        {
          "model": {
            "infocarCode": "123456789012",
            "makeId": 7,
            "modelId": 387,
            "version": "What is love?",
            "bodyId": 1,
            "fuelId": 3,
            "powerKw": 39,
            "engineSize": 2049,
            "tractionId": 1,
            "emissionClassId": 5,
            "fiscalPower": 82,
            "doors": 3,
            "seats": 5,
            "weight": 4000,
            "emissionCo2": 422.0,
            "cylinders": 4,
            "consumption": {
                "extraUrban": 80.0
             },
             "gearboxId": 1,
             "gearsNumber": 4
          },
          "qualitySealIds": [
            2,
            3
          ],
          "color": {
              "exterior": {
                "colorId": 6,
                "paintId": 1
              },
              "interior": {
                "colorId": 2,
                "materialId": 1
              }
          },
          "internalCode": "12345678901234567890",
          "usageId": 1,
          "originId": 0,
          "registrationDate": {
            "year": 2014,
            "month": 1
          },
          "revisionExpireDate": {
            "month": 4,
            "year": 2018
          },
          "year": 2013,
          "km": 0,
          "wheelTypeId": 5,
          "wheelStatus": 40,
          "nonSmoking": true,
          "damaged": true,
          "claimableVat": false,
          "negotiable": true,
          "previousOwners": 4,
          "promptDelivery": false,
          "financingAvailable": true,
          "warranty": {
            "available": true,
            "months": 6,
            "typeId": 1
          },
          "plate": "AR 147 TD",
          "vin": "123433",
          "priceType": 0,
          "vatAmount": 22.0,
          "prices": {
            "customers": 1400,
            "rent": 200
          },
          "subtitle": "Lounge",
          "additionalInformations": "This is a test<br />Second line for a test",
          "contractTypeId": 1,
          "availabilityId": 3,
          "availability": {
            "typeId": 1,
            "from": {
                "year": 2018,
                "month": 4,
                "day": 1
            }
          },
          "website": [
            1
          ],
          "online": false
        }

    I possibili valori per i parametri di un annuncio sono:

    * **model**: Struttura che contiene le informazioni sul modello del veicolo associato all'annuncio, in particolare:

        * **infocarCode**: Codice `Infocar <http://www.ibi.it/infocar.php>`_ che identifica il modello del veicolo. Il campo è una stringa di al massimo **12** caratteri ed è **opzionale**
        * **makeId**: Identificativo univoco della marca del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-make>`
        * **modelId**: Identificativo univoco del modello del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-model>`
        * **version**: Versione del veicolo. Questo campo è una stringa **obbligatoria** di al massimo **50** caratteri
        * **bodyId**: Identificativo univoco della carrozzeria del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-body>`
        * **fuelId**: Identificativo univoco del tipo di alimentazione del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-fuel>`
        * **powerKw**: Potenza del veicolo, espressa in *kilowatt*. Il campo è **obbligatorio** e accetta valori compresi tra **1** e **2000**
        * **engineSize**: Cilindrata del veicolo. Il campo è **opzionale** e accetta valori compresi tra **50** e **10000**
        * **tractionId**:  Identificativo univoco del tipo di trazione del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-traction>`
        * **emissionClassId**: Identificativo univoco del tipo di emissioni del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-emission-class>`
        * **fiscalPower**: Cavalli fiscali del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **100**
        * **doors**: Porte del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **5**
        * **seats**: Posti presenti sul veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10**
        * **weight**: Peso del veicolo, espresso in *kg*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **100** e **7500**
        * **emissionCo2**: Emissioni di CO2 del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **500**
        * **cylinder**: Cilindri del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **16**
        * **consumption**: Struttura che contiene i consumi del veicolo espressi in l/100 km, in particolare:

            * **urban**: Consumo urbano del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**
            * **extraUrban**: Consumo extra - urbano del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**
            * **combined**: Consumo misto del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**

        * **gearboxId**: Identificativo univoco del tipo di cambio del veicolo. Il parametro è **obbligatorio** . I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-gearbox>`
        * **gearsNumber**: Numero delle marce del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **99**

    * **qualitySealIds**: *Array* che contiene l'elenco degli identificativi univoci dei sigilli di qualità che il veicolo possiede. La struttura è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-quality-seal>`
    * **color**: Struttura che contiene i colori del veicolo, in particolare:

        * **exterior**: Struttura **obbligatoria** che indica i colori esterni del veicolo, in particolare:

            * **colorId**: Identificativo univoco del colore dell'esterno del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-exterior-color>`
            * **paintId**: Identificativo univoco del tipo di vernice del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-paint>`

        * **interior**: Struttura **opzionale** che indica i colori degli interni del veicolo, in particolare:

            * **colorId**: Identificativo univoco del colore dell'interno del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-interior-color>`
            * **materialId**: Identificativo univoco dei materiali dell'interno del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-material>`

    * **internalCode**: Codice interno riservato ai clienti per il veicolo. E una stringa **opzionale** di al massimo **50** caratteri
    * **usageId**: Identificativo univoco dello stato d'uso del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-usage>`
    * **originId**: Identificativo univoco della provenienza del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-origin>`
    * **registrationDate**: Struttura **opzionale** che contiene la data di immatricolazione del veicolo. La struttura contiene il mese (**month**) e l'anno (**year**) di immatricolazione del veicolo
    * **revisionExpire**: Struttura **opzionale** che contiene la data di scadenza della revisione del veicolo. La struttura contiene il mese (**month**) e l'anno (**year**) di immatricolazione del veicolo
    * **year**: Anno in cui è stato prodotto il veicolo. Il campo è **obbligatorio**. I vlaori consentiti sono compresi tra **1920** e l´ **anno in corso**
    * **km**: Chilometraggio del veicolo. Il campo è **opzionale**. I valori consentiti vanno da **0** a **2.000.000** di chilometri
    * **wheelTypeId**: Identificativo univoco della tipologia di pneumatici del veicolo. Il campo è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-wheel-type>`
    * **wheelStatus**: Stato dell'usura dei pneumatici, il valore è **opzionale** e indica lo stato di usura espresso in percentuale, i valori ammessi sono compresi in *[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]*
    * **nonSmoking**: Valore *booleano* **opzionale** che indica se il veicolo era di proprietà di non fumatore
    * **damaged**: Valore *booleano* **opzionale** che indica se il veicolo è "danneggiato"
    * **occasion**: Valore *booleano* **opzionale** che indica se il veicolo è un'occasione
    * **claimableVat**: Valore *booleano* **opzionale** che indica se il veicolo ha l'IVA esposta
    * **negotiable**: Valore *booleano* **opzionale** che indica se i prezzi del veicolo sono negoziabili
    * **previousOwners**: Intero **opzionale** che indica il numero dei precedenti proprietari. I valori ammessi vanno da **0** a **99**
    * **promptDelivery**: Valore *booleano **opzionale** che indica se il veicolo è disponibile in pronta consegna
    * **financingAvailable**: Valore *booleano* **opzionale** che indica se è disponibile il finanziamento per il veicolo
    * **warranty**: Struttura che contiene le indicazioni della garanzia. I parametri sono **opzionali**. I dettagli della struttura sono:

        * **available**: Valore *booleano* **opzionale** che indica se la garanzia è disponibile per il veicolo
        * **months**: Indica per quanti mesi la garanzia è disponibile per il veicolo. Il valore è un intero **opzionale** con valori compresi tra **0** e **99**
        * **typeId**: Identificativo univoco del tipo di garanzia del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-warranty>`

    * **plate**: Stringa che contiene la targa del veicolo. Il parametro è **opzionale**. La stringa può contenere al massimo **10** caratteri
    * **vin**: Stringa che contiene il telaio del veicolo. Il parametro è **opzionale**. La stringa può contenere al massimo **20** caratteri
    * **priceTypeId**: Identificativo univoco del tipo di prezzo del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-price-type>`
    * **vatAmount**: IVA correlata al veicolo. Il parametro è **opzionale** e accetta come valori quelli contenuti nell'insieme *[7, 7.6, 9, 19, 20, 21, 22]*
    * **prices**: Struttura che contiene i prezzi del veicolo. I dettagli della struttura sono:

        * **customers**: Prezzo riservato ai *privati*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **dealers**: Prezzo riservato ai *commercianti*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **rent**: Prezzo del *noleggio*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **website**: Prezzo visibile sul *sito web*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **new**: Prezzo di *listino*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **partners**: Prezzo riservato ai *partners*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**

    * **subtitle**: Sottotitolo dell'annuncio. Il parametro è **opzionale**. La lunghezza massima è di **80** caratteri
    * **additionalInformations**: Testo in formato *HTML* della descrizione dell'annuncio. Il parametro è **opzionale** e la lunghezza massima è di **5000** caratteri; la versione *solo testo* del campo sarà calcolata partendo da questo valore e rimuovendo in modo intelligente i *tag HTML*. I tag HTML accettati sono ``<b></b>``, ``<ul></ul>``, ``<ol></ol>``, ``<li></li>``, ``<br>``, ``<hr>``
    * **contractTypeId**: Identificativo univoco del tipo di contratto del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-contract>`
    * **availability**: Struttura che identifica la disponibilità del veicolo. I parametri sono **opzionali**. I dettagli della struttura sono:

        * **availabilityId**: Identificativo univoco del tipo di disponibilità del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-availability>`
        * **from**: struttura della data di inizio disponibilità suddivisa in *year*, *month*, *day*.

    * **website**: *Array* di identificativi univoci di destinazioni del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-destination>`
    * **online**: Valore *booleano* **opzionale** (il *default* è ``true``) che indica se il veicolo deve essere pubblicato o meno

    :return: struttura contenente tutti i dati dell'annuncio creato come indicato nel :ref:`metodo di recupero di un annuncio <ads-get>`

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/car
             -d '<json_data>'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    .. note::

        I portali associati al Cliente saranno **tutti** automaticamente attivati per l'annuncio. Per disattivare uno specifico portale è necessario utilizzare l´ :ref:`apposita chiamata <update-website-activation-status>`.

.. _insert-motorbike-ad:

Moto
~~~~

.. function:: /<userid>/ads/motorbike

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **POST** un *JSON* che contiene tutti i parametri di un annuncio.

    .. code-block:: javascript

        {
          "model": {
            "makeId": 31,
            "modelId": 20126,
            "version": "What is love?",
            "bodyId": 15,
            "fuelId": 1,
            "transmissionId": 2,
            "stroke": 2,
            "powerKw": 39,
            "powerMaxAtRpm": 10000,
            "torqueKgm": 39,
            "torqueKgmAtRpm": 10000,
            "engineSize": 2729,
            "cylinders": 4,
            "cylindersDisposition": 1,
            "brakesId": 3,
            "coolingId": 2,
            "emissionClassId": 5,
            "fiscalPower": 82,
            "seats": 2,
            "tank": 1,
            "ignitionId": 2,
            "weight": 4000,
            "height": 4000,
            "width": 4000,
            "length": 200,
            "emissionCo2": 422.0,
            "gearboxId": 1,
            "gearsNumber": 4,
            "consumption": {
                "extraUrban": 80.0
             }
          },
          "color": {
              "exterior": {
                "colorId": 6,
                "paintId": 1
              }
          },
          "internalCode": "12345678901234567890",
          "usageId": 1,
          "originId": 0,
          "year": 2013,
          "registrationDate": {
            "year": 2014,
            "month": 1
          },
          "revisionExpireDate": {
            "month": 4,
            "year": 2018
          },
          "km": 0,
          "wheelTypeId": 5,
          "wheelStatus": 40,
          "damaged": false,
          "claimableVat": false,
          "negotiable": false,
          "previousOwners": 1,
          "promptDelivery": false,
          "financingAvailable": false,
          "warranty": {
            "available": true,
            "months": 6,
            "typeId": 1
          },
          "plate": "BM 147 WW",
          "vin": "123433",
          "priceType": 0,
          "vatAmount": 22.0,
          "prices": {
            "customers": 12300
          },
          "subtitle": "Lounge",
          "additionalInformations": "This is a test<br /><b>Taken</b> or not?<b><b>",
          "contractTypeId": 1,
          "availability": {
            "typeId": 1,
            "from": {
                "year": 2018,
                "month": 4,
                "day": 1
            }
          },
          "destination": [
            1
          ],
          "online": true
        }


    I possibili valori per i parametri di un annuncio sono:

    * **model**: Struttura che contiene le informazioni sul modello del veicolo associato all'annuncio, in particolare:

        * **makeId**: Identificativo univoco della marca del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-make-motorbike>`
        * **modelId**: Identificativo univoco del modello del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-model-motorbike>`
        * **version**: Versione del veicolo. Questo campo è una stringa **obbligatoria** di al massimo **50** caratteri
        * **bodyId**: Identificativo univoco della carrozzeria del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-body-motorbike>`
        * **fuelId**: Identificativo univoco del tipo di alimentazione del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-fuel-motorbike>`
        * **transmissionId**: Identificativo univoco del tipo di trasmissione del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-transmission-motorbike>`
        * **stroke**: Tempi del motore del veicolo. Il campo è **opzionale** e accetta valori compresi tra **1** e **4** (solo interi)
        * **powerKw**: Potenza del veicolo, espressa in *kilowatt*. Il campo è **obbligatorio** e accetta valori compresi tra **1** e **2000**
        * **powerMaxAtRpm**: Potenza del veicolo in giri/minuto. Il campo è **opzionale** e accetta valori compresi tra **1** e **30000**
        * **torqueKgm**: Coppia del motore del veicolo. Il campo è **opzionale** e accetta valori compresi tra **1** e **65000**
        * **torqueKgmAtRpm**: Tempi del motore del veicolo. Il campo è **opzionale** e accetta valori compresi tra **1** e **30000**
        * **engineSize**: Cilindrata del veicolo. Il campo è **opzionale** e accetta valori compresi tra **50** e **10000**
        * **cylinders**: Cilindri del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **16**
        * **cylindersDispositionId**: Disposizione dei cilindri del veicolo. Il parametro è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-cylinder-disposition-motorbike>`
        * **brakesId**: Tipologia di freni del veicolo. Il parametro è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-brake-motorbike>`
        * **coolingId**: Tipologia di sistema di raffreddamento del veicolo. Il parametro è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-cooling-motorbike>`
        * **emissionClassId**: Identificativo univoco del tipo di emissioni del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-emission-class>`
        * **fiscalPower**: Cavalli fiscali del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **100**
        * **doors**: Porte del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **5**
        * **seats**: Posti presenti sul veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10**
        * **weight**: Peso del veicolo, espresso in *kg*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **100** e **7500**
        * **height**: Altezza del veicolo, espresso in *mm*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **50** e **20000**
        * **width**: Larghezza del veicolo, espresso in *mm*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **50** e **20000**
        * **length**: Lunghezza del veicolo, espresso in *mm*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **50** e **20000**
        * **emissionCo2**: Emissioni di CO2 del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **500**
        * **gearboxId**: Identificativo univoco del tipo di cambio del veicolo. Il parametro è **obbligatorio** . I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-gearbox>`
        * **gearsNumber**: Numero delle marce del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **99**
        * **consumption**: Struttura che contiene i consumi del veicolo, in particolare:

            * **urban**: Consumo urbano del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**
            * **extraUrban**: Consumo extra - urbano del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**
            * **combined**: Consumo misto del veicolo. Il parametro è **opzionale**. I valori consentiti sono compresi tra **0** e **100**


    * **color**: Struttura che contiene i colori del veicolo, in particolare:

        * **exterior**: Struttura **obbligatoria** che indica i colori esterni del veicolo, in particolare:

            * **colorId**: Identificativo univoco del colore dell'esterno del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-exterior-color>`
            * **paintId**: Identificativo univoco del tipo di vernice del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-paint>`

    * **internalCode**: Codice interno riservato ai clienti per il veicolo. E una stringa **opzionale** di al massimo **50** caratteri
    * **usageId**: Identificativo univoco dello stato d'uso del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-usage>`
    * **originId**: Identificativo univoco della provenienza del veicolo. Il campo è **obbligatorio**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-origin>`
    * **registrationDate**: Struttura **opzionale** che contiene la data di immatricolazione del veicolo. La struttura contiene il mese (**month**) e l'anno (**year**) di immatricolazione del veicolo
    * **revisionExpire**: Struttura **opzionale** che contiene la data di scadenza della revisione del veicolo. La struttura contiene il mese (**month**) e l'anno (**year**) di immatricolazione del veicolo
    * **year**: Anno in cui è stato prodotto il veicolo. Il campo è **obbligatorio**. I vlaori consentiti sono compresi tra **1920** e l´ **anno in corso**
    * **km**: Chilometraggio del veicolo. Il campo è **opzionale**. I valori consentiti vanno da **0** a **2.000.000** di chilometri
    * **wheelTypeId**: Identificativo univoco della tipologia di pneumatici del veicolo. Il campo è **opzionale**. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-wheel-type>`
    * **wheelStatus**: Stato dell'usura dei pneumatici, il valore è **opzionale** e indica lo stato di usura espresso in percentuale, i valori ammessi sono compresi in *[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]*
    * **damaged**: Valore *booleano* **opzionale** che indica se il veicolo è "danneggiato"
    * **occasion**: Valore *booleano* **opzionale** che indica se il veicolo è un'occasione
    * **claimableVat**: Valore *booleano* **opzionale** che indica se il veicolo ha l'IVA esposta
    * **negotiable**: Valore *booleano* **opzionale** che indica se i prezzi del veicolo sono negoziabili
    * **previousOwners**: Intero **opzionale** che indica il numero dei precedenti proprietari. I valori ammessi vanno da **0** a **99**
    * **promptDelivery**: Valore *booleano **opzionale** che indica se il veicolo è disponibile in pronta consegna
    * **financingAvailable**: Valore *booleano* **opzionale** che indica se è disponibile il finanziamento per il veicolo
    * **warranty**: Struttura che contiene le indicazioni della garanzia. I parametri sono **opzionali**. I dettagli della struttura sono:

        * **available**: Valore *booleano* **opzionale** che indica se la garanzia è disponibile per il veicolo
        * **months**: Indica per quanti mesi la garanzia è disponibile per il veicolo. Il valore è un intero **opzionale** con valori compresi tra **0** e **99**
        * **typeId**: Identificativo univoco del tipo di garanzia del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-warranty>`

    * **plate**: Stringa che contiene la targa del veicolo. Il parametro è **opzionale**. La stringa può contenere al massimo **10** caratteri
    * **vin**: Stringa che contiene il telaio del veicolo. Il parametro è **opzionale**. La stringa può contenere al massimo **20** caratteri
    * **priceTypeId**: Identificativo univoco del tipo di prezzo del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-price-type>`
    * **vatAmount**: IVA correlata al veicolo. Il parametro è **opzionale** e accetta come valori quelli contenuti nell'insieme *[7, 7.6, 9, 19, 20, 21, 22]*
    * **prices**: Struttura che contiene i prezzi del veicolo. I dettagli della struttura sono:

        * **customers**: Prezzo riservato ai *privati*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **dealers**: Prezzo riservato ai *commercianti*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **rent**: Prezzo del *noleggio*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **website**: Prezzo visibile sul *sito web*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **new**: Prezzo di *listino*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**
        * **partners**: Prezzo riservato ai *partners*. Il parametro è **opzionale**. I valori consentiti sono compresi tra **1** e **10.000.000**

    * **subtitle**: Sottotitolo dell'annuncio. Il parametro è **opzionale**. La lunghezza massima è di **80** caratteri
    * **additionalInformations**: Testo in formato *HTML* della descrizione dell'annuncio. Il parametro è **opzionale** e la lunghezza massima è di **5000** caratteri; la versione *solo testo* del campo sarà calcolata partendo da questo valore e rimuovendo in modo intelligente i *tag HTML*. I tag HTML accettati sono ``<b></b>``, ``<ul></ul>``, ``<ol></ol>``, ``<li></li>``, ``<br>``, ``<hr>``
    * **contractTypeId**: Identificativo univoco del tipo di contratto del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-contract>`
    * **availability**: Struttura che identifica la disponibilità del veicolo. I parametri sono **opzionali**. I dettagli della struttura sono:

        * **availabilityId**: Identificativo univoco del tipo di disponibilità del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-availability>`
        * **from**: struttura della data di inizio disponibilità suddivisa in *year*, *month*, *day*.

    * **destination**: *Array* di identificativi univoci di destinazioni del veicolo. I valori consentiti devono essere reperiti dall´ :ref:`apposita lookup <lookup-destination>`
    * **online**: Valore *booleano* **opzionale** (il *default* è ``true``) che indica se il veicolo deve essere pubblicato o meno

    :return: struttura contenente tutti i dati dell'annuncio creato come indicato nel :ref:`metodo di recupero di un annuncio <ads-get>`

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/car
             -d '<json_data>'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    .. note::

        I portali associati al Cliente saranno **tutti** automaticamente attivati per l'annuncio. Per disattivare uno specifico portale è necessario utilizzare l´ :ref:`apposita chiamata <update-website-activation-status>`.

Foto
~~~~

.. function:: /<userid>/ads/<id>/photos

    **Metodo:** POST

    .. note::

        *  Sono accettate esclusivamente immagini di tipo JPG o PNG.
        *  Il valore dell'header *Content-Type* (vedi esempio seguente) deve corrispondere al tipo del contenuto del file caricato, indipendentemente dall'estensione dello stesso.
        *  E'possibile inserire **una** sola immagine per chiamata.
        *  L'immagine inserita viene ordinata come ultima rispetto alle immagini eventualmente già presenti.

    :return: struttura contenente i dati dell'immagine inserita come da struttura [#photo]_.

        .. code-block:: js

            {
                "id": 23451,
                "small": "//cdn/8385911_T_59afb47996970.jpg",
                "medium": "//cdn/8385911_N_59afb47990358.jpg",
                "large": "//cdn/8385911_E_59afb4782d909.jpg",
                "original": "//cdn/8385911_O_59afb478076d3.jpg",
                "hd": "//cdn/8385911_O_59afb478076d3.jpg"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos
             --data-binary @<filepath>
             -X POST
             -H "Content-type: image/jpeg"
             -H "Authorization: <token>"

Video
~~~~~

.. function:: /<userid>/ads/<id>/videos

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente l'id del video appena inserito e l'url di visualizzazione.

        .. code-block:: js

            {
                "id": 7620,
                "url": "https://www.youtube.com/watch?v=qBqC_bP2rd4"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/videos
             -d '{"youtube_id": "<youtube_video_id>"}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    Il valore del parametro ``youtube_video_id`` corrisponde alla parte evidenziata del link: \https://www.youtube.com/watch?v= **qBqC_bP2rd4**

Accessorio
~~~~~~~~~~

Automobile
''''''''''

.. function:: /<userid>/db/options/car

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

        L'operazione NON mette in relazione l'accessorio con un veicolo. Per effettuare l'operazione usare :ref:`l'apposita chiamata <option-bind>`.

    :return: struttura contenente i dati dell'accessorio creato.

        .. code-block:: js

            {
                "id": 561,
                "name": "Inserti in radica"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/options/car
             -d '{"name": "<testo>"}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

Moto
''''

.. function:: /<userid>/db/options/motorbike

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

        L'operazione NON mette in relazione l'accessorio con un veicolo. Per effettuare l'operazione usare :ref:`l'apposita chiamata <option-bind>`.

    :return: struttura contenente i dati dell'accessorio creato.

        .. code-block:: js

            {
                "id": 456,
                "name": "Doppio scarico"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/options/motorbike
             -d '{"name": "<testo>"}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

Camper
''''''

.. function:: /<userid>/db/options/camper

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

        L'operazione NON mette in relazione l'accessorio con un veicolo. Per effettuare l'operazione usare :ref:`l'apposita chiamata <option-bind>`.

    :return: struttura contenente i dati dell'accessorio creato.

        .. code-block:: js

            {
                "id": 618,
                "name": "TV LED"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/options/camper
             -d '{"name": "<testo>"}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

Colore
~~~~~~

Esterni
'''''''

.. function:: /<userid>/db/color

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente i dati del colore creato.

        .. code-block:: js

            {
                "id": 456,
                "name": "Grigio Intellettuale",
                "is_interior": False,
                "base_id": 10
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/exterior/color
             -d '{"name": "<nome>", "base_id": <base_id>, "is_interior": True}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    Il colore di base *base_id* va reperito tra quelli disponibili tramite :ref:`l'apposita chiamata <base-color>`.

    Il campo *is_interior* indica che un colore può essere utilizzato per gli interni del veicolo. Il campo è opzionale e il suo valore di default è ``False``.

Etichetta
~~~~~~~~~

.. function:: /<userid>/db/labels

    **Metodo:** POST

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

        L'operazione NON mette in relazione l'etichetta con un veicolo. Per effettuare l'operazione usare :ref:`l'apposita chiamata <label-bind>`.

    :return: struttura contenente i dati dell'etichetta creata.

        .. code-block:: js

            {
                "id": 54,
                "name": "Occasione",
                "color": {
                    "background": "#ffffff",
                    "text": "#000000"
                }
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/labels
             -d '{"name": "<testo>", "style": "<style_id>"}'
             -X POST
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    Il valore del parametro ``style_id`` desiderato può essere ricavato da quelli disponibili attraverso :ref:`la relativa funzione <get-label-style>`.


Modifica
--------

Automobile
~~~~~~~~~~

.. function:: /<userid>/ads/car/<id>

    **Metodo:** PUT

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **PUT** un *JSON* che contiene **tutti** i parametri dell'annuncio che si desidera modificare (compresi i parametri che rimarranno uguali). |br|
    La struttura dei campi è analoga a quella citata nella :ref:`chiamata di inserimento <insert-car-ad>`.

    :return: la struttura dati completa dell'annuncio modificato.

        .. code-block:: javascript

            {
              "additionalInformations": {
                "html": null,
                "plain": null
              },
              "availability": {
                "from": {
                    "year": 2018,
                    "month": 4,
                    "day": 1
                },
                "typeId": 1
              },
              "occasion": false,
              "businessVehicle": false,
              "claimableVat": false,
              "class": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "colors": {
                "exterior": {
                  "color": {
                    "hex": "#999999",
                    "id": 21,
                    "name": "Antracite"
                  },
                  "paint": {
                    "id": 1,
                    "paint": "pastello"
                  }
                },
                "interior": {
                  "color": {
                    "hex": null,
                    "id": null,
                    "name": null
                  },
                  "material": {
                    "id": null,
                    "material": null
                  }
                }
              },
              "contractType": {
                "id": 0,
                "name": "Vendita"
              },
              "damaged": false,
              "destination": [],
              "financingAvailable": false,
              "id": 8417229,
              "imagesCount": 1,
              "internalCode": null,
              "km": null,
              "lastModified": 1505293956,
              "macro": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "mainImage": {
                "hd": null,
                "large": "//graphics.gestionaleauto.com/gonline_graphics/8417229_E_59b8f684d111d.jpg",
                "medium": "//graphics.gestionaleauto.com/gonline_graphics/8417229_N_59b8f684da10e.jpg",
                "original": "//graphics.gestionaleauto.com/gonline_graphics/8417229_O_59b8f684b148f.jpg",
                "small": "//graphics.gestionaleauto.com/gonline_graphics/8417229_T_59b8f684de9ba.jpg"
              },
              "model": {
                "body": {
                  "id": 11,
                  "name": "Station Wagon"
                },
                "consumption": {
                  "combined": 5.4,
                  "extraUrban": 4.8,
                  "urban": 6.3
                },
                "cylinders": "4",
                "doors": 5,
                "emissionClass": {
                  "id": 5,
                  "name": "E6"
                },
                "emissionCo2": 139,
                "engineSize": 1968,
                "fiscalPower": 20,
                "fuel": {
                  "id": 4,
                  "name": "Diesel"
                },
                "gearbox": {
                  "id": 1,
                  "name": "Manuale"
                },
                "gearsNumber": 6,
                "infocarCode": "107454201501",
                "make": {
                  "id": 9,
                  "name": "AUDI"
                },
                "model": {
                  "id": 24230,
                  "name": "A4 allroad"
                },
                "powerKw": 110,
                "seats": 5,
                "traction": "integrale permanente",
                "version": {
                  "id": 15743201,
                  "name": "2.0 TDI 150 CV cl.d."
                },
                "weight": 1630
              },
              "negotiable": false,
              "nonSmoking": false,
              "online": true,
              "plate": null,
              "price": {
                "customer": null,
                "dealer": null,
                "new": null,
                "partners": null,
                "rental": null,
                "website": null
              },
              "priceType": {
                "id": 2,
                "name": "Lordo"
              },
              "qualitySeal": null,
              "registrationDate": {
                "month": 2,
                "year": 2015
              },
              "revisionExpire": {
                "month": null,
                "year": null
              },
              "startDate": 1505293956,
              "subtitle": null,
              "trashed": false,
              "usage": {
                "id": 0,
                "name": "usato"
              },
              "userid": "upload1",
              "vatAmount": "0",
              "vin": null,
              "warranty": {
                "available": false,
                "months": null,
                "type": null
              },
              "wheel": {
                "status": null,
                "type": null
              }
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/car/<id>
             -d '<json_data>'
             -X PUT
             -H "Content-type: application/json"
             -H "Authorization: <token>"

.. function:: /<userid>/ads/car/<id>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **PATCH** un *JSON* che contiene **solamente** i parametri dell'annuncio che si desidera modificare. |br|
    La struttura dei campi è analoga a quella citata nella :ref:`chiamata di inserimento <insert-car-ad>`.

    :return: la struttura dati completa dell'annuncio modificato.

        .. code-block:: javascript

            {
              "additionalInformations": {
                "html": null,
                "plain": null
              },
              "availability": {
                "from": {
                    "year": 2018,
                    "month": 4,
                    "day": 1
                },
                "typeId": 1
              },
              "occasion": false,
              "businessVehicle": false,
              "claimableVat": false,
              "class": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "colors": {
                "exterior": {
                  "color": {
                    "hex": "#999999",
                    "id": 21,
                    "name": "Antracite"
                  },
                  "paint": {
                    "id": 1,
                    "paint": "pastello"
                  }
                },
                "interior": {
                  "color": {
                    "hex": null,
                    "id": null,
                    "name": null
                  },
                  "material": {
                    "id": null,
                    "material": null
                  }
                }
              },
              "contractType": {
                "id": 0,
                "name": "Vendita"
              },
              "damaged": false,
              "destination": [],
              "financingAvailable": false,
              "id": 8417229,
              "imagesCount": 1,
              "internalCode": null,
              "km": null,
              "lastModified": 1505293956,
              "macro": {
                "id": 1,
                "name": "Auto e commerciali leggeri"
              },
              "mainImage": {
                "hd": null,
                "large": "//graphics.gestionaleauto.com/gonline_graphics/8417229_E_59b8f684d111d.jpg",
                "medium": "//graphics.gestionaleauto.com/gonline_graphics/8417229_N_59b8f684da10e.jpg",
                "original": "//graphics.gestionaleauto.com/gonline_graphics/8417229_O_59b8f684b148f.jpg",
                "small": "//graphics.gestionaleauto.com/gonline_graphics/8417229_T_59b8f684de9ba.jpg"
              },
              "model": {
                "body": {
                  "id": 11,
                  "name": "Station Wagon"
                },
                "consumption": {
                  "combined": 5.4,
                  "extraUrban": 4.8,
                  "urban": 6.3
                },
                "cylinders": "4",
                "doors": 5,
                "emissionClass": {
                  "id": 5,
                  "name": "E6"
                },
                "emissionCo2": 139,
                "engineSize": 1968,
                "fiscalPower": 20,
                "fuel": {
                  "id": 4,
                  "name": "Diesel"
                },
                "gearbox": {
                  "id": 1,
                  "name": "Manuale"
                },
                "gearsNumber": 6,
                "infocarCode": "107454201501",
                "make": {
                  "id": 9,
                  "name": "AUDI"
                },
                "model": {
                  "id": 24230,
                  "name": "A4 allroad"
                },
                "powerKw": 110,
                "seats": 5,
                "traction": "integrale permanente",
                "version": {
                  "id": 15743201,
                  "name": "2.0 TDI 150 CV cl.d."
                },
                "weight": 1630
              },
              "negotiable": false,
              "nonSmoking": false,
              "online": true,
              "plate": null,
              "price": {
                "customer": null,
                "dealer": null,
                "new": null,
                "partners": null,
                "rental": null,
                "website": null
              },
              "priceType": {
                "id": 2,
                "name": "Lordo"
              },
              "qualitySeal": null,
              "registrationDate": {
                "month": 2,
                "year": 2015
              },
              "revisionExpire": {
                "month": null,
                "year": null
              },
              "startDate": 1505293956,
              "subtitle": null,
              "trashed": false,
              "usage": {
                "id": 0,
                "name": "usato"
              },
              "userid": "upload1",
              "vatAmount": "0",
              "vin": null,
              "warranty": {
                "available": false,
                "months": null,
                "type": null
              },
              "wheel": {
                "status": null,
                "type": null
              }
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/car/<id>
             -d '<json_data>'
             -X PUT
             -H "Content-type: application/json"
             -H "Authorization: <token>"

Moto
~~~~

.. function:: /<userid>/ads/motorbike/<id>

    **Metodo:** PUT

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **PUT** un *JSON* che contiene **tutti** i parametri dell'annuncio che si desidera modificare (compresi i parametri che rimarranno uguali). |br|
    La struttura dei campi è analoga a quella citata nella :ref:`chiamata di inserimento <insert-motorbike-ad>`.

    :return: struttura contenente tutti i dati dell'annuncio creato come indicato nel :ref:`metodo di recupero di un annuncio <ads-get>`

.. function:: /<userid>/ads/motorbike/<id>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    **Parametri della funzione**

    La funzione accetta nel corpo della chiamata **PUT** un *JSON* che contiene **solamente** i parametri dell'annuncio che si desidera modificare. |br|
    La struttura dei campi è analoga a quella citata nella :ref:`chiamata di inserimento <insert-motorbike-ad>`.

    :return: struttura contenente tutti i dati dell'annuncio creato come indicato nel :ref:`metodo di recupero di un annuncio <ads-get>`

.. _update-website-activation-status:

Stato di pubblicazione
~~~~~~~~~~~~~~~~~~~~~~

Singolo portale
'''''''''''''''

.. function:: /<userid>/ads/<id>/websites/<siteid>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
              "success": true
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/websites/<siteid>
             -X PATCH
             -d '{"activated": true}'
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    *siteid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-websites>`.

    Il valore del campo *activated* può essere solo ``true`` o ``false``.

Portali multipli
''''''''''''''''

.. function:: /<userid>/ads/<id>/websites

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
              "success": true
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/websites
             -X PATCH
             -d '{"items": [{"id": <id1>, "activated": <bool>}, ... {"id": <idN>, "activated": <bool>}]}'
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    *id1* ... *idN* possono essere ricavati tramite :ref:`l'apposita chiamata <get-ad-websites>`.

    Il valore del campo *activated* può essere solo ``true`` o ``false``.

Tutti i portali
'''''''''''''''

Attivazione
^^^^^^^^^^^

.. function:: /<userid>/ads/<id>/websites/all/enable

    **Metodo:** PATCH

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
              "success": true
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/websites/all/enable
             -X PATCH
             -H "Authorization: <token>"

Disattivazione
^^^^^^^^^^^^^^

.. function:: /<userid>/ads/<id>/websites/all/disable

    **Metodo:** PATCH

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
              "success": true
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/websites/all/disable
             -X PATCH
             -H "Authorization: <token>"

Posizione foto in un annuncio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. function:: /<userid>/ads/<id>/photos/<photoid>/order

    **Metodo:** PUT

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos/<photoid>/order
             -X PUT
             -d '{"order": <int>}'
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    *photoid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-photos>`.

    Il valore del campo *order* può essere solo un numero intero >=0.

    Qualora il valore del campo *order* sia superiore al totale delle foto disponibili per l'annuncio, la foto verrà spostata all'ultima posizione.

Video
~~~~~

.. function:: /<userid>/ads/<id>/videos/<videoid>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente l'id del video appena modificato e l'url di visualizzazione.

        .. code-block:: js

            {
                "id": 7620,
                "url": "https://www.youtube.com/watch?v=qBqC_bP2rd4"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/videos/<videoid>
             -d '{"youtube_id": "<youtube_video_id>"}'
             -X PATCH
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    *videoid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-videos>`.

    Il valore del parametro ``youtube_video_id`` corrisponde alla parte evidenziata del link: \https://www.youtube.com/watch?v= **qBqC_bP2rd4**

Accessorio
~~~~~~~~~~

Contenuto
'''''''''

.. function:: /<userid>/db/options/<optionid>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente i dati dell'accessorio aggiornato.

        .. code-block:: js

            {
                "id": 561,
                "name": "Inserti in noce"
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/options/<optionid>
             -d '{"name": "<testo>"}'
             -X PATCH
             -H "Content-type: application/json"
             -H "Authorization: <token>"

.. _option-bind:

Aggiunta a un annuncio
''''''''''''''''''''''

Singola
^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/options/<optionid>/add

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/options/<optionid>/add
             -X PUT
             -H "Authorization: <token>"

Multipla
^^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/options/add

    **Metodo:** PATCH

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/options/add
             -d '{"items": [id1, ..., idN]}'
             -X PATCH
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    Gli ID degli accessori da inserire possono essere reperiti tramite le apposite chiamate per ciascuna categoria di veicoli:

    *  :ref:`Auto <lookup-options-car>`
    *  :ref:`Moto <lookup-options-motorbike>`
    *  :ref:`Camper <lookup-options-camper>`


Rimozione da un annuncio
''''''''''''''''''''''''

Singola
^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/options/<optionid>/remove

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/options/<optionid>/remove
             -X PUT
             -H "Authorization: <token>"

Completa
^^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/options/remove

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/options/remove
             -X PUT
             -H "Authorization: <token>"

Colore
~~~~~~

.. function:: /<userid>/db/color/<colorid>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente i dati del colore aggiornato.

        .. code-block:: js

            {
                "id": 567,
                "name": "Giallo Sole",
                "is_interior": False,
                "base_id": 15
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/color/<colorid>
             -d '{"name": "<nome>", "base_id": <base_id>, "is_interior": true}'
             -X PATCH
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    *  Il valore di *colorid* può essere ricavato tramite :ref:`l'apposita chiamata <lookup-exterior-color>`.
    *  È necessario che sia presente almeno *un* valore da aggiornare.
    *  Il valore *is_interior*, il quale indica la possibilità di un colore di essere utilizzato per gli interni, può essere solo di tipo booleano.
    *  Il colore di base *base_id* va reperito tra quelli disponibili tramite :ref:`l'apposita chiamata <base-color>`.


Etichetta
~~~~~~~~~

Contenuto e stile
'''''''''''''''''

.. function:: /<userid>/db/labels/<labelid>

    **Metodo:** PATCH

    .. note::

        Il ``Content-Type`` della chiamata **deve** essere ``application/json``.

    :return: struttura contenente i dati dell'etichetta aggiornata.

        .. code-block:: js

            {
                "id": 54,
                "name": "Grande Occasione",
                "color": {
                    "background": "#ffffff",
                    "text": "#000000"
                }
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/labels/<labelid>
             -d '{"name": "<testo>", "style": "<style_id>"}'
             -X PATCH
             -H "Content-type: application/json"
             -H "Authorization: <token>"

    Per effettuare un aggiornamento deve essere presente almeno uno dei due parametri ``testo`` o ``style_id``.

    Il valore del parametro ``style_id`` desiderato può essere ricavato da quelli disponibili attraverso :ref:`la relativa funzione <get-label-style>`.

.. _label-bind:

Aggiunta a un annuncio
''''''''''''''''''''''

.. function:: /<userid>/ads/<vehicleid>/labels/<labelid>/add

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/labels/<labelid>/add
             -X PUT
             -H "Authorization: <token>"


Rimozione da un annuncio
''''''''''''''''''''''''

Singola
^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/labels/<labelid>/remove

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/labels/<labelid>/remove
             -X PUT
             -H "Authorization: <token>"

Completa
^^^^^^^^

.. function:: /<userid>/ads/<vehicleid>/labels/remove

    **Metodo:** PUT

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<vehicleid>/labels/remove
             -X PUT
             -H "Authorization: <token>"

Cancellazione
-------------

.. _delete-ad:

Annuncio
~~~~~~~~

.. function:: /<userid>/ads/<id>/trash

    **Metodo:** PUT

    .. note::

        Si tratta di una operazione logica, in quanto l'annuncio viene spostato in un cestino dal quale viene realmente rimosso dopo *5 giorni*.
        Mentre si trova nel cestino, sull'annuncio non è possibile eseguire alcuna operazione; per effettuare delle modifiche lo stesso va riportato nella lista principale tramite l'apposita :ref:`funzione di recupero <resume-ad>`.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/trash
             -X PUT
             -H "Authorization: <token>"

Foto
~~~~

Singola
'''''''

.. function:: /<userid>/ads/<id>/photos/<photoid>

    **Metodo:** DELETE

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos/<photoid>
             -X DELETE
             -H "Authorization: <token>"

    Il valore di *photoid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-photos>`.

Annuncio
''''''''

.. function:: /<userid>/ads/<id>/photos

    **Metodo:** DELETE

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/photos
             -X DELETE
             -H "Authorization: <token>"

Video
~~~~~

Singolo
'''''''

.. function:: /<userid>/ads/<id>/videos/<videoid>

    **Metodo:** DELETE

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/videos/<videoid>
             -X DELETE
             -H "Authorization: <token>"

    Il valore di *videoid* può essere ricavato tramite :ref:`l'apposita chiamata <get-ad-videos>`.

Annuncio
''''''''

.. function:: /<userid>/ads/<id>/videos

    **Metodo:** DELETE

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/videos
             -X DELETE
             -H "Authorization: <token>"

Accessorio
~~~~~~~~~~

.. function:: /<userid>/db/options/<optionid>

    **Metodo:** DELETE

    .. note::

        La cancellazione dell'accessorio implica anche la cancellazione di tutte le relazioni tra lo stesso e gli eventuali annunci associati.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/options/<optionid>
             -X DELETE
             -H "Authorization: <token>"

    Il valore di *labelid* può essere ricavato :ref:`l'apposita chiamata <get-labels>`.

Colore
~~~~~~

.. function:: /<userid>/db/color/<colorid>

    **Metodo:** DELETE

    .. note::

        Il colore non verrà rimosso se è attualmente in uso all'interno di un annuncio, *anche se nel cestino*.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/color/<colorid>
             -X DELETE
             -H "Authorization: <token>"


Etichetta
~~~~~~~~~

.. function:: /<userid>/db/labels/<labelid>

    **Metodo:** DELETE

    .. note::

        La cancellazione dell'etichetta implica anche la cancellazione di tutte le relazioni tra la stessa e gli eventuali annunci associati.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/db/labels/<labelid>
             -X DELETE
             -H "Authorization: <token>"

    Il valore di *labelid* può essere ricavato :ref:`l'apposita chiamata <get-labels>`.



Recupero
--------

.. _resume-ad:

Annuncio
~~~~~~~~

.. function:: /<userid>/ads/<id>/resume

    **Metodo:** PUT

    .. note::

        Inversa della :ref:`funzione di cancellazione <delete-ad>`.

    :return: struttura contenente l'esito dell'operazione.

        .. code-block:: js

            {
                "success": True
            }

    **Esempio CURL**

    .. code-block:: bash

        curl https://api.gestionaleauto.com/v2/<userid>/ads/<id>/trash
             -X PUT
             -H "Authorization: <token>"

----

.. rubric:: Note

.. [#lookup] Si intende come struttura di tipo *lookup* un dizionario *JSON* che contiene l'identificativo univoco
    dell'elemento e il relativo valore descrittivo.

    La struttura specifica del dizionario è la seguente:

    .. code-block:: javascript

        {
            "id": 5,
            "name": "descrizione"
        }

    *id* è solitamente un intero, mentre *name* è la stringa descrittiva della lookup.

.. [#photo] La struttura di una foto caricata in un annuncio è del tipo:

    .. code-block:: javascript

        {
            "small": "//cdn/8385911_T_59afb47996970.jpg",
            "medium": "//cdn/8385911_N_59afb47990358.jpg",
            "large": "//cdn/8385911_E_59afb4782d909.jpg",
            "original": "//cdn/8385911_O_59afb478076d3.jpg",
            "hd": "//cdn/8385911_O_59afb478076d3.jpg"
        }

    Dove:

    * **small** rappresenta la foto a risoluzione **160x120** pixels
    * **medium** rappresenta la foto a risoluzione **320x240** pixels
    * **large** rappresenta la foto a risoluzione **640x480** pixels
    * **original** rappresenta la foto a risoluzione **1024x768** pixels
    * **hd** rappresenta la foto a risoluzione **1920x1080** pixels (questa risoluzione a volte può essere non disponibile, il servizio **foto HD** e fornito come servizio supplementare a pagamento da GestionaleAuto.com)


.. [#label] La struttura delle *etichette* è fatta in questo modo:

    .. code-block:: javascript

        {
            "id": 4318,
            "name": "conto vendita",
            "color": {
                "background": "#000000",
                "text": "#FFFFFF"
            }
        }

    Dove:

    * **name**: Il testo visibile sull'etichetta
    * **color**: Struttura che contiene i colori dell'etichetta espressi in formato `RGB <https://it.wikipedia.org/wiki/RGB>`_:

        * **background**: Colore di sfondo dell'etichetta
        * **text**: Colore del testo dell'etichetta

.. [#strippedHTML] Non tutti i tag HTML sono supportati, quelli non riconosciuti saranno rimossi in fase di inserimento - modifica.

    Il testo *plain* e il testo *HTML* non possono differire, in fase di inserimento - modifica veicolo sarà permesso di inserire solo il testo *HTML* che sarà trasformato automaticamente dal sistema in *plain*.

.. This is a workaround to have line break,
   see: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline
.. |br| raw:: html

   <br />

.. Since RST does not allow nested tags, to have a link with formatting you must use this workaround
   see: https://stackoverflow.com/questions/10669099/italicize-text-containing-a-link
.. _unix_timestamp_link: https://it.wikipedia.org/wiki/Tempo_(Unix)

.. |unix_timestamp_link| replace:: *Unix Timestamp*