Collegarsi al CRM tramite API

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 Token di Sfida (Challenge)
  2. Scambio delle credenziali (username e accessKey)

Nota: L'accessKey è disponibile in "My Preferences" nella Web UI 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>) // Nota: "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" (Elenco dei Tipi)

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 (Create Operation)

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 (Retrieve Operation)

Richiesta:

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

3.7 Operazione di Aggiornamento (Update Operation)

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 (Delete Operation)

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>]
  • : 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.
  • : 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 (Sync Operation)

Richiesta:

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

3.11 Operazione di Estensione della Sessione (Extend Session Operation)

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.