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 :

  1. Visitez cette page https://accounts.zoho.com/developerconsole.
  2. Cliquez sur « Add Client ID » (Ajouter un ID client).
  3. Entrez le nom du client, le domaine du client et l'URI de redirection.
  4. Pour le type de client, sélectionnez « Web based » (Basé sur le Web).
  5. Cliquez sur « Create » (Créer).
  6. Votre application cliente devrait désormais être créée et s'afficher.
  7. 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 :

  1. saveOAuthTokens(token_obj)
  2. updateOAuthTokens(token_obj)
    • Indépendamment de la réponse, l'exécution suivante se produit. L'utilisateur doit donc traiter son module avec soin.
  3. 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)

  1. Visiter https://accounts.zoho.com/developerconsole
  2. Cliquez sur Options → Self Client (Client auto) pour le client à autoriser.
  3. 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.
  4. Copiez le jeton d'autorisation à des fins de sauvegarde.

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

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