Indice

Collegarsi al CRM tramite API

manuale
Opencrmitalia

VERSIONE: 1.0.0

Integrazione con Applicazioni di Terze Parti (API REST)

Le API REST (Webservices) consentono di sfruttare le funzionalità esposte su HTTP(s) per inviare o ricevere dati dal CRM e per integrarli con applicazioni di terze parti. È possibile utilizzare la libreria di propria scelta per interagire con queste API. Ad esempio, vtwsclib offre supporto per vari linguaggi di programmazione.

1. Formato della Richiesta

  • Metodi HTTP: GET / POST
  • Content-Type: application/x-www-form-urlencoded

2. Formato della Risposta

In caso di successo

{
    "success": true,
    "result": {
        // ...
    }
}

In caso di errore

{
    "success": false,
    "error": {
        "message": "String",
        "code": "String"
    }
}

3. Operazioni

3.1 Operazione di Login

Il processo di login avviene in due fasi:

  1. Ottenimento del Challenge
  2. Scambio delle credenziali (username e accessKey)

N.B.: L'accessKey è disponibile nelle preferenze utente del CRM

3.1.1 Ottenimento del Challenge

Richiesta:

GET /webservice.php?operation=getchallenge&username=<USERNAME> HTTP/1.1

Risposta:

{
    "success": true,
    "result": {
        "token": "TOKENSTRING",    // Token di sfida da utilizzare per il login.
        "serverTime": "TIMESTAMP", // Ora attuale del server.
        "expireTime": "TIMESTAMP"  // Momento in cui il token scade.
    }
}

3.1.2 Esecuzione del Login

Richiesta:

POST /webservice.php HTTP/1.1

operation=login
username=<USERNAME>
accessKey=md5(TOKENSTRING + <ACCESSKEY>)

N.B.: "accessKey" è scritto con la 'K' maiuscola.

Risposta:

{
    "success": true,
    "result": {
        "sessionName":   "String", // Identificatore univoco della sessione (sessionId).
        "userId":        "String", // ID dell'utente nel CRM.
        "version":       "String", // Versione dell'API Webservice.
        "vtigerVersion": "String"  // Versione del CRM.
    }
}

3.2 Operazione di Logout

Richiesta:

POST /webservice.php HTTP/1.1

operation=logout
sessionName=sessionId  // SessionId ottenuto tramite l'Operazione di Login.

3.3 Operazione "List Types"

Richiesta:

GET /webservice.php?operation=listtypes&sessionName=sessionId HTTP/1.1

3.4 Operazione "Describe"

Richiesta:

GET /webservice.php?operation=describe&sessionName=sessionId&elementType=<TYPE> HTTP/1.1

3.5 Operazione di Creazione

Richiesta:

POST /webservice.php HTTP/1.1

operation=create
sessionName=sessionId        // Ottenuto tramite l'Operazione di Login.
element=URLENCODED(JSONDATA)   // JSONDATA: mappa JSON (fieldname=fieldvalue).
elementType=<TYPE>           // <TYPE>: Nome del modulo.

3.6 Operazione di Recupero

Richiesta:

GET /webservice.php?operation=retrieve&sessionName=sessionId&id=<WEBSERVICE_ID> HTTP/1.1

3.7 Operazione di Aggiornamento

Richiesta:

POST /webservice.php HTTP/1.1

operation=update
sessionName=sessionId      // Ottenuto tramite l'Operazione di Login.
element=URLENCODED(DATA)   // DATA: mappa dei campi (fieldname=fieldvalue).

3.8 Operazione di Eliminazione

Richiesta:

POST /webservice.php HTTP/1.1

operation=delete
sessionName=sessionId      // Ottenuto tramite l'Operazione di Login.
id=<WEBSERVICE_ID>

3.9 Operazione di Query

Richiesta:

GET /webservice.php?operation=query&sessionName=sessionId&query=<QUERY> HTTP/1.1

Formato del <QUERY>:

SELECT * | <lista_colonne> | <count(*)>
FROM <oggetto>
[WHERE <condizioni>]
[ORDER BY <lista_colonne>]
[LIMIT [<m>, ] <n>]
  • <lista_colonne>: Elenco separato da virgole dei nomi dei campi.
  • Nome del modulo (tipo).
    • Operazioni condizionali (<, >, <=, >=, =, !=).
    • Clausole in ().
    • Clausole like 'sqlregex'. Le condizioni devono essere separate dagli operatori and o or (processate da sinistra a destra) e non è previsto l’uso di parentesi per il raggruppamento.
  • <lista_valori>: Elenco di valori separati da virgola.
  • <\m> <\n>: Valori interi per specificare rispettivamente l’offset e il limite.

Limitazioni:

  • Le query sono attualmente limitate a un singolo oggetto.
  • Le join non sono supportate.
  • Per default, la query limita l’output a 100 record; l’applicazione client può utilizzare l’operatore LIMIT per recuperare un diverso set di record.

3.10 Operazione di Sincronizzazione

Richiesta:

GET /webservice.php?operation=sync&sessionName=sessionId&modifiedTime=<TIMESTAMP>&elementType=<TYPE> HTTP/1.1

3.11 Operazione di Estensione della Sessione

Richiesta:

GET /webservice.php?operation=extendsession HTTP/1.1

Questo documento riassume le principali operazioni per l'integrazione di applicazioni di terze parti tramite le API REST del CRM. Utilizza queste informazioni come riferimento per implementare le chiamate API necessarie alle tue integrazioni.

Collection postman

Postman è un ambiente per lo sviluppo e l'utilizzo di API con una interfaccia semplice e intuitiva che vi consentirà di effettuare chiamate alle API del CRM. Le chiamate HTTP che potete effettuare all'enpoint webservice.php le abbiamo strutturate e documentate in una collection postman, questi sono tutti gli step che dovete eseguire per utilizzare questo strumento:

1. Import

  • Scaricare il client Postman dal seguente link;
  • Scaricare la nostra collection postman cliccando qui;
  • Avviare il client e registare un account;
  • Cliccare sul pulsante Import in altro a sinistra e importare la collection che avete scaricato;

2. Inizializzazione

Sulla sinistra vi troverete la collection Webservice opencrmitalia, cliccate sopra al nome della collection per aprire i dettagli e in alto trovere le seguenti tab:

Overwiew

Nella tab Overwiew troverete una introduzione sulla collection e se cercate maggiori dettagli sulle singole chiamate HTTP potete visualizzarli cliccando sulla voce View complete documentation

Variables

Nella tab Variables dovete specificare le credenziali del CRM, nello specifico dovrete popolare la colonna Current value delle seguenti variabili:

  • enpoint: inserire il dominio del crm, es: https://nomecrm.opencrmitalia.com
  • username: specificare l'username a cui volete accedere,
  • password: dovete inserire la password che trovate nel campo password presente nelle impostazione dell'utente sul CRM,

3. Utilizzo

Per effettuare una chiamata HTTP basta selezionare l'operazione che ci serve presente nelle cartelle della collectione e cliccare sul pulsante Send in alto a destra, nel box in basso possiamo visualizzare la risposta della chiamata.
Prima di inviare la chiamata HTTP che ci serve dobbiamo effettuare il login inviando la chiamata Challenge che richiede il token che servirà alla chiamata successiva Login che ci restituirà il sessionName che verrà usato da tutte le altre chiamate successive. Tutte le variabili come token, sessionName e molte altre vengono popolate automaticamente all'interno della collection attraverso degli script.