SDK Node JS pour Zoho CRM
Table des matières
Le SDK Node est un wrapper pour les API Zoho CRM. Donc, l'invocation d'une API Zoho CRM à partir de votre application Node est juste un appel de fonction qui fournit la réponse la plus appropriée.
Ce SDK prend en charge l'authentification d'un utilisateur unique et celle de plusieurs utilisateurs.
Enregistrement d'un client Zoho
Étant donné que les API Zoho CRM sont authentifiées par des normes OAuth2, vous devriez enregistrer votre application cliente auprès de Zoho. Pour enregistrer votre application :
- Visitez cette page https://accounts.zoho.com/developerconsole.
- Cliquez sur « Add Client ID » (Ajouter un ID client).
- Entrez le nom du client, le domaine du client et l'URI de redirection.
- Pour le type de client, sélectionnez « Web based » (Basé sur le Web).
- Cliquez sur « Create » (Créer).
- Votre application cliente devrait désormais être créée et s'afficher.
- L'ID client et la clé secrète client de l'application nouvellement enregistrée sont accessibles en cliquant sur Options → Edit (Options → Modifier).
(Les options sont représentées par l'icône des points de suspension dans le coin droit).
Installation du SDK Node CRM
Le SDK Node JS sera installé et un package nommé « crmsdk » sera créé sur la machine locale.
Le package peut être ajouté à l'aide du code suivant :
var ZCRMRestClient = require('zcrmsdk')
Installation du SDK
Voici comment installer le SDK Node JS
Exécutez la commande ci-dessous :
npm install zcrmsdk
Une autre méthode pour installer le SDK consiste à l'ajouter aux dépendances du package.json du serveur de nœuds avec la dernière version (recommandée) et à exécuter npm install dans le répertoire qui installe toutes les dépendances mentionnées dans package.json.
Mettre à niveau le SDK
Exécutez cette commande pour mettre à niveau le SDK Node JS vers la version la plus récente.
npm install --upgrade zcrmsdk
Configurations
Les détails de votre client OAuth doivent être fournis au SDK en tant que fichier de propriétés. Dans le SDK, vous devez configurer un fichier nommé oauth_configuration.properties. Veuillez placer les valeurs respectives dans ce fichier. Vous pouvez le placer sous le dossier resources à partir duquel le SDK est utilisé.
Veuillez remplir les valeurs pour les seules clés suivantes.
En fonction de votre domaine (EU,CN), modifiez la valeur de crm.iamurl. La valeur par défaut est un domaine US.
Dans le fichier oauth_configuration.properties :
[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=
- crm.clientid, crm.clientsecret et crm.redirecturl sont les configurations de votre client OAuth que vous obtenez après avoir enregistré votre client Zoho.
- crm.iamurl est l'URL des comptes. Il peut s'agir de accounts.zoho.com ou de accounts.zoho.eu. Si crm.iamurl n'est pas spécifié, par défaut, l'URL sera accounts.zoho.com.
Dans le fichier configuration.properties :
[crm]
api.url=
api.user_identifier=
api.tokenmanagement=
[mysql]
username=
password=
- api.url est l'URL utilisée pour appeler les API. Par défaut, l'URL est www.zohoapis.com.
- Par défaut,
- api.user_identifier est vide. Pour l'authentification d'un utilisateur unique, cette clé peut être renseignée avec l'ID de messagerie correspondant afin que tous les appels s'effectuent à l'aide de cette authentification d'utilisateur.
- api.tokenmanagement est fourni en tant que mesure pour gérer et entretenir les jetons. Si tokenmanagement n'est pas fourni, la mise en œuvre par défaut du SDK (MySQL) sera suivie.
- Le
- nom d'utilisateur et le mot de passe peuvent être fournis ici si vous en avez déjà créés pour votre MySQL.
Les clés ci-dessus, spécifiées dans le fichier configuration.properties, sont toutes facultatives.
Mécanisme de stockage des jetons
Pour utiliser le stockage de jetons par défaut fourni par le SDK, les conditions suivantes doivent être respectées :
Mysql doit s'exécuter dans le port par défaut dans localhost.
Une base de données nommée zohooauth doit avoir été créée et contenir un tableau comportant les configurations ci-dessous. Le tableau « oauthtokens » doit comporter les colonnes « useridentifier » (varchar) « accesstoken » (varchar), « refreshtoken » (varchar) et « expirytime » (bigint).
Une fois la configuration définie, le stockage et la récupération des jetons seront traités par le SDK.
Si l'utilisateur veut utiliser son propre mécanisme, il peut l'indiquer dans configuration.properties en fournissant le module correspondant dans api.tokenmanagement.
Ce module devrait contenir les méthodes ci-dessous :
- saveOAuthTokens(token_obj)
- updateOAuthTokens(token_obj)
- Indépendamment de la réponse, l'exécution suivante se produit. L'utilisateur doit donc traiter son module avec soin.
- getOAuthTokens()
- Réponse attendue pour cette méthode : tableau JSON contenant la réponse json avec les champs expirytime, refreshtoken et accesstoken.
Remarque :
- Toutes les méthodes doivent renvoyer une promesse.
saveOAuthtoken & updateOAuthTokens sera appelé avec les paramètres JSON, lesquels contiennent les champs présentés ci-dessous,
access_token
refresh_token
expires_in
Exemple de code pour la gestion des jetons personnalisés getOAuthTokens()
tokenmanagement.getOAuthTokens = function(user_identifier){ //expire : 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);
});
}
Initialisation
Chaque fois que l'application démarre, l'extrait de code ci-dessous doit être appelé pour l'initialisation.
var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//faire le nécessaire après initialisation
})
Générer un jeton d'autorisation et d'actualisation auto-autorisé
Pour les applications clientes, le jeton d'autorisation auto-autorisé doit être généré à partir de Zoho Developer Console (https://accounts.zoho.com/developerconsole)
- Visiter https://accounts.zoho.com/developerconsole
- Cliquez sur Options → Self Client (Client auto) pour le client à autoriser.
- Entrez une ou plusieurs étendues (séparées par des virgules) Zoho CRM valides que vous souhaitez autoriser dans le champ « Scope » (Étendue) et choisissez l'heure d'expiration. Indiquez une étendue « aaaserver.profile.READ » avec les étendues Zoho CRM.
- Copiez le jeton d'autorisation à des fins de sauvegarde.
Générez refresh_token à partir du jeton d'autorisation en effectuant une demande POST à l'aide de l'URL ci-dessous
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
- Copiez le jeton d'actualisation à des fins de sauvegarde.
Veuillez noter que le jeton d'autorisation généré n'est valide que pendant le délai indiqué lors de sa création. Par conséquent, les jetons d'accès et d'actualisation doivent être générés dans ce délai.
Chaque fois que le serveur redémarre, cette fonction doit être appelée et les deux fichiers de configuration doivent être renseignés avec les valeurs appropriées avant d'appeler cette fonction, sinon une exception sera générée.
Toutes les fonctions renvoient des promesses dans zcrm node sdk.
Obtention de jetons d'accès et d'actualisation à partir de jetons d'autorisation à l'aide d'appels de méthode
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);
});
Les jetons d'accès et d'actualisation sont générés. Si le jeton d'accès a expiré, le SDK l'actualise automatiquement.
Si l'utilisateur dispose d'un jeton d'actualisation et doit générer un jeton d'accès, il peut utiliser la fonction ci-dessous,
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);
});
Exemple d'appel d'API pour obtenir des 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>";
})
Hiérarchie
zcrmsdk
API
ORG
get
MODULES
get
post
put
delete
getAllDeletedRecords
getRecycleBinRecords
getPermanentlyDeletedRecords
search
PARAMÈTRES
getFields
getLayouts
getCustomViews
updateCustomViews
getModules
getRoles
getProfiles
getRelatedLists
ACTIONS
convert
UTILISATEURS
get
PIÈCES JOINTES
uploadFile
deleteFile
downloadFile
uploadLink
uploadPhoto
downloadPhoto
deletePhoto
FONCTIONS
executeFunctionsInGet
executeFunctionsInPost
Tel qu'il apparaît dans la hiérarchie, le module d'entité zcrmsdk comporte des variables pour récupérer ses propres propriétés et celles d'autres modules.
Par exemple, pour appeler une API afin d'obtenir des données de module, la demande devrait être zcrmsdk.API.MODULES.{operation_type}. Les types d'opération peuvent être GET, POST, PUT, DELETE ou CREATE.
Gestion des réponses
Tous les appels d'API produiront la réponse d'API réelle donnée par les API Zoho, sauf le téléchargement de fichiers.
Pour le téléchargement d'un fichier, la réponse contiendra un champ supplémentaire de nom de fichier.
Gestion des erreurs :
Toutes les erreurs seront créées explicitement et il faut les examiner avec soin.