SDK de Node JS para Zoho CRM
Índice
El SDK de Node es un envoltorio para las API de Zoho CRM. En consecuencia, la invocación de una API de Zoho CRM desde la aplicación de Node es solo una llamada a una función que proporcione la respuesta más adecuada.
Este SDK permite la autenticación de un solo usuario y de usuarios múltiples.
Registrar un cliente de Zoho
Como las API de Zoho CRM se autentican con los estándares OAuth2, deberá registrar la aplicación del lado del cliente en Zoho. Para registrar su aplicación:
- Visite esta página https://accounts.zoho.com/developerconsole.
- Haga clic en "Agregar ID de cliente".
- Ingrese el nombre de cliente, el dominio de cliente y el URI de redireccionamiento.
- Seleccione el tipo de cliente como En la Web.
- Haga clic en "Crear".
- Su aplicación del lado del cliente se debería haber creado y mostrado.
- Los ID de cliente y Cliente secreto de la aplicación recién registrados se pueden encontrar haciendo clic en Opciones → Editar.
(Opciones es el ícono de tres puntos en la esquina derecha).
Instalación del SDK de Node para CRM
El SDK de Node JS se instalará y se creará un paquete denominado "zcrmsdk" en el equipo local.
El paquete se puede agregar mediante el siguiente código:
var ZCRMRestClient = require('zcrmsdk')
Instalar el SDK
Para instalar el SDK de Node JS debe hacer lo siguiente:
- Ejecute este comando:
npm install zcrmsdk
Otro método para instalar el SDK es agregarlo en las dependencias del package.json del servidor de Node con la última versión (recomendado) y ejecutar npm install en el directorio, lo que instalará todas las dependencias mencionadas en package.json.
Actualizar el SDK
- Ejecute este comando para actualizar el SDK de Node JS a la última versión.
npm install --upgrade zcrmsdk
Configuraciones
Debe brindar al SDK los detalles de su cliente de OAuth como un archivo de propiedades. En el SDK, deberá configurar un archivo llamado oauth_configuration.properties. Coloque los valores respectivos en dicho archivo. Puede colocar el archivo en la carpeta Recursos desde donde se utiliza el SDK.
Ingrese los valores solo para las siguientes claves.
Según su dominio (EU,CN), cambie el valor de crm.iamurl. Valor predeterminado establecido como dominio estadounidense.
En el archivo oauth_configuration.properties:
[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=
- crm.clientid, crm.clientsecret y crm.redirecturl son las configuraciones del cliente de OAuth que obtendrá después de registrar su cliente de Zoho.
- crm.iamurl es la dirección URL de las cuentas. Puede ser accounts.zoho.com o accounts.zoho.eu. Si no se especifica la crm.iamurl, de forma predeterminada la dirección URL será accounts.zoho.com.
En el archivo configuration.properties:
[crm]
api.url=
api.user_identifier=
api.tokenmanagement=
[mysql]
username=
password=
- api.url es la dirección URL utilizada para enviar solicitudes a las API. De forma predeterminada, la dirección URL es www.zohoapis.com.
- api.user_identifier estará vacío de forma predeterminada. Para la autenticación de usuario único, se puede llenar esta clave con el respectivo ID de correo electrónico, de manera que todas las solicitudes se realicen mediante el uso de la autenticación de este usuario.
- api.tokenmanagement se proporciona como una medida para administrar y mantener tokens. Si no se proporciona tokenmanagement, se seguirá la implementación predeterminada del SDK (MySQL).
- Aquí se puede indicar username y password si ya los creó para su MySQL.
Las claves mencionadas anteriormente en el archivo configuration.properties son todas opcionales.
Mecanismo de almacenamiento de token
Para utilizar el almacenamiento predeterminado de token proporcionado por el SDK, debe hacer lo siguiente:
MySQL debe ejecutarse en el puerto predeterminado en localhost.
Se debe crear una base de datos con el nombre zohooauth y se debe presentar en la base de datos una tabla con la configuración que aparece a continuación: La tabla debe llamarse "oauthtokens" y debe tener las columnas "useridentifier" (varchar) "accesstoken" (varchar), "refreshtoken" (varchar) y "expirytime" (bigint).
Una vez que la configuración se haya establecido, SDK manejará el almacenamiento y la recuperación de los tokens.
Si el usuario quiere utilizar su propio mecanismo, puede mencionarlo en configuration.properties proporcionando el módulo respectivo en api.tokenmanagement.
Este módulo debe contener los siguientes métodos:
- saveOAuthTokens(token_obj)
- updateOAuthTokens(token_obj)
- Independientemente de la respuesta, se producirá la siguiente ejecución. Por eso, el usuario debe tener cuidado durante el manejo de su módulo.
- getOAuthTokens()
- La respuesta esperada para este método: un arreglo JSON que contenga la respuesta JSON con los campos expirytime, refreshtoken y accesstoken.
Nota:
- Todos los métodos deben devolver la promesa.
Se llamará a saveOAuthtoken y updateOAuthTokens con los parámetros de JSON, los que contendrán los siguientes campos:
access_token
refresh_token
expires_in
Ejemplo de código para la gestión de tokens personalizados getOAuthTokens()
tokenmanagement.getOAuthTokens = function(user_identifier){ //vence en : 1527839622728
return new Promise(function(resolve,reject){
var result = {};
result.accesstoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
result.expirytime = 15278396227289
result.refreshtoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
var result_array =[];
result_array.push(result);
resolve(result_array);
});
}
Inicialización
Cuando la aplicación se inicia, se solicita la inicialización del siguiente fragmento de código.
var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//haga lo que sea necesario después de la inicialización
})
Generar tokens de actualización y concesión que no requieren autorización
Para aplicaciones cliente autónomo, la propia concesión autorizada token debe generarse desde la consola de desarrollador Zoho (https://accounts.zoho.com/developerconsole)
- Visite https://accounts.zoho.com/developerconsole
- Haga clic en la opción Opciones → Self Client del cliente que desea autorizar.
- Ingrese uno o más de los alcances de Zoho CRM válidos (separados por comas) que desea autorizar en el campo "Alcance" y elija la fecha de vencimiento. Indique el alcance “aaaserver.profile.READ” junto con los alcances de Zoho CRM.
- Copie el token de concesión para realizar una copia de seguridad.
- Genere un refresh_token a partir del token de concesión haciendo una petición POST con la dirección URL que se menciona a continuación
https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code
- Copie el token de actualización para realizar una copia de seguridad.
El token de concesión generado solo es válido durante el período estipulado que escogió cuando lo generó. Por lo tanto, los tokens de acceso y actualización se deben generar dentro de ese período.
Cada vez que se reinicia el servidor, se debe llamar esta función; ambos archivos de configuración se deben llenar con los valores correctos antes de llamarla, de lo contrario, se producirá una excepción.
Todas las funciones devuelven promesas en el sdk de node para zcrm.
Obtener los tokens de acceso y actualización a partir del token de concesión mediante llamadas al método
ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
Se generan los tokens de acceso y actualización. En el caso de que el token de acceso haya vencido, el SDK lo actualizará automáticamente.
Si el usuario tiene un token de actualización y necesita generar un token de acceso, puede utilizar la función que se menciona a continuación:
ZCRMRestClient.generateAuthTokenfromRefreshToken(user_identifier,refresh_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
Ejemplo de solicitud de la API para obtener clientes potenciales:
var input ={};
input.module = "Leads";
var params = {};
params.page = 0;
params.per_page = 5;
input.params = params;
zcrmsdk.API.MODULES.get(input).then(function(response){
var result = "<html><body><b>Leads</b>";
var data = response.body;
data = JSON.parse(data);
data = data.data;
for (i in data){
var record = data[i];
var name = record.Full_Name;
result+="<span>"+name+"</span>";
}
result+="</body></html>";
})
Jerarquía
zcrmsdk
API
ORG
get
MÓDULOS
get
post
put
delete
getAllDeletedRecords
getRecycleBinRecords
getPermanentlyDeletedRecords
search
AJUSTES
getFields
getLayouts
getCustomViews
updateCustomViews
getModules
getRoles
getProfiles
getRelatedLists
ACCIONES
convert
USUARIOS
get
DOCUMENTOS ADJUNTOS
uploadFile
deleteFile
downloadFile
uploadLink
uploadPhoto
downloadPhoto
deletePhoto
FUNCIONES
executeFunctionsInGet
executeFunctionsInPost
Como figura en la jerarquía, el módulo de entidad zcrmsdk tiene variables que sirven para capturar sus propiedades y las de otros módulos.
Por ejemplo, para llamar a una API con el fin de obtener los datos del módulo, la solicitud debe ser zcrmsdk.API.MODULES.{operation_type}. Los tipos de operación pueden ser GET, POST, PUT, DELETE o CREATE.
Administración de respuestas
Todas las llamadas de la API darán la respuesta dada por las API de Zoho, excepto la descarga de archivos.
Para descargar archivos, la respuesta contendrá un campo adicional de filename.
Administración de errores:
Todos los errores se generarán de forma explícita y se debe tener cuidado en identificarlos.