Node JS

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:

  1. Visite esta página https://accounts.zoho.com/developerconsole.
  2. Haga clic en "Agregar ID de cliente".
  3. Ingrese el nombre de cliente, el dominio de cliente y el URI de redireccionamiento.
  4. Seleccione el tipo de cliente como En la Web.
  5. Haga clic en "Crear".
  6. Su aplicación del lado del cliente se debería haber creado y mostrado.
  7. 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:

  1. saveOAuthTokens(token_obj)
  2. 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.
  3. 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)

  1. Visite https://accounts.zoho.com/developerconsole
  2. Haga clic en la opción Opciones → Self Client del cliente que desea autorizar.
  3. 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.
  4. Copie el token de concesión para realizar una copia de seguridad.
  5. 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

  6. 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.

Share this post : FacebookTwitter

Todavía no puede encontrar lo que está buscando?

Escríbenos: support@zohocrm.com