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.