Este artículo sobre cómo integrar SugarCRM está dirigido para desarrolladores debido a su alto contenido especializado. 

Juan Antonio Longás // En muchas ocasiones, tendemos a trabajar con herramientas para diferentes propósitos. A veces tenemos que tratar la información por duplicado o trabajar la información en una herramienta y traspasarla posteriormente de manera manual a otra. Esto último repercute en el tiempo invertido solamente en normalizar la información entre las diferentes herramientas. SugarCRM por suerte, consta con una implementación de una API nativa, que nos permite recuperar información e incluso insertar una nueva dentro del mismo CRM. De tal forma que permite la integración de otras herramientas mediante este sistema.

Para poder lograr la comunicación necesitaremos haber efectuado una autenticación previa contra la API de SugarCRM.

¿Dónde puedo encontrar la API en mi SugarCRM?

Todo sistema SugarCRM ya viene con la API implementada. Lo bueno es que no hay que hacer ningún paso previo para poder utilizarla. Supongamos que nuestro sistema SugarCRM está ubicado en la siguiente dirección: https://sugarcrm.miempresa.com

Partiendo de nuestra dirección de acceso al CRM, podremos ver todos los endpoints disponibles para utilizar accediendo al siguiente enlace: https://sugarcrm.miempresa.com/rest/<version>/help

El parámetro <versión> variará en función de la versión de SugarCRM que se esté utilizando. En el siguiente enlace, podréis ver un listado de las versiones de API en función de la versión de SugarCRM: https://support.sugarcrm.com/Documentation/Sugar_Developer/Sugar_Developer_Guide_10.0/Integration/Web_Services/#Versioning

Autenticación API SugarCRM

Una vez localizada la ruta de la API en nuestro SugarCRM, solo necesitaremos disponer de nuestro usuario y contraseña de la aplicación para comenzar a obtener datos mediante la misma.

Lo primero de todo, es obtener un Token de acceso que nos permitirá poder extraer los datos o introducir nuevos, ya que, si no estamos autenticados, por seguridad, SugarCRM no nos dejará hacer nada. En caso contrario, cualquiera con acceso a la ruta del CRM, podría insertar datos no deseados.

Para efectuar la autenticación, utilizaremos el endpoint /oauth2/token que nos retornará el token de acceso para poder seguir operando con la API.

Endpoint: POST /oauth2/token

Parámetros de entrada:

Nombre Tipo Descripción Requerido
grant_type String Tipo petición. Puede ser “password” o “refresh_token” Si
client_id String Parámetro que identifica el cliente. Por defecto, su valor será “sugar” Si
client_secret String La clave “secret” del cliente informado en client_id Si
username String Nombre de usuario de SugarCRM Si
password String Password del usuario de SugarCRM Si
platform String Plataforma. Usaremos “base” Si

Ejemplo de la petición en JSON:

{   «grant_type»:»password»,   «client_id»:»sugar»,   «client_secret»:»»,   «username»:»admin»,   «password»:»password»,   «platform»:»base»}

Parámetros de retorno:

Nombre Tipo Descripción
access_token String El Token de acceso para el resto de endpoints.
expires_in Integer El tiempo en el que expirará el Access Token
token_type String El tipo de Token que es. Por el momento, bearer
refresh_token String El Token de refresco
refresh_expires_in Integer El tiempo de expiración del token de refresco
download_token String El Token para descargar Imágenes y Ficheros

Ejemplo de retorno en JSON:

{

«access_token»:»802b64c0-5eac-8431-a541-5342d38ac527″,

«expires_in»:3600,

«token_type»:»bearer»,

«scope»:null,

«refresh_token»:»85053198-24b1-4521-b1a1-5342d382e0b7″,

«refresh_expires_in»:1209600,

«download_token»:»8c9b5461-0d95-8d87-6084-5342d357b39e»

}

Una vez tenemos nuestro access_token, tras llamar al endpoint correspondiente, podremos efectuar el resto de llamadas añadiendo en cada petición, la cabecera siguiente:

Authorization: Bearer <access_token>

En lugar de mandar la cabecera, Authorization, también podemos enviar la cabecera OAuth-Token:

OAuth-Token: <access_token>

Gestión de registros mediante API

Ahora que ya disponemos de nuestra clave de acceso, podemos comenzar a operar con nuestros registros dentro del sistema, permitiéndonos crear nuevos registros, actualizarlos hasta efectuar filtros sobre los módulos.

Creación de una nueva Cuenta

Endpoint: POST /Accounts

Lo primero que haremos será, crear una nueva Cuenta en nuestro sistema SugarCRM.

Para ello, SugarCRM nos habilita el endpoint dinámico /<module>, que nos permite la generación de cualquier entidad que tengamos en nuestro CRM.

Para este ejemplo, lanzaremos una petición POST al endpoint /Accounts, con el siguiente JSON:

URL completa: http://sugarcrm.miempresa.com/rest/v11_5/Accounts

JSON de ejemplo:

Efectuada la llamada, SugarCRM nos retornará un nuevo JSON con los datos generados en el sistema. Además, nos informará del ID que se le ha otorgado al nuevo registro, y que podremos utilizar ya sea para registrarlo en el sistema externo, o para seguir trabajando con él.

Modificación de una nueva Cuenta

Endpoint: PUT /Accounts/<id>

Otra de las opciones que nos ofrece la API, es modificar registros existentes en el sistema, de manera que podemos mantener varios sistemas sincronizados sin interacción manual por parte del usuario. Para esto, utilizaremos el endpoint /<module>/<id>.

En este caso, supongamos que a la cuenta creada anteriormente, queremos modificarle el valor del teléfono, indicándole el prefijo del país.

URL Completa: http://sugarcrm.miempresa.com/rest/v11_5/Accounts/f573feb4-78b0-11ea-97c0-4a45ef745ccd

JSON de ejemplo:

En el caso de las actualizaciones, cabe reseñar que únicamente enviaremos los campos que necesitemos actualizar, de manera que agiliza la forma en la que actualizamos el registro, pues no nos obliga a conocer el resto de los datos del registro.

Tras efectuar la llamada, el sistema nos vuelve a retornar el JSON actualizado con todos los datos del registro:

Listado de Cuentas

Endpoint: GET /Accounts

Otra de las acciones que nos permite efectuar la API de SugarCRM, es la de obtener listados filtrados o no, de los diferentes módulos de la herramienta. Para ello, nos basta con hacer una petición al endpoint /<modulo> mediante GET.

En nuestro caso, procederemos a listar todas aquellas cuentas que comiencen por la palabra “Open”. Para ello, efectuaremos una búsqueda filtrada. Podréis conocer el resto de tipo de filtros, accediendo al siguiente enlace: https://support.sugarcrm.com/Documentation/Sugar_Developer/Sugar_Developer_Guide_10.0/Integration/Web_Services/REST_API/Endpoints/modulefilter_GET/index.html#Full

URL completa: http://sugarcrm.miempresa.com/rest/v11_5/Accounts

JSON de ejemplo:

 

En este caso, como vemos en el ejemplo, además del filtro, estamos limitando el número de registros devueltos a 3, y los campos retornados a los 3 siguientes:

  • id
  • name
  • phone_office

Esto es útil cuando no necesitamos disponer de toda la información, y únicamente necesitamos unos pocos campos para poder operar.

En este caso, el resultado sería:

Conclusiones

Como habréis podido apreciar, efectuar conexiones contra SugarCRM es ligeramente sencillo conociendo los mecanismos para ello. Además nos da un gran abanico de posibilidades para poder operar con aplicaciones de terceros.

Y como siempre, si tenéis más dudas al respecto, no dudéis en poneros en contacto con nosotros.