Le SDK Python pour Zoho CRM fournit des wrappers pour les API Zoho CRM. Donc, invoquer une API Zoho CRM à partir de votre application Python cliente n'est qu'un appel de méthode.

Le SDK Python 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 Python peut être installé par le biais de « Pip ». Pip est un outil de gestion des dépendances dans Python. Le SDK attend ce qui suit de l'application cliente

• L'application cliente doit disposer de Python 2.7 et version supérieure.
  • https://www.python.org/downloads/
• L'application cliente a besoin que des demandes Python soient installées
  • http://docs.python-requests.org/en/master/user/install/
• Le SDK Python doit être installé par le biais de Pip.
• La méthode ZCRMRestClient.initialize() doit être appelée au démarrage de votre application
• MySQL doit s'exécuter sur la machine en service 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 « user identifier » (varchar(100)), « accesstoken » (varchar(100)), « refreshtoken » (varchar(100)), « expirytime » (bigint).

Si token_persistence_path est fourni dans le fichier oauth_configuration.properties, la persistance n'a lieu que dans le fichier. Dans ce cas, MySQL est inutile.

Créez un fichier vide appelé

zcrm_oauthtokens.pkl dans le token_persistence_path mentionné.

Installation du SDK à l'aide de Pip

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

Veuillez consulter le document ci-dessous pour installer Pip

Installer le SDK

Voici comment installer le SDK Python

• Exécutez la commande ci-dessous :

  pip install zcrmsdk

Le SDK Python sera installé et un package nommé « zcrmsdk » sera créé dans le répertoire d'installation de Python ( par exemple, '/Library/Python/2.7/site-packages').

Mettre à niveau le SDK

• Exécutez cette commande pour mettre à niveau le SDK Python vers la version la plus récente.

  pip 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, nous avons placé un fichier de configuration (oauth_configuration.properties). Veuillez placer les valeurs respectives dans ce fichier. Ce fichier est disponible sous « zcrmsdk/resources ».

Veuillez remplir les valeurs pour les seules 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.

• 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 Python pour le moment.
• 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.

Incluez le chemin d'accès absolu dans configuration.properties pour la clé « applicationLogFilePath » afin de stocker les journaux. Ce fichier est disponible sous « zcrmsdk/resources ». Ce fichier sert à consigner les exceptions lors de l'utilisation du SDK Python.

Veuillez indiquer la valeur pour la clé suivante uniquement. Si le chemin d'accès aux journaux n'est pas fourni, les journaux ne seront pas stockés, mais vous pourrez les voir dans la console

Pour effectuer des appels d'API au compte Sandbox, veuillez modifier la valeur de clé suivante en true. 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 le fil actuel en tant qu'attribut.

Vous pouvez également utiliser celui présenté ci-dessus pour l'authentification d'un utilisateur unique, mais il est conseillé de définir l'identifiant de messagerie dans le fichier configuration.properties.

Si vous ne configurez pas l'e-mail de l'utilisateur dans le fil actuel, 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 Python 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 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.

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 des jetons 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 un jeton d'accès.

Veuillez coller le jeton d'autorisation généré dans le littéral de chaîne mentionné. Ce processus est uniquement ponctuel.

Générer des jetons 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 un jeton d'accès.

Veuillez coller le jeton d'actualisation généré dans le littéral de chaîne mentionné. Ce processus est uniquement ponctuel.

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.

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 Python 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 Python 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 aura été initialisé par la ligne ci-dessus, vous pourrez utiliser n'importe quelle API du SDK pour obtenir des résultats corrects.

Utilisation du SDK

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

Vous pouvez ainsi accéder à toutes les fonctionnalités du SDK Python.

Hiérarchie des classes

Toutes les entités Zoho CRM sont modélisées sous forme de modules comportant des classes, méthodes et variables d'instance applicables à cette entité particulière. ZCRMRestClient est la classe de base du SDK Python. ZCRMRestClient a des méthodes pour obtenir des instances de diverses autres entités Zoho CRM. Elles sont dans le module RestClient.

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 :

Telles qu'elles apparaissent dans la hiérarchie, toutes les classes d'entités ont des méthodes pour récupérer leurs propres propriétés et pour récupérer les données de leurs entités enfant immédiates par le biais d'un appel d'API.

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

Instancier l'object

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 méthode get_instance() pour obtenir son propre objet factice, ainsi que des variables d'instance pour obtenir les objets factices de ses entités enfant.

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

En résumé,

• ZCRMRestClient.get_module(“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.get_module_instance(“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, vous n'avez pas besoin de commencer à partir de ZCRMRestClient. Au lieu de cela, vous pouvez obtenir une instance de ZCRMModule avec ZCRMModule.get_instance(), puis invoquer sa méthode get_records() non statique à 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, nous avons seulement donné les champs communs comme created_time, created_by, owner (propriétaire), etc., comme propriétés par défaut de ZCRMRecord. Toutes les autres propriétés d'un enregistrement sont disponibles sous forme de dictionnaire dans l'objet ZCRMRecord.

Pour accéder aux valeurs des champs individuels d'un enregistrement, utilisez les méthodes get et set disponibles. Les clés du dictionnaire des propriétés de l'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 → Extensions & APIs → APIs → CRM API → API Names. (Configuration → Extensions et API → API → API CRM → Noms d'API).

Pour obtenir une valeur de champ, utilisez record.get_field_value(field_api_name). Pour définir une valeur de champ, utilisez record.set_field_value(field_api_name,new_value). Lorsque vous définissez une valeur de champ, veillez à ce que la valeur définie corresponde au type de données du champ pour lequel vous allez la définir.

Gestion des réponses

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

DownloadFile et downloadPhoto renvoient FileAPIResponse au lieu d'APIResponse.

Une méthode recherchant une entité unique renvoie l'objet APIResponse, alors qu'une liste d'entités recherchant une méthode renvoie l'objet BulkAPIResponse.

Utilisez la variable d'instance « data » pour obtenir uniquement les données d'entité à partir d'objets de wrapper de réponse. APIResponse.data renvoie un objet d'entité Zoho CRM unique, alors que BulkAPIResponse.data 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. response_headers - 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. Info - toute autre information, si elle est fournie par l'API, en plus des données réelles.
3. bulk_entity_response (liste des instances EntityResponse) - 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 Python 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.

Classes et leurs variables d'instance

Nom du module	Nom de la classe	Variables d'instance	Méthodes
RestClient	ZCRMRestClient		get_instance() initialize() get_all_modules() get_module(module_api_name) get_organization_instance() get_module_instance(module_api_name) get_record_instance(module_api_name,entity_id) get_current_user() get_organization_details()
Org	ZCRMOrganization	org_id alias primary_zuid zgid primary_email website mobile phone employee_count description time_zone iso_code currency_locale currency_symbol street state city country zip_code country_code fax mc_status is_gapps_enabled paid_expiry trial_type trial_expiry is_paid_account paid_type	get_instance(org_name=None,org_id=None) get_user(self,user_id) get_current_user() get_all_users() get_all_active_users() get_all_deactive_users() get_all_confirmed_users() get_all_not_confirmed_users() get_all_deleted_users() get_all_active_confirmed_users() get_all_admin_users() get_all_active_confirmed_admin_users() get_all_profiles() get_profile(profile_id) get_all_roles() get_role(role_id) create_user(user_instance) update_user(user_instance) delete_user(user_id)
Opérations	ZCRMModule	api_name is_convertable is_creatable is_editable is_deletable web_link singular_label plural_label modified_by modified_time is_viewable is_api_supported is_custom_module is_scoring_suppored id module_name business_card_field_limit business_card_fields profiles display_field_name display_field_id related_lists layouts fields related_list_properties properties per_page search_layout_fields default_territory_name default_territory_id default_custom_view_id default_custom_view is_global_search_supported sequence_number	get_instance(module_apiname) get_record(entityID) get_records(cvid= None,sort_by=None,sort_order=None,page=0,per_page=200) create_records(record_ins_list) upsert_records(record_ins_list) update_records(entityid_list,field_api_name,value) delete_records(entityid_list) get_all_deleted_records() get_recyclebin_records() get_permanently_ deleted_records() search_records(search_word,page=0,per_page=200) get_all_fields() get_field(field_id) get_all_layouts() get_layout(layout_ id) get_all_customviews() get_customview(customview_id) get_all_relatedlists () get_relatedlist(relatedlist_id) update_module_settings() update_customview(customview_instance)
	ZCRMRecord	module_api_name entity_id line_items lookup_label owner created_by modified_by created_time modified_time field_data properties participants price_details layout tax_list last_activity_time	get_instance(module_apiname,entity_id=None) set_field_value(key,value) get_field_value(key) add_line_item(line_item) get() create() update() delete() convert(potential_record=None,assign_to_user=None) upload_attachment(file_path) upload_link_as_attachment(link_url) download_attachment(attachment_id) delete_attachment(attachment_id) upload_photo(file_path) download_photo() delete_photo() add_relation(junction_record) remove_relation(junction_record) add_note(note_ins) update_note(note_ins) delete_note(note_ins) get_notes(sort_by=None,sort_order=None,page=1,per_page=20) get_attachments(page=1,per_page=20) get_relatedlist_records(relatedlist_api_name,sort_by=None,sort_order=None,page=1,per_page=20)
	ZCRMInventoryLineItem	product id list_price quantity description total discount discount_percentage total_after_discount tax_amount net_total delete_flag line_tax	get_instance(zcrm_record_instance)
	ZCRMTax	name percentage value	get_instance(name)
	ZCRMEventParticipant	id type email name is_invited status	get_instance(participant_type,participant_id)
	ZCRMPriceBookPricing	id to_range from_range discount	get_instance(price_book_id)
	ZCRMUser	id name signature country role customize_info city name_format language locale is_personal_account default_tab_group street alias theme state country_locale fax first_name email zip decimal_separator website time_format profile mobile last_name time_zone zuid is_confirm full_name phone dob date_format status	get_instance(user_id=None,name=None)
	ZCRMUserCustomizeInfo	notes_desc is_to_show_right_panel is_bc_view is_to_show_home is_to_show_detail_view unpin_recent_item	get_instance()
	ZCRMUserTheme	normal_tab_font_color normal_tab_background selected_tab_font_color selected_tab_background	get_instance()
	ZCRMRole	name id reporting_to label is_admin	get_instance(role_id,role_name=None)
	ZCRMLayout	id name created_time modified_time is_visible modified_by accessible_profiles created_by sections status convert_mapping	get_instance(layout_id)
	ZCRMAttachment	id parent_record file_name file_type size owner created_by created_time modified_by modified_time parent_module attachment_type parent_name parent_id	get_instance(parent_record,attachment_id=None)
	ZCRMCustomView	id module_api_name display_value is_default name system_name sort_by category fields favorite sort_order criteria_pattern criteria categories is_off_line	get_instance(custom_view_id,module_apiname=None)
	ZCRMCustomViewCategory	display_value actual_value	get_instance()
	ZCRMCustomViewCriteria	comparator field value	get_instance()
	ZCRMField	api_name is_custom_field lookup_field convert_mapping is_visible field_label length created_source default_value is_mandatory sequence_number is_read_only is_unique_field is_case_sensitive data_type is_formula_field is_currency_field id picklist_values is_auto_number is_business_card_supported field_layout_permissions decimal_place precision rounding_option formula_return_type formula_expression prefix suffix start_number json_type	get_instance(api_name)
	ZCRMJunctionRecord	id api_name related_data=dict()	get_instance(api_name,record_id) set_related_data(key,value) get_related_data()
	ZCRMLeadConvertMapping	id name fields	get_instance(name ,converted_id)
	ZCRMLeadConvertMappingField	id api_name field_label is_required	get_instance(api_name,field_id)
	ZCRMLookupField	api_name display_label module id	get_instance(api_name)
	ZCRMModuleRelatedList	api_name module display_label is_visible name id href type	get_instance(api_name)
	ZCRMModuleRelation	parent_record parent_module_api_name junction_record api_name label id is_visible	get_instance(parentmodule_apiname_or_parentrecord,related_list_apiname_or_junction_record) get_records(sort_by_field=None,sort_order=None,page=1,per_page=20) upload_attachment(file_path) upload_link_as_attachment(link_url) download_attachment(attachment_id) delete_attachment(attachment_id) add_relation() remove_relation() add_note(zcrm_note_ins) update_note(zcrm_note_ins) delete_note(zcrm_note_ins) get_notes(sort_by,sort_order,page,per_page) get_attachments(page,per_page)
	ZCRMNote	id parent_record title content owner created_by created_time modified_by modified_time attachments size is_voice_note parent_module parent_name parent_id	get_instance(parent_record,note_id=None)
	ZCRMPermission	id name display_label module is_enabled	get_instance(permission_name,permission_id)
	ZCRMPickListValue	display_value sequence_number actual_value maps	get_instance()
	ZCRMProfile	name id is_default created_time modified_time modified_by description created_by category permissions sections	get_instance(profile_id,profile_name=None)
	ZCRMProfileCategory	name module display_label permission_ids	get_instance(profile_category_name)
	ZCRMProfileSection	name categories	get_instance(section_name)
	ZCRMRelatedListProperties	sort_by sort_order fields	get_instance()
	ZCRMSection	name display_name column_count sequence_number fields	get_instance(section_name)
	ZCRMTrashRecord	id type display_name deleted_time created_by deleted_by	get_instance(entity_type,entity_id=None)
Réponse	APIResponse	response_json response_headers status_code data status code message details
	BulkApiRepsponse	response_json response_headers status_code data info(ResponseInfo instance) bulk_entity_response(EntityResponse instances as list) status code message details
	EntityRepsponse	data status code message details upsert_action upsert_duplicate_field
	RepsponseInfo	is_more_records page per_page count
	FileApiRepsponse	response status_code file_name response_headers status code message details
CLException	ZCRMException	url status_code error_content error_message error_code error_details