El SDK de Java 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 Java del lado del cliente es solo la llamada de un método.

Descargue el archivo del SDK para empezar a trabajar en su proyecto.

• SDK con dependencias
• SDK sin dependencias

Los archivos JAR con dependencia son los siguientes:

• hamcrest-all-1.3
• httpclient-4.4.1
• httpcore-4.4.4
• httpmime-4.5.3
• json-20170516
• servlet-api-2.5
• commons-logging-1.1.3
• ZohoOAuthClient

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 Java está disponible como un archivo JAR. El SDK espera lo siguiente de la aplicación del cliente.

• La aplicación del lado del cliente debe estar funcionando con al menos Java 7.
• El archivo JAR y los archivos de configuración necesarios deberían agregarse como un SDK al proyecto del cliente y deberían estar disponibles en la ruta de clases durante la compilación y ejecución.
• Cuando inicie la aplicación, debe llamar e invocar correctamente el método ZCRMRestClient.initialize();, sin excepción alguna.

Configuraciones

Debe brindar al SDK los detalles de su cliente de OAuth como un archivo de propiedades. Cree un archivo oauth_configuration.properties y colóquelo en la carpeta "Recursos". Asegúrese de que el archivo "resources/oauth_configuration.properties" esté disponible en su ruta de clase.

El archivo debe tener el siguiente formato y las siguientes propiedades y sus valores respectivos.

• client_id, client_secret y redirect_uri corresponden a las configuraciones del cliente de OAuth que se obtienen después de registrar el cliente de Zoho.
• Scope puede ser uno o más scopes válidos de Zoho CRM (separados por comas). Agregue el scope Aaaserver.profile.Read a los scopes correspondientes. Es obligatorio.
• access_type se debe establecer como offline u online.
• persistence_handler_class corresponde a la implementación de la interfaz ZohoPersistenceHandler, que cuenta con métodos de controlador para almacenar datos OAuth. Ejemplo: persistence_handler_class=com.zoho.oauth.clientapp.ZohoOAuthFilePersistence (o) com.zoho.oauth.clientapp.ZohoOAuthDBPersistence (o) su propia clase de controlador de persistencias.
• Si prefiere utilizar la persistencia de nuestra base de datos, debe indicar las claves mysql_username y mysql_password para la conectividad de MySQL. De manera predeterminada, mysql_username = "root" y mysql_password = "".

Además de las configuraciones de OAuth mencionadas anteriormente, el SDK también proporciona opciones para anular determinados atributos de solicitud HTTP. Estas configuraciones se deben proporcionar en un archivo denominado zcrm_configuration.properties, el que también se debe colocar en la carpeta "Recursos".

Las siguientes son las configuraciones admitidas en el archivo zcrm_configuration.properties.

• El valor de timeOut representa el tiempo de espera de la solicitud en segundos. Deje timeOut vacío si no es necesario.
• El valor de userAgent proporciona un nombre opcional para la identificación del cliente.
• El valor
• minLogLevel representa el nivel de registro mínimo de impresiones del registrador de SDK. Los valores admitidos son los siguientes: ALL (TODOS), TRACE (SEGUIMIENTO), DEBUG (DEPURACIÓN), INFO (INFORMACIÓN), WARNING (ADVERTENCIA), ERROR y OFF (DESACTIVADO). El nivel de registro mínimo predeterminado corresponde a WARNING (ADVERTENCIA).
• Si está trabajando con varios usuarios, a fin de permitir que el SDK identifique al usuario específico que realiza la solicitud, la dirección de correo electrónico del solicitante se debe configurar mediante el siguiente fragmento de código antes de realizar la llamada del método del SDK.
  ZCRMRestClient.setCurrentUser(currentUserEmailId);
• Por otro lado, si es un solo usuario, puede establecer el ID de correo electrónico del usuario en ZCRMRestClient (como el que se muestra antes) en todas las solicitudes o puede proporcionar el ID de correo electrónico del usuario en el archivo zcrm_configuration.properties con la clave currentUserEmail como una configuración de una sola vez.
• accessType (opcional): tipo de entorno en CRM
  • Production: entorno que tiene usuarios con pago habilitado que acceden a datos empresariales importantes.
  • Development: entornos que puede ampliar, integrar y desarrollar sin afectar los entornos de producción.
  • Sandbox: entornos utilizados específicamente para probar la funcionalidad de la aplicación antes de implementarla en la producción o de presentarla a los consumidores.
• domainSuffix (opcional): compatibilidad con varios DC.
  • EE. UU.: www.zohoapis.com
  • Europa: www.zohoapis.eu
  • China: www.zohoapis.com.cn

Persistencia de OAuth

Una vez que el usuario autorice la aplicación, los tokens de acceso y actualización de OAuth se pueden utilizar en las subsiguientes solicitudes de datos de usuario de Zoho CRM. Por lo tanto, la aplicación del cliente debe hacerlos persistir. 

Para facilitar este proceso, debe escribir una implementación de la interfaz integrada ZohoPersistenceHandler, la que cuenta con los siguientes métodos de devolución de solicitudes: 

• saveOAuthData(ZohoOAuthTokens tokens): se invoca cuando se capturan tokens de acceso y actualización de Zoho. 
• deleteOAuthTokens(): se invoca antes de guardar los tokens recientemente recibidos. 
• getOAuthTokens(): se invoca antes de realizar una solicitud para capturar los tokens guardados. Con este método, se devuelve el objeto ZohoOAuthTokens para que la biblioteca lo procese. 

El nombre (junto con el paquete) de esta clase de implementación debe ser peristence_handler_class en oauth_configuration.properties. En la biblioteca del cliente, se incluyen dos implementaciones de muestra de ZohoPersistenceHandler. 

Puede utilizar cualquiera de las dos implementaciones de muestra que hemos incluido en la biblioteca: ZohoOAuthFilePersistence o ZohoOAuthDBPersistence. 

ZohoOAuthDBPersistence utiliza una persistencia de MySQL personalizada. Para utilizarla, debe asegurarse de hacer lo siguiente:  

• MySQL se debe ejecutar 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 "useridentifier" (varchar), "accesstoken" (varchar), "refreshtoken" (varchar) y "expirytime" (bigint).  

ZohoOAuthFilePersistence utiliza un archivo local de propiedades para escribir y leer los datos de los tokens de OAuth. La ruta completa del archivo que la biblioteca utilizará para leer y escribir los datos de los tokens debe especificarse en el archivo oauth_configuration.properties como el valor de la propiedad "oauth_tokens_file_path". (Por ejemplo,  oauth_tokens_file_path=/user-path/src/resources/oauthtokens.properties). 

Inicialización

La aplicación está lista para inicializarse después de definir la clase de controlador de persistencias de OAuth y el archivo de configuración de OAuth de la aplicación.

Generación de tokens de concesión

Para un solo usuario:

La consola de desarrollador tiene una opción de generación directa de tokens de concesión para un usuario. Esta opción puede ser útil si en la aplicación se van a utilizar las credenciales de solo un usuario de CRM para todas las operaciones o para la prueba de desarrollo.

1. Inicie sesión en la cuenta del usuario.
2. Visite https://accounts.zoho.com/developerconsole.
3. Haga clic en la opción Opciones → Self Client del cliente que desea autorizar.
4. Ingrese uno o más ámbitos válidos de Zoho CRM (separados por comas) que desee autorizar en el campo Ámbito y elija el período de validez.
5. Copie el token de concesión que se muestra en la pantalla.

Para varios usuarios:

Para varios usuarios, es responsabilidad de la aplicación del cliente generar el token de concesión de los usuarios que intentan iniciar sesión. La IU de la aplicación debe tener la opción "Iniciar sesión con Zoho" para abrir la URL del token de concesión de Zoho, en la que se solicitarán las credenciales de inicio de sesión de Zoho del usuario.

Después de iniciar correctamente la sesión del usuario, el token de concesión se enviará como parámetro a la URL de redirección registrada.

Generación de tokens de acceso y actualización

Después de obtener el token de concesión, se deberá ejecutar el siguiente fragmento de código en la clase principal para obtener tokens de acceso y actualización. Pegue la copia del token de concesión en la cadena literal mencionado.

Tome en cuenta que el fragmento de código anterior solo es válido una vez por token de concesión. Después de realizar correctamente la ejecución, los tokens generados de acceso y actualización habrán persistido en 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 se encargará de actualizar el token de acceso mediante el token de actualización, según sea necesario.

Iniciar la aplicación

SDK requiere la invocación de la siguiente línea de código cada vez que la aplicación 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.

Jerarquía de clases

Todas las entidades de Zoho CRM se presentan como clases que tienen miembros y métodos que se emplean en una entidad en particular. ZCRMRestClient es la clase básica del SDK. Esta clase cuenta con métodos para obtener instancias de varias otras entidades de Zoho CRM.

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:

Todas las entidades de clases tienen funciones para capturar sus propias propiedades y para capturar los datos de sus entidades secundarias inmediatas mediante una solicitud API.

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

Objetos de instancia

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

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

Para resumir,

• ZCRMRestClient.getModule("Contacts") devuelve el módulo real de Contactos, que tiene todas las propiedades del módulo de Contactos ingresadas mediante una solicitud a la API.
• ZCRMRestClient.getModuleInstance("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.getInstance() e invocar su método no estático getRecords() desde la instancia creada. Esto evitará la solicitud a la API que, de otra manera, se habría generado 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 createdTime, createdBy, owner, etc., como miembros predeterminados de ZCRMRecord. Todas las otras propiedades de registros están disponibles como un mapa 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 mapa de propiedades de registro corresponden a los nombres 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 → Marketplace → API de CRM → Nombres de la API.

• Para obtener el valor de un campo, utilice record.getFieldValue(fieldAPIName);
• Para establecer el valor de un campo, utilice record.setFieldValue(fieldAPIName, newValue);
  Cuando establezca el valor de un campo, asegúrese de que el valor establecido corresponda al tipo de datos APT 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.

• Una entidad de búsqueda de método devolverá el objeto APIResponse, mientras que una lista de entidades de búsqueda de método devolverá el objeto BulkAPIResponse.
• Utilice el método getData() para obtener los datos de la entidad separados de los objetos envoltorios de respuesta. APIResponse.getData() devolverá un solo objeto de entidad de Zoho CRM, mientras que BulkAPIResponse.getData() 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. ResponseHeaders: recuento de API faltantes del día/ventana presente y el tiempo transcurrido del restablecimiento de la ventana presente.
2. ResponseInfo: cualquier otro tipo de información, si la API la proporciona, además de los datos reales.
3. List<EntityResponse>: estado de las entidades individuales en una Bulk API. Por ejemplo: es posible que se produzca un error parcial en una API de ingreso de registros, debido a unos cuantos registros. Esta matriz proporciona el estado de creación de los registros individuales.

Excepciones

El SDK administra todos los comportamientos inesperados, como respuestas incorrectas de la API y errores del SDK, y se los muestra 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.