El SDK de Python para las API de Zoho CRM les proporciona un envoltorio a estas. En consecuencia, la invocación de una API de Zoho CRM desde su aplicación Python del lado del cliente es solo la llamada de un método.

Este SDK permite la autenticación de un solo usuario y de usuarios múltiples.

Registrar un cliente de Zoho

Como las API de Zoho CRM se autentican con los estándares OAuth2, deberá registrar la aplicación del lado del cliente en Zoho. Para registrar su aplicación:

1. Visite esta página https://accounts.zoho.com/developerconsole.
2. Haga clic en "Agregar ID de cliente".
3. Ingrese el nombre de cliente, el dominio de cliente y el URI de redireccionamiento.
4. Seleccione el tipo de cliente como En la Web.
5. Haga clic en "Crear".
6. Su aplicación del lado del cliente se debería haber creado y mostrado.
7. Los ID de cliente y Cliente secreto de la aplicación recién registrados se pueden encontrar haciendo clic en Opciones → Editar.
   (Opciones es el ícono de tres puntos en la esquina derecha).

Configuración

El SDK de Python se puede instalar a través de “PIP”. PIP es una herramienta de administración de dependencias en Python. El SDK espera lo siguiente de la aplicación cliente

• La aplicación cliente debe tener Python 2.7 o superior.
  • https://www.python.org/downloads/
• La aplicación cliente debe tener instaladas las solicitudes Python
  • http://docs.python-requests.org/en/master/user/install/
• Se debe instalar el SDK de Python a través de PIP.
• Se debe llamar el método ZCRMRestClient.initialize() durante el inicio de su aplicación
• Se debe ejecutar MySQL en el mismo equipo que utiliza el puerto predeterminado 3306.
  • El nombre de la base de datos debe ser "zohooauth".
  • Debe haber una tabla “oauthtokens” con las columnas “user identifier”(varchar(100)), “accesstoken”(varchar(100)), “refreshtoken”(varchar(100)), “expirytime”(bigint).

Si se indica token_persistence_path en el archivo oauth_configuration.proporties, la persistencia solo se producirá en el archivo. En este caso, no es necesario MySQL.

Cree un archivo vacío con el nombre zcrm_oauthtokens.pkl en la mencionada ruta token_persistence_path.

Instalación del SDK a través de PIP

Instale PIP (si no está instalado)

Consulte el documento que aparece a continuación para instalar PIP

Instalar el SDK

Esta es la forma de instalar el SDK de Python

• Ejecute este comando:

  pip install zcrmsdk

Se instalará el SDK de Python y se creará un paquete denominado "zcrmsdk" en el directorio de instalación de Python (p. ej., "/Library/Python/2.7/site-packages").

Actualizar el SDK

• Ejecute este comando para actualizar el SDK de Python a la última versión:

  pip install --upgrade zcrmsdk

Configuraciones

Debe brindar al SDK los detalles de su cliente de OAuth como un archivo de propiedades. En el SDK, hemos colocado un archivo de configuración (oauth_configuration.properties). Coloque los valores respectivos en dicho archivo. Puede encontrar el archivo en "zcrmsdk/resources".

Ingrese los valores solo para las siguientes claves.

Cambie el valor de "accounts_url" según su dominio (UE, CN). Valor predeterminado establecido como dominio estadounidense.

• client_id, client_secret y redirect_uri son las configuraciones del cliente de OAuth que obtendrá después de registrar su cliente de Zoho.
• access_type se debe configurar como offline solo porque el SDK de Python en este momento no admite el cliente de OAuth.
• token_persistence_path es la ruta donde se almacenan los tokens relacionados de OAuth del archivo. Si se utiliza esta opción, no es necesario indicar una base de datos para persistencia. La persistencia solo sucede a través del archivo.

Incluya la ruta absoluta de configuration.properties para la clave “applicationLogFilePath” con el fin de almacenar los registros. Puede encontrar el archivo en "zcrmsdk/resources". Este archivo sirve para registrar las excepciones ocurridas durante el uso del SDK de Python.

Ingrese los valores solo para las siguientes claves. Si no se proporciona la ruta de los registros, estos no se almacenarán, pero podrá verlos en la consola

Para realizar solicitudes de la API a la cuenta del entorno de pruebas, cambie el valor de la siguiente clave a true. Por defecto, el valor es false.

Si su aplicación necesita una sola autenticación de usuario, deberá configurar el ID de correo electrónico del usuario en al archivo configurations.properties, como se indica a continuación:

A fin de trabajar con la autenticación de múltiples usuarios, debe establecer el ID de correo electrónico del usuario en el thread actual como un atributo:

Si bien puede utilizar lo anterior para la autenticación de usuario único, recomendamos hacerlo mediante la configuración del ID de correo electrónico en el archivo configuration.properties.

Si no configura la dirección de correo electrónico del usuario en el thread actual, el SDK esperará encontrarla en el archivo configuration.properties. Si la dirección de correo electrónico del usuario no está configurada en ninguno de estos, el SDK de Python arrojará una excepción.

Inicialización

La aplicación estará lista para su inicialización después de definir el archivo de configuración de OAuth.

Generar tokens de actualización y concesión que no requieren autorización

Para aplicaciones self client, se debe generar el token de concesión que no requiere autorización desde la consola para desarrolladores de Zoho (https://accounts.zoho.com/developerconsole)

1. Visite https://accounts.zoho.com/developerconsole
2. Haga clic en la opción Opciones → Self Client del cliente que desea autorizar.
3. Ingrese uno o más de los alcances de Zoho CRM válidos (separados por comas) que desea autorizar en el campo "Alcance" y elija la fecha de vencimiento. Indique el alcance “aaaserver.profile.READ” junto con los alcances de Zoho CRM.
4. Copie el token de concesión para realizar una copia de seguridad.
5. Genere un refresh_token a partir del token de concesión haciendo una petición POST con la dirección URL que se menciona a continuación

   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. Copie el token de actualización para realizar una copia de seguridad.

El token de concesión generado solo es válido durante el período estipulado que escogió cuando lo generó. Por lo tanto, los tokens de acceso y actualización se deben generar dentro de ese período.

Generar un token de acceso

Se puede generar el token de acceso por medio del token de concesión o el token de actualización. Basta con seguir cualquiera de los dos métodos.

Generar un token de acceso a partir de un token de concesión

Se deberá ejecutar el siguiente fragmento de código en la clase principal para obtener tokens de acceso.

Pegue el token de concesión en la cadena literal mencionada.

Solo deberá realizar este proceso una vez.

Generar tokens de acceso a partir del token de actualización

Se deberá ejecutar el siguiente fragmento de código en la clase principal para obtener tokens de acceso.

Pegue el token de actualización en la cadena literal mencionada.

Solo deberá realizar este proceso una vez.

Después de realizar correctamente la ejecución del fragmento de código anterior, los tokens de acceso y actualización generados deberían haber persistido a través de la clase de controlador de persistencias.

Una vez que los tokens OAuth hayan persistido, en las siguientes solicitudes API se utilizarán los tokens de acceso y actualización persistentes. El SDK de Python se encargará de actualizar el token de acceso mediante el token de actualización, según sea necesario.

Iniciar la aplicación

El SDK de Python requiere de la invocación de la siguiente línea de código cada vez que la aplicación cliente se inicie.

Una vez que el SDK se haya inicializado mediante la línea anterior, puede utilizar cualquiera de las API del SDK para obtener resultados adecuados.

Usar el SDK

Agregue la siguiente línea en los archivos Python de su aplicación cliente, en los que le gustaría utilizar el SDK de Python.

A través de esta línea, puede acceder a todas las funciones del SDK de Python.

Jerarquía de clases

Todas las entidades de Zoho CRM se presentan como módulos que tienen clases, métodos y variables de instancias que se pueden aplicar a esa entidad en particular. ZCRMRestClient es la clase básica del SDK de Python. Esta clase cuenta con métodos para obtener instancias de varias otras entidades de Zoho CRM. Se encuentra en el módulo RestClient.

La jerarquía y las relaciones de clases del SDK se rigen por la jerarquía de las entidades dentro de Zoho CRM. La jerarquía de clases de varias entidades de Zoho CRM se indica a continuación:

Como aparece en la jerarquía, todas las clases de entidades tienen variables de instancias para capturar sus propias propiedades y capturar datos de sus entidades secundarias inmediatas a través una solicitud a la API.

Por ejemplo, un objeto de un módulo de Zoho CRM (ZCRMModule) tendrá variables de instancias para obtener las propiedades de un módulo, como nombre de visualización, ID de módulo, etc., y también tendrá variables de instancias para capturar todos sus objetos secundarios (como ZCRMLayout).

Crear instancias de objetos

No siempre es efectivo seguir la jerarquía de clases completa de la parte superior para capturar los datos de una entidad en un nivel inferior, ya que esto podría conllevar solicitudes de API en todos los niveles. Con el objetivo de manejar esta situación, todas las clases de entidades tendrán un método get_instance(), a fin de obtener su propio objeto ficticio, y variables de instancias, para obtener objetos ficticios de sus entidades secundarias.

Tenga en cuenta que no se llenará ninguna de las propiedades del método get_instance(), ya que no se emitiría una solicitud a la API. Esto solo devolvería un objeto ficticio que se utilizaría solo para acceder a los métodos dinámicos de la clase.

Para resumir,

• ZCRMRestClient.get_module(“Contacts”) devolverá el módulo real de Contactos, que tiene todas las propiedades del módulo de Contactos ingresadas mediante una solicitud de API
• ZCRMRestClient.get_module_instance(“Contacts”) devolverá un objeto ZCRMModule ficticio que se referirá al módulo de Contactos, sin propiedades ingresadas, ya que no realiza una solicitud a la API.

Por lo tanto, para obtener los registros de un módulo, no será necesario que inicie desde ZCRMRestClient. En su lugar, puede obtener una instancia de ZCRMModule con ZCRMModule.get_instance() e invocar su método dinámico get_records() desde la instancia creada. Esto evita la solicitud de la API que, de otra manera, se habría activado para rellenar el objeto ZCRMModule.

Acceso a propiedades de registro

Puesto que las propiedades de registro son dinámicas en todos los módulos, se han proporcionado solo los campos comunes, como created_time, created_by, owner, etc., como propiedades predeterminadas de ZCRMRecord. Todas las otras propiedades de registros están disponibles en forma diccionario en el objeto ZCRMRecord.

Para acceder a los valores de campo individuales de un registro, utilice los métodos de captador y establecedor disponibles. Las claves del diccionario de propiedades de registro corresponden a los nombres de la API de los campos del módulo. Los nombres de la API para todos los campos de todos los módulos están disponibles en Configuración → Extensiones y API → API de CRM → Nombres de la API.

Para obtener el valor de un campo, utilice record.get_field_value(field_api_name). Para establecer el valor de un campo, utilice record.set_field_value(field_api_name,new_value). Cuando establezca el valor de un campo, asegúrese de que el valor establecido corresponda al tipo de datos del campo en el que lo va a establecer.

Administración de respuestas

APIResponse y BulkAPIResponse son los objetos contenedores de las respuestas de API de Zoho CRM. Con todos los métodos de llamada API, se devuelve uno de estos dos objetos.

DownloadFile y downloadPhoto devuelven FileAPIResponse, en lugar de APIResponse.

Un método que realiza la búsqueda de una sola entidad devolverá un objeto APIResponse, mientras que un método que busca una lista de entidades devolverá un objeto BulkAPIResponse.

Utilice la variable de instancias "data" para obtener los datos de la entidad de manera separada de los objetos envoltorio de respuesta. APIResponse.data devolverá un solo objeto de entidad de Zoho CRM, mientras que BulkAPIResponse.data devolverá una lista de objetos de entidad de Zoho CRM.

Además de los datos, estos objetos contenedores de respuesta tienen las siguientes propiedades:

1. response_headers: recuento de API faltantes del día/ventana presente y el tiempo transcurrido del restablecimiento de la ventana presente.
2. info: cualquier otro tipo de información, si la API la proporciona, además de los datos reales.
3. bulk_entity_response (lista de instancias de EntityResponse): estado de entidades individuales en una API masiva. Por ejemplo, una API de ingreso de registros puede presentar un error parcial debido a algunos registros. Esta matriz proporciona el estado de creación de los registros individuales.

Excepciones

El SDK de Python administra todos los comportamientos inesperados, como respuestas incorrectas de la API y errores del SDK, y se producen como una sola excepción: ZCRMException. Por lo tanto, basta con captar esta única excepción en el código de la aplicación del cliente.

Clases y variables de instancia