Le SDK PHP est un wrapper pour les API Zoho CRM. Donc, invoquer une API Zoho CRM à partir de votre application PHP cliente n'est qu'un appel de fonction. Il 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).

Configuration

Le SDK

PHP peut être installé par le biais de « Composer ». Composer est un outil de gestion des dépendances dans PHP. Le SDK attend les éléments suivants de l'application cliente.

• L'application cliente doit disposer de PHP 5.6 ou version supérieure avec l'extension curlactivée.
• Le SDK PHP doit être installé dans l'application cliente par le biais de Composer.
• La fonction ZCRMRestClient::initialize() doit être appelée au démarrage de l'application.
• MySQL doit s'exécuter sur la même machine servant au port par défaut 3306.
• Le nom de la base de données doit être « zohooauth ».
• Il doit y avoir un tableau « oauthtokens » comportant les colonnes « useridentifier »(varchar(100)), « accesstoken »(varchar(100)), « refreshtoken »(varchar(100)), « expirytime » (bigint).

Si token_persistence_path est fourni dans le fichier oauth_configuration.properties, la persistance est limitée au fichier. Dans ce cas, MySQL est inutile. Créez un fichier vide appelé zcrm_oauthtokens.txt dans le token_persistence_path mentionné.

Installation du SDK PHP par le biais de Composer

Installez Composer (s'il ne l'est pas déjà)

Exécutez cette commande pour installer l'outil Composer

Pour que Composer soit accessible globalement, suivez les instructions disponibles en suivant le lien ci-dessous

Installer le SDK PHP

Voici comment installer le SDK

1. Accédez à l'espace de travail de votre application cliente
2. Exécutez la commande ci-dessous :

   composer requiert zohocrm/php-sdk

3. Le SDK PHP sera donc installé et un package nommé « vendor » sera créé dans l'espace de travail de votre application cliente.

Configurations

Les détails de votre client OAuth doivent être fournis au SDK PHP en tant que fichier de propriétés. Nous avons placé un fichier de configuration (oauth_configuration.properties) dans le SDK PHP. Veuillez placer les valeurs respectives dans ce fichier. Vous trouverez ce fichier sous « vendor/zohocrm/php-sdk/src/resources ».

Veuillez remplir uniquement les clés suivantes. En fonction de votre domaine (EU, CN), modifiez la valeur de « accounts_url ». La valeur par défaut est un domaine US.

• Seules les clés affichées ci-dessus doivent être remplies.
• client_id, client_secret et redirect_uri sont les configurations du client OAuth que vous obtenez après avoir enregistré votre client Zoho.
• access_type doit être défini comme ayant la valeur offline (hors ligne) uniquement, car le client OAuth n'est pas pris en charge par le SDK PHP pour le moment.
• persistence_handler_class est la mise en œuvre de ZohoOAuthPersistenceInterface, c'est-à-dire ZohoOAuthPersistenceHandler.
• token_persistence_path est le chemin d'accès au stockage des jetons associés à OAuth dans le fichier. S'il est défini, la persistance ne requiert pas de base de données. La persistance intervient par le biais du fichier uniquement.

Créez un fichier nommé « ZCRMClientLibrary.log » dans la machine de votre application cliente et précisez le chemin d'accès absolu du fichier créé dans configuration.properties pour la clé « applicationLogFilePath ». Ce fichier est disponible sous « vendor/zohocrm/php-sdk/src/resources ». Ce fichier sert à consigner les exceptions survenant lors de l'utilisation du SDK PHP.

Veuillez remplir uniquement la clé suivante

Pour effectuer des appels d'API au compte Sandbox, veuillez modifier la valeur de clé suivante en true dans le fichier configurations.properties . La valeur par défaut est false.

Si votre application ne nécessite qu'une authentification pour utilisateur unique, vous devez définir l'identifiant de messagerie de l'utilisateur dans le fichier configurations.properties comme indiqué ci-dessous :

Pour utiliser l'authentification pour plusieurs utilisateurs, vous devez définir l'identifiant de messagerie des utilisateurs dans la super variable globale « $_SERVER » de PHP comme indiqué ci-dessous :

Vous pouvez également utiliser la variable $_SERVER pour l'authentification d'un utilisateur unique, mais il est recommandé de définir l'identifiant de messagerie dans le fichier configuration.properties.

Si vous ne configurez pas l'e-mail de l'utilisateur comme une super variable globale, le SDK s'attend à l'obtenir depuis le fichier configuration.properties. Si l'e-mail de l'utilisateur n'a pas l'une de ces deux configurations, le SDK PHP renvoie une exception.

Initialisation

L'application sera prête à être initialisée après la définition du fichier de configuration OAuth.

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

Générer un jeton d'accès

Il est possible de générer un jeton d'accès à l'aide d'un jeton d'autorisation ou d'un jeton d'actualisation. Il suffit de suivre l'une de ces deux méthodes.

Générer un jeton d'accès à partir d'un jeton d'autorisation

L'extrait de code suivant doit être exécuté à partir de votre classe principale pour obtenir des jetons d'accès et d'actualisation. Veuillez coller le jeton d'autorisation copié dans le littéral de chaîne mentionné ci-dessous. Il s'agit d'un processus ponctuel.

Veuillez noter que l'extrait de code ci-dessus est valable une seule fois par jeton d'autorisation. Quand l'exécution de l'extrait de code ci-dessus a réussi, les jetons d'accès et d'actualisation générés sont conservés dans notre classe de gestion de la persistance.

Générer un jeton d'accès à partir d'un jeton d'actualisation

L'extrait de code suivant doit être exécuté à partir de votre classe principale pour obtenir des jetons d'accès et d'actualisation. Veuillez coller le jeton d'actualisation généré dans le littéral de chaîne mentionné ci-dessous. Il s'agit d'un processus ponctuel.

Quand l'exécution de l'extrait de code ci-dessus a réussi, le jeton d'accès généré et le jeton d'actualisation donné sont conservés dans notre classe de gestion de la persistance.

Quand les jetons OAuth ont été conservés, les appels d'API suivants utilisent les jetons d'accès et d'actualisation conservés. Le SDK PHP va procéder à l'actualisation du jeton d'accès à l'aide d'un jeton d'actualisation, en fonction des exigences.

Démarrage de l'application

Le SDK PHP a besoin que la ligne de code suivante soit invoquée chaque fois que votre application cliente est démarrée.

Une fois que le SDK PHP aura été initialisé par la ligne ci-dessus, vous pourrez utiliser n'importe quelle API du SDK pour obtenir les résultats corrects.

Utilisation du SDK PHP

Ajoutez la ligne ci-dessous aux fichiers PHP de votre application cliente, là où vous voudriez utiliser le SDK PHP.

Cette ligne vous permet d'accéder à toutes les fonctionnalités du SDK PHP.

Hiérarchie des classes

Toutes les entités Zoho CRM reposent sur un modèle de classes comportant des propriétés et des fonctions applicables à cette entité en particulier. ZCRMRestClient est la classe de base du SDK PHP. ZCRMRestClient comporte des fonctions permettant d'obtenir des instances de diverses autres entités Zoho CRM.

Les relations de classe et la hiérarchie du SDK suivent la hiérarchie des entités dans Zoho CRM. La hiérarchie des classes des diverses entités Zoho CRM est présentée ci-dessous :

ZCRMRestClient
     -ZCRMOrganization
          -ZCRMUser
               -ZCRMUserTheme
               -ZCRMUserCustomizeInfo
         -ZCRMRole
         -ZCRMProfile
              -ZCRMPermission
              -ZCRMProfileSection
                   -ZCRMProfileCategory
        -ZCRMModule
             -ZCRMLayout
                  -ZCRMSection
                       -ZCRMField
                       -ZCRMPickListValue
                       -ZCRMLookupField
                  -ZCRMLeadConvertMapping
                       -ZCRMLeadConvertMappingField
             -ZCRMCustomView
                  -ZCRMCustomViewCategory
                  -ZCRMCustomViewCriteria
             -ZCRMRelatedListProperties
                  -ZCRMModuleRelatedList
             -ZCRMRecord
             -ZCRMNote
             -ZCRMAttachment
             -ZCRMInventoryLineItem
                  -ZCRMTax
             -ZCRMEventParticipant
             -ZCRMPriceBookPricing
             -ZCRMModuleRelation
             -ZCRMJunctionRecord
             -ZCRMTrashRecord

Chaque classe d'entités a des fonctions lui permettant de récupérer ses propres propriétés et de récupérer les données de ses entités enfants immédiates grâce à un appel d'API.

Par exemple : un objet de module Zoho CRM (ZCRMModule) comportera des fonctions de membre permettant d'obtenir les propriétés d'un module (comme le nom de l'affichage, l'ID du module, etc.), ainsi que des fonctions pour récupérer tous ses objets enfants (comme ZCRMLayout).

Objet d'instance

Il n'est pas toujours efficace de respecter l'ensemble de la hiérarchie des classes à partir du niveau supérieur pour récupérer les données d'une entité de niveau inférieur, cela impliquant des appels d'API à tous les niveaux. Pour gérer ce problème, chaque classe d'entité dispose d'une fonction getInstance() pour obtenir son propre objet factice, ainsi que de fonctions pour obtenir les objets factices de ses entités enfants.

Veuillez noter qu'aucune propriété n'est indiquée pour la fonction getInstance() car cela ne renvoie pas d'appel d'API, mais seulement un objet factice à utiliser uniquement pour accéder aux fonctions non statiques de la classe.

En résumé,

• ZCRMRestClient::getModule(“Contacts”) renvoie le module Contacts réel, dont toutes les propriétés sont renseignées par le biais d'un appel d'API.
• ZCRMRestClient::getModuleInstance(“Contacts”) renvoie un objet factice ZCRMModule faisant référence au module Contacts, sans aucune propriété renseignée, étant donné que cela ne génère pas d'appel d'API.

Par conséquent, pour obtenir des enregistrements d'un module, il n'est pas nécessaire de démarrer à partir de ZCRMRestClient. Au lieu de cela, vous pouvez obtenir une instance ZCRMModule avec ZCRMModule::getInstance(), puis invoquer sa fonction non statique getRecords() à partir de l'instance créée. Cela permettrait d'éviter l'appel d'API qui aurait été déclenché pour remplir l'objet ZCRMModule.

Accès aux propriétés d'un enregistrement

Étant donné que les propriétés d'enregistrement sont dynamiques entre les modules, seuls les champs tels que createdTime, createBy, owner (propriétaire), etc., sont donnés en tant que propriétés par défaut de ZCRMRecord. Toutes les autres propriétés d'enregistrement sont disponibles sous forme de carte dans l'objet ZCRMRecord.

Pour accéder aux valeurs de champs individuelles d'un enregistrement, utilisez les fonctions get et set disponibles. Les clés de la carte des propriétés d'enregistrement sont les noms d'API des champs du module. Tous les noms d'API des champs de tous les modules sont disponibles sous Setup → Marketplace → APIs → CRM API → API Names (Configuration → Marketplace → API → API CRM → Noms d'API).

• Pour obtenir une valeur de champ, utilisez $record → getFieldValue($fieldAPIName);
• Pour définir une valeur de champ, utilisez $record → setFieldValue($fieldAPIName, $newValue);
  Lorsque vous définissez une valeur de champ, veillez à ce que la valeur définie corresponde au type de données approprié du champ pour lequel vous allez la définir.

Gestion des réponses

APIResponse et BulkAPIResponse sont des wrappers pour les réponses d'API Zoho CRM. Toutes les fonctions d'appel d'API renvoient l'un de ces deux objets.

• DownloadFile et downloadPhoto renvoient FileAPIResponse au lieu d'APIResponse.
• Une fonction qui cherche une seule entité renvoie un objet APIResponse et une fonction qui recherche une liste d'entités renvoie un objet BulkAPIResponse.
• Utilisez la fonction getData() pour obtenir uniquement les données de l'entité à partir des wrappers de réponse. APIResponse → getData() renvoie un objet d'entité Zoho CRM unique, alors que BulkAPIResponse → getData() renvoie une liste d'objets d'entités Zoho CRM.

À part les données, ces objets de wrapper de réponse ont les propriétés suivantes :

1. ResponseHeaders - nombre d'API restantes pour le jour/la fenêtre actuel(e) et temps écoulé pour la réinitialisation de la fenêtre actuelle.
2. ResponseInfo - toute autre information, si elle est fournie par l'API, en plus des données réelles.
3. Array of EntityResponse(s) - statut des entités individuelles dans une API en bloc. Par exemple : une API d'insertion d'enregistrements peut partiellement échouer en raison de quelques enregistrements. Ce tableau donne le statut de création des enregistrements individuels.

Exceptions

Tous les comportements inattendus, comme des réponses d'API erronées ou des anomalies du SDK, sont gérés par le SDK PHP et sont regroupés dans une exception unique, à savoir ZCRMException. Cela suffit donc pour identifier cette exception seule dans le code de l'application cliente.