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.
Deja tu comentario