18.10 REST Webservice

REST Webservice Settings

From the CRM settings its possible to view the available web services (referred here as webservice, or REST webservice), to allow external applications to interact with the CRM itself, using the REST paradigm. A webservice is accessible by an URL address (referred here as endpoint), usually made by the URL address of the vte installation, followed by /restapi/v1/vtews/, and the method name associated to the endpoint of interest.

Once configured, it is possible to invoke the desired endpoint with HTTP requests to execute the requested actions.

HTTP requests format

LeHTTP richiesterequests supportanosupport unicamente il metodothe POST emethod ilonly tipoand di autenticazionethe Basic, ossiaauthentication iltype, passaggiomeaning trathe idefinition campi header diof Authorization definitodefined comeas Basic <credenzialicredentials>, dovewhere <credenzialicredentials> èis la codifica inthe Base64 delencoding nomeof utentethe euser dellaname and the accesskey, separatiseparated daby :.

LeWebservice richiesterequests aiare webserviceintended sonoto pensatereturn pera restituire una rispostaresponse in formatoJSON JSON:format: inon casosuccess dithey successoreturn restituisconoa unostatus statoand ethe idata daticomputed elaboratiby dall'the endpoint, mentreand inon casoerror dithey errorereturn restituisconothe ilerror codicecode diand errorerelative e la relativa descrizione.description.

Selettore utente e visualizzazione accesskey, lista moduli e campi utilizzabili

Tramite l'apposita picklist, associata a Nome Utente, è possibile selezionare l'utente interessato; questo permette, tramite pulsanti appositi, di visualizzarne gli accesskey e i moduli accessibili per le richieste dall'utente selezionato.

Il pulsante associato a Webservice accesskey permette di mostrare, previo inserimento della propria password, gli accesskey generati dall'utente: questi vengono usati per autorizzare le richieste ai webservice, come osservato nel paragrafo Formato richieste HTTP. Da notare che per aggiungere ulteriori accesskey, l'utente deve accedere alle proprio preferenze, nella sezione Configurazione servizi web REST: si rimanda alla sezione dedicata alle preferenze utente.

Il pulsante associato a Lista di moduli e campi utilizzabili permette di visualizzare l'elenco dei moduli disponibili per l'utente e il loro nome interno, da usare nelle richieste ai webservice ove richiesto.

Pagina Documentazione REST (OpenAPI)

Cliccando il pulsante associato a Mostra Documentazione REST, è possibile accedere alla pagina adibita alla visualizzazione degli endpoint esposti dal CRM. Inizialmente vuota, basterà cliccare su Genera Documentazione OpenAPI per ottenere la definizione degli endpoint che verrà usata per la loro impaginazione.

E' quindi possibile testare i singoli endpoint premendo il pulsante Test Request per l'endpoint e l'utente interessato, posto nel riquadro di esempio adiacente alla descrizione del metodo. L'utente si può selezionare tramite l'apposito selettore, posto centralmente in alto nella pagina.

Configurazione Web service esterni per utilizzo nei processi

Nella pagina delle impostazioni è possibile aggiungere client web service esterni, basati su Zapier (si rimanda al capitolo dedicato), o impostazioni personalizzate.

Una volta configurati e attivati, tramite il pulsante Aggiungi Client Webservice, possono essere visionati nella sezione Lista webservice client configurati, e utilizzati nei processi.