Integración con aplicaciones de Terceros (REST APIs)

REST APIs (Webservices)

Tome ventaja del REST APIs expuestos a través de HTTP para empujar o servir datos de Vtiger e integrar con aplicaciones de terceros. Estás en libertad de elegir la librería de tu preferencia para trabajar con esta API. vtwsclib proporciona soporte para trabajar con las API REST a través de diversos lenguajes de programación.

El protocolo REST define un sistema consistente y seguro para acceder a la mayoría de las entidades de vtiger CRM. Permite un acceso directo a la base de datos sin pasar por la aplicación que facilita las tareas de integración entre esta aplicación y otras de distinta índole.

La implementación del protocolo realizada por vtiger CRM utiliza el formato JSON para representar las estructuras de datos e intercambio de información entre la aplicación final y vtiger CRM.

Cada entidad tiene un formato especial de identificación que se puede utilizar para conocer su tipo y el registro concreto. La operación de crear es el único caso en el que no se requiere una identificación de registro.

La siguiente sección muestra los detalles mas importantes para el uso de la API.

Formato de Llamada

Para acceder al servicio se llama siempre al mismo programa de la misma manera indicando la operación y los parámetros necesarios en cada caso.

HTTP - GET / POST application/x-www-form-urlencoded

http://url_vtiger/webservice.php?operation=[tipooperación]&sessionName=[nombresesión]&[parámeterosespecíficosdelaoperación]

El funcionamiento general se basa en:

• REST - API está basado en el protocolo REST, así que toda la comunicación entre cliente y servidor ocurre sobre HTTP como peticiones GET o POST.
• JSON - se utiliza el formato JSON para codificar las peticiones y las respuestas.
• Peticiones y Respuestas - La aplicación cliente prepara y envía peticiones de servicio al API, el API procesa la petición y devuelve una respuesta, finalmente la aplicación cliente gestiona la respuesta.
• Cambios inmediatos - Cada operación que escribe a un objeto vtiger CRM se guarda inmediatamente.

Formato de Respuesta

La respuesta a cualquier solicitud de servicio web es un objeto JSON. El objeto tiene un campo de éxito que tendrá el valor verdadero (true) si la operación fue un éxito y falso (false) en caso contrario. Si el resultado es falso el objeto de respuesta contendrá un campo “error” que contendrá un objeto JSON. El objeto de error contendrá dos campos o lineas de codigo, una sola palabra describiendo el error, y el message ,sera una cadena que contiene una descripción del error.

Por tanto, todas las respuestas de una ejecución, tendrán el siguiente formato.

Success

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

Failure

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

Login

permite la validación del usuario en el servicio y la conexión al servicio.

Es un proceso de dos pasos que implica obtener el token y el intercambio de las credenciales (nombre de usuario y la Key de acceso).Puede encontrar información accessKey en "Mis Preferencias" en el CRM.

Challenge

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

Challenge Response

{
        success: true,
        result: {
                token: TOKENSTRING,    // Challenge token to be used for login.
                serverTime: TIMESTAMP, // Hora acutal del servidor
                expireTime: TIMESTAMP  // Time when token expires
        }
}

Login

POST /webservice.php HTTP/1.1

operation=login

username=USERNAME

accessKey=md5(TOKENSTRING + ) // Note: accessKey= K here is capitalized.

http://vtiger_url/webservice.php?operation=login&username=[username]&accessKey=[accessKey]

Response

{
        success: true,
        result: {
                sessionId:      String, // Unique Identifier for the session
                userId:         String, // User ID in CRM
                version:        String, // Webservice API version
                vtigerVersion:  String  // Version of CRM
        }
}

Logout

Desconexión del servicio.

POST /webservice.php HTTP/1.1

operation=logout

sessionName=sessionId // obtenidos por medio de Login Operation

List Types

Obtiene una lista de módulos y campos disponibles.

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

Describe

Devuelve el conjunto de operaciones permitidas por el usuario conectado.

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

http://vtiger_url/webservice.php?operation=describeobject&sessionName=[sessionid]&elementType=[elementType]

El objeto devuelto por esta operación contiene estos campos:

1. label - etiqueta correspondiente al nombre del módulo.
2. name - el nombre del módulo.
3. createable - valor booleano indicando si el usuario conectado puede crear registros.
4. updateable - valor booleano indicando si el usuario conectado puede actualizar registros.
5. deleteable - valor booleano indicando si el usuario conectado puede eliminar registros.
6. retrieveable - valor booleano indicando si el usuario conectado puede obtener (consultar) registros.
7. fields - un array que contiene los nombres de los campos disponibles y toda su información sobre su tipo.

Cada elemento en el array de campos describe un campo en particular en el módulo.

1. name - el nombre del campo utilizado internamente por vtiger crm.
2. label - la etiqueta utilizada para mostrar el campo.
3. mandatory - valor booleano que indica si el campo es obligatorio, los campos obligatorios han de estar presentes a la hora de creación.
4. type - un array que describe el tipo de información contenida en el campo.
5. default - el valor por defecto del campo.
6. nillable - valor booleano indicando si el campo puede ser nulo/vacío.
7. editable - valor booleano indicando si el campo puede ser modificado.

El elemento type tiene importancia especial ya que describe el contenido de un campo. Es un array que contiene, al menos, un elemento denominado name que es el nombre del tipo de dato. El tipo puede ser:

1. string - una única línea de texto
2. text - un texto de varias líneas
3. integer - un número sin decimales
4. double - un número con decimales
5. boolean - campo lógico/booleano, contiene verdadero o falso
6. time - una cadena con el formato hh:mm, el formato se basa en las preferencias del usuario
7. date - un array con dos elementos, una cadena que representa una fecha y otro elemento con el formato en el que se espera el valor, se basa en las preferencias del usuario conectado
8. datetime - un array con dos elementos, una cadena que representa una fecha y hora, y otro elemento con el formato en el que se espera el valor, se basa en las preferencias del usuario conectado
9. autogenerated - Estos son los campos cuyos valores son generados automáticamente por vtiger CRM, estos suelen ser campos identificadores de un objeto
10. reference - Un campo que muestra una relación con otro objeto, el array contendrá, además, otro elemento llamado refersTo que es una matriz que contiene el nombre de los módulos con los que puede relacionarse
11. picklist - Un campo que puede contener una lista de valores, el array contendrá dos elementos, picklistValues que es una lista de valores posibles, y defaultValue que es el valor por defecto de la lista
12. multipicklist - Un campo picklist en el que se puede seleccionar varios valores
13. phone - un campo para almacenar teléfonos
14. email - un campo para almacenar identificadores de email
15. url - un campo para almacenar urls
16. skype - un campo para almacenar teléfonos o identificadores skype
17. password - un campo para almacenar contraseñas
18. owner - Un campo para definir el propietario del registro. Podría ser un grupo o usuario individual

Create

Crear nuevos registros en el CRM.

POST /webservice.php HTTP/1.1

operation=create

sessionName=sessionId // obtenidos por medio de Login Operation

element=URLENCODED(JSONDATA) // JSONDATA - JSON Map of (fieldname=fieldvalue)

elementType=TYPE // TYPE - Nombre del Modulo

Operación de Recuperación

Obtiene información de registros

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

Update Operation

Actualiza registros dentro del CRM.

POST /webservice.php HTTP/1.1

operation=update

sessionName=sessionId // obtenidos por medio de Login Operation

element=URLENCODED(DATA) // DATOS - Mapa de (fieldname=fieldvalue)

Delete Operation

Elimina registros dentro del CRM.

POST /webservice.php HTTP/1.1

operation=delete

sessionName=sessionId // obtenidos por medio de Login Operation

id=WEBSERVICE_ID

Query Operation

Permite ejecutar cualquier consulta en el CRM.

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

<QUERY>
FORMAT:
SELECT * | <column_list> | <count(*)>
FROM <object>
[WHERE <conditionals>]
[ORDER BY <column_list>]
[LIMIT [<m>, ] <n>]

LIMITACIONES

• Las consultas se limitan actualmente a un solo objeto.
• Si se unen no son compatibles.
• La consulta siempre limita su producción a 100 registros, la aplicación cliente puede utilizar el operador limite para obtener diferentes registros.

Sync Operation

Permite la obtención de todos los cambios realizados desde una fecha dada.

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

Extend Session Operation

permite utilizar la sesión definida al validarse en la aplicación, de esta manera se puede acceder al servicio de manera transparente una vez el usuario haya entrado en la aplicación de manera normal.

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

Nombre de Sesión

La clave que se utiliza para identificar la sesión actual. Esto debe ser enviada al servidor como parte de cada solicitud.

Seguridad

El servicio REST soporta el modelo de seguridad seguido en la interfaz de usuario vtiger CRM web, por lo que el usuario conectado solo podrá realizar aquellas operaciones que podría hacer en la aplicación.

Para elevar la seguridad en el servicio expuesto, el proceso de inicio de sesión utiliza un esquema en dos etapas desafío/respuesta.

Tipos de Datos utilizados

VtigerObject

Un mapa que representa el contenido de un objeto basado en crmentity. O sea, el contenido de cualquier registro de la aplicación que esté basada en un módulo o entidad.

Todos los campos de referencia se representa mediante el tipo de identificación (moduleid'x'recordid).

Existe un campo especial, llamado Id, que posee el formato de un identificador de entidad (moduleid'x'recordid), que es la clave de identificación de única del objeto. Este campo está presente para cualquier objeto que se obtenga de la base de datos.

Id Format

objectTypeId 'x' objectId objectTypeId - Identificador del tipo de objeto o entidad (módulo). Este número es generado unívocamente para cada entidad soportada por el API y puede ser obtenida para un módulo utilizando la operación describe.

Map

Un array asociativo de pares de clave ⇒ valor. Normalmente se utiliza en operación de creación.

TimeStamp

Un número entero largo representando el número de segundos desde Unix Epoch.

Entidades CRM

Lista de Entidades CRM expuestas por el servicio.