El SDK de PHP es un envoltorio para las API de Zoho CRM. En consecuencia, la invocación de una API de Zoho CRM desde su aplicación PHP del lado del cliente es solo la llamada de una función. Esto 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 PHP se puede instalar a través de “Composer”. Composer es una herramienta de administración de dependencias en PHP. El SDK espera lo siguiente de la aplicación del cliente.

• La aplicación del cliente debe contar con PHP 5.6, o superior, con la extensión curlhabilitada.
• El SDK de PHP debe instalarse en la aplicación del cliente mediante Composer.
• Se debe llamar la función ZCRMRestClient::initialize() al inicio de la 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 “useridentifier”(varchar(100)), “accesstoken”(varchar(100)), “refreshtoken”(varchar(100)), “expirytime”(bigint).

Si se indica token_persistence_path en el archivo oauth_configuration.properties, 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.txt en la mencionada ruta token_persistence_path.

Instalación del SDK de PHP a través de Composer

Instale Composer (si no está instalado)

Ejecute este comando para instalar Composer

Para hacer que se pueda acceder a Composer de manera global, siga las instrucciones del siguiente enlace

Instalar el SDK de PHP

Esta es la forma de instalar el SDK

1. Desplácese hasta el área de trabajo de su aplicación cliente
2. Ejecute este comando:

   composer requiere zohocrm/php-sdk

3. De esta forma, el SDK de PHP se instalará y se creará un paquete denominado "vendor" en el espacio de trabajo de la aplicación cliente.

Configuraciones

Se deben brindar los detalles del cliente de OAuth al SDK de PHP como un archivo de propiedades. En el SDK de PHP, hemos colocado un archivo de configuración (oauth_configuration.properties). Coloque los valores respectivos en dicho archivo. Puede encontrar el archivo en "vendor/zohocrm/php-sdk/src/resources".

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

• Solo se deben llenar las claves mencionadas anteriormente.
• 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 PHP en este momento no admite el cliente de OAuth.
• persistence_handler_class es la implementación de ZohoOAuthPersistenceInterface, es decir, ZohoOAuthPersistenceHandler.
• 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.

Cree un archivo denominado "ZCRMClientLibrary.log" en el equipo de su aplicación cliente y mencione la ruta absoluta del archivo creado en configuration.properties para la clave "applicationLogFilePath". Puede encontrar el archivo en "vendor/zohocrm/php-sdk/src/resources". Este archivo sirve para registrar las excepciones ocurridas durante el uso del SDK de PHP.

Llene solo las siguientes claves

Para realizar solicitudes de la API a la cuenta del entorno de pruebas, cambie el valor de la siguiente clave a true en el archivo configurations.properties . 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 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 la variable super global de PHP "$_SERVER", tal como se muestra a continuación:

Si bien puede utilizar la variable $_SERVER 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 como una variable super global, 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 PHP 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 en el campo "Alcance" uno o más de los alcances de Zoho CRM válidos (separados por comas) que desea autorizar y seleccione una 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 y actualización. Pegue la copia del token de concesión en la cadena literal mencionada a continuación. Solo deberá realizar este proceso una vez.

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

Generar un token 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 y actualización. Pegue el token de actualización en la cadena literal mencionada a continuación. 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 PHP 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 PHP requiere 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 de PHP se haya inicializado mediante la línea anterior, puede utilizar cualquiera de las API del SDK para obtener resultados adecuados.

Cómo utilizar el SDK de PHP

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

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

Jerarquía de clases

Todas las entidades de Zoho CRM se presentan como clases que tienen propiedades y funciones que se emplean en una entidad en particular. ZCRMRestClient es la clase básica del SDK de PHP. Esta clase cuenta con funciones 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:

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

Todas las entidades de clases tienen funciones para capturar sus propias propiedades y para capturar los datos de sus entidades secundarias inmediatas a través de una solicitud de 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 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 una función getInstance(), a fin de obtener su propio objeto ficticio, además de funciones para obtener objetos ficticios de sus entidades secundarias.

Tenga en cuenta que no se llenará ninguna de las propiedades de la función getInstance(), ya que no se emitiría una solicitud a la API. Esto solo devolvería un objeto ficticio que solo se debería utilizar para acceder a las funciones dinámicas 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 de API.
• ZCRMRestClient::getModuleInstance("Contacts") devolverá un objeto ficticio ZCRMModule que se referirá al módulo de Contactos, sin propiedades ingresadas, ya que no realiza una solicitud de API.

Por lo tanto, para obtener registros de un módulo, no es necesario que empiece desde ZCRMRestClient. En su lugar, puede obtener una instancia de ZCRMModule con ZCRMModule::getInstance() e invocar su función dinámica getRecords() 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 campos como createdTime, createdBy, owner, etc., como propiedades predeterminadas de ZCRMRecord. Todas las otras propiedades de registros están disponibles como un mapa en el objeto ZCRMRecord.

Para acceder a los valores de campos individuales de un registro, utilice las funciones disponibles de obtención y configuración. 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 → API de CRM → Nombres de la API.

• Para obtener el valor de un campo, use $record → getFieldValue($fieldAPIName);
• Para configurar el valor de un campo, use $record → setFieldValue($fieldAPIName, $newValue);
  Cuando establezca el valor de un campo, asegúrese de que el valor corresponda al tipo de datos del campo en el que lo va a establecer.

Administración de respuestas

APIResponse y BulkAPIResponse son los objetos envoltorio de las respuestas de API de Zoho CRM. Todas funciones de solicitudes a la API devuelven uno de estos dos objetos.

• DownloadFile y downloadPhoto devuelven FileAPIResponse, en lugar de APIResponse.
• Una función que realiza la búsqueda de una sola entidad devolverá un objeto APIResponse, mientras que una función que busca una lista de entidades devolverá un objeto BulkAPIResponse.
• Utilice la función getData() para obtener los datos de la entidad separados de los objetos envoltorio 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. Array of EntityResponse(s): estado de las entidades individuales en una API masiva. 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 de PHP 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 excepción por sí sola en el código de la aplicación cliente.