SDK Node JS para Zoho CRM
Sumário
SDK Node é um pacote para APIs do Zoho CRM. Portanto, a chamada de uma API do Zoho CRM do aplicativo Node é apenas uma chamada de função que fornece a resposta mais adequada.
Este SDK oferece suporte à autenticação de um único usuário e também de vários usuários.
Registro um cliente Zoho
Como as APIs do Zoho CRM são autenticadas com os padrões OAuth2, você deve registrar seu aplicativo cliente com o Zoho. Para registrar seu aplicativo:
- Visite esta página https://accounts.zoho.com/developerconsole.
- Clique em "Adicionar ID de Cliente".
- Insira o Nome do Cliente, o Domínio do Cliente e a URI de Redirecionamento.
- Selecione o Tipo de Cliente como "Baseado na Web".
- Clique em "Criar".
- Seu aplicativo será criado e exibido agora.
- O ID do Cliente e o Segredo do Cliente podem ser encontrados clicando em Opções → Editar.
(Opções é o ícone de reticências no canto direito).
Instalação do SDK Node CRM
O SDK Node JS será instalado, e um pacote com o nome "zcrmsdk" será criado na máquina local.
O pacote pode ser adicionado usando o seguinte código:
var ZCRMRestClient = require('zcrmsdk')
Instalação do SDK
Veja como instalar o SDK Node JS
- Execute o comando a seguir:
npm install zcrmsdk
Outro método para instalar o SDK é adicioná-lo em dependências ao package.json do servidor de nó com a versão mais recente (recomendado) e executar npm install no diretório que instala todas as dependências mencionadas em package.json.
Atualiza o SDK
- Execute este comando para atualizar o SDK Node JS para a versão mais recente.
npm install --upgrade zcrmsdk
Configurações
Os detalhes do Cliente OAuth devem ser fornecidos ao SDK como um arquivo de propriedade. No SDK, é necessário configurar um arquivo chamado oauth_configuration.properties. Insira os respectivos valores nesse arquivo. Você pode inseri-lo sob a pasta resources a partir da qual o SDK é usado.
Preencha os valores para as seguintes chaves sozinhas.
Com base em seu domínio (EU,CN), altere o valor de crm.iamurl. Valor padrão definido como domínio US.
No arquivo oauth_configuration.properties:
[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=
- crm.clientid, crm.clientsecret e crm.redirecturl são as configurações do cliente OAuth obtidas após o registro do cliente Zoho.
- crm.iamurl é o URL das contas. Pode ser accounts.zoho.com ou accounts.zoho.eu. Se o crm.iamurl não for especificado, por padrão, o URL será accounts.zoho.com.
No arquivo configuration.properties:
[crm]
api.url=
api.user_identifier=
api.tokenmanagement=
[mysql]
username=
password=
- api.url é o URL usado para chamar APIs. Por padrão, a URL é www.zohoapis.com.
- api.user_identifier estará vazio por padrão. Para autenticação de usuário único, esta chave pode ser preenchida com o ID de e-mail correspondente, de modo que todas as chamadas sejam feitas com o uso desta autenticação do usuário.
- api.tokenmanagement é fornecido como uma medida para gerenciar e manter tokens. Se tokenmanagement não for fornecido, default implementation(mysql) do SDK será seguido.
- username e password poderão ser fornecidos aqui se você já tiver criado um para seu MySQL.
As chaves especificadas acima no arquivo configuration.properties são todas opcionais.
Mecanismo de armazenamento de token
Para usar o armazenamento de token padrão fornecido pelo SDK, o seguinte deverá ser feito:
Mysql deve estar em execução na porta padrão em localhost.
O banco de dados com o nome zohooauth deve ser criado, e uma tabela com as configurações abaixo deve estar presente no banco de dados. A tabela com o nome "oauthtokens" deve ter as colunas "useridentifier" (varchar) "accesstoken" (varchar), "refreshtoken" (varchar) e "expirytime" (bigint).
Depois que a configuração for definida, o armazenamento e a recuperação de tokens serão tratados pelo SDK.
Se o usuário quiser utilizar o seu próprio mecanismo, ele poderá mencioná-lo em configuration.properties fornecendo o respectivo módulo em api.tokenmanagement.
Este módulo deve conter métodos a seguir,
- saveOAuthTokens(token_obj)
- updateOAuthTokens(token_obj)
- Independentemente de resposta, a próxima execução ocorre. Cuidados devem ser tomados pelo usuário no manuseio desse módulo.
- getOAuthTokens()
- A resposta esperada para este método: array JSON contendo a resposta json com os campos expirytime, refreshtoken e accesstoken.
Nota:
- Todos os métodos devem retornar promessa.
saveOAuthtoken & updateOAuthTokens serão chamados com parâmetros de JSON, que contêm os campos fornecidos abaixo,
access_token
refresh_token
expires_in
Código de exemplo para gerenciamento de token personalizado getOAuthTokens()
tokenmanagement.getOAuthTokens = function(user_identifier){ //expires in : 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);
});
}
Inicialização
Sempre que o aplicativo for iniciado, o trecho de código a seguir deverá ser chamado para inicialização.
var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//do whatever required after initialize
})
Geração de concessão autoautorizada e de token de atualização
Para aplicativos de autocliente, o token de concessão autoautorizada deve ser gerado no Zoho Developer Console (https://accounts.zoho.com/developerconsole)
- Visite https://accounts.zoho.com/developerconsole
- Clique em Opções → Autocliente do cliente o qual você deseja autorizar.
- Insira um ou mais escopos válidos do Zoho CRM (separados por vírgula) que deseja autorizar no campo "Escopo" e escolha a hora de expiração. Forneça o escopo "aaaserver.profile.READ" em conjunto com os escopos do Zoho CRM.
- Copie o token de concessão para backup.
- Gere refresh_token a partir do token de concessão criando uma solicitação POST com o URL abaixo
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 o token de atualização para backup.
Observe que o token de concessão gerado é válido apenas pelo tempo estipulado durante a geração. Portanto, os tokens de acesso e de atualização devem ser gerados durante esse período.
Cada vez que o servidor for reiniciado, esta função precisará ser chamado, e ambos os arquivos de configuração deverão ser preenchidos com os valores corretos antes de se chamar esta função, caso contrário, uma exceção será emitida.
Todas as funções retornam promessas em zcrm node sdk.
Obtenção de tokens de acesso e atualização a partir de token de concessão por meio de chamadas de método
ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("token de atualização :"+auth_response.refresh_token);
console.log("expira em :"+auth_response.expires_in);
});
Os tokens de acesso e atualização são gerados. Caso o token de acesso expire, o SDK o atualizará automaticamente.
Se o usuário tiver token de acesso e precisar gerá-lo, a função abaixo poderá ser usada,
ZCRMRestClient.generateAuthTokenfromRefreshToken(user_identifier,refresh_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("token de atualização :"+auth_response.refresh_token);
console.log("expira em :"+auth_response.expires_in);
});
Chamada de API de amostra para obter Leads:
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>";
})
Hierarquia
zcrmsdk
API
ORG
get
MODULES
get
post
put
delete
getAllDeletedRecords
getRecycleBinRecords
getPermanentlyDeletedRecords
search
SETTINGS
getFields
getLayouts
getCustomViews
updateCustomViews
getModules
getRoles
getProfiles
getRelatedLists
ACTIONS
convert
USERS
get
ATTACHMENTS
uploadFile
deleteFile
downloadFile
uploadLink
uploadPhoto
downloadPhoto
deletePhoto
FUNCTIONS
executeFunctionsInGet
executeFunctionsInPost
Conforme aparece na hierarquia, o módulo de entidade zcrmsdk tem variáveis para obter suas próprias propriedades e as de outros módulos.
Por exemplo, para chamar uma API para obter os dados do módulo, a solicitação deverá ser zcrmsdk.API.MODULES.{operation_type}. O tipos de operação podem ser GET, POST, PUT, DELETE ou CREATE.
Manipulação da resposta
Todas as chamadas de API darão a resposta de API real fornecida pelas APIs do Zoho, exceto download de arquivo.
Para download de arquivo, a resposta conterá um nome de arquivo de campo extra.
Manipulação de erros:
Todos os erros serão descartados explicitamente, e cuidados deverão ser tomados para detecção do mesmo.