martes, 19 de noviembre de 2019

Tutorial en español - Cómo conectarse a la API v2 de Zoho vía PHP

CÓMO CONECTARSE A LA API v2 DE ZOHO vía PHP

TUTORIAL EN ESPAÑOL

Explicado detalladamente con palitos y manzanas

Ya que, a mi parecer, la documentación oficial peca de claridad, o al menos de la claridad que yo necesitaba; me vi obligado a apoyarme en tutoriales ajenos a Zoho para intentar establecer conexión persistente con la API v2. Lamentablemente todos los tutoriales que encontré estaban en inglés y la mayoría de ellos, sino es que todos, si bien clarificaron muchas cosas, aún así no eran tan claros. Finalmente logré mi objetivo y ahora trabajo facilito con la API v2 de Zoho. ¿Aún no logras establecer conexión con la API v2 de Zoho? Bueno, pues como sé que hoy no quieres trabajar, ahí te voy.


Aquí van los pasos explicados fácil:
  1. Accedemos a accounts.zoho.com/developerconsole y agregamos un ID de cliente.
    Los datos que se solicitan son bastante obvios y nada hay más que decir. En el campo URIs de redireccionamiento autorizados simplemente ponemos la URL de un archivo PHP dentro de nuestro dominio, por ejemplo: https://midominio.com/zoho-api-v2/oauth2callback/index.php. El contenido de este archivo que simplemente sea una cadena como: Este es mi archivo para oauth2callback
  2. Después hay que instalar el SDK que necesitemos. Para conseguir el objetivo de este punto tendremos que meternos con la consola (si tienes un hosting Linux). Para ello tienes que acceder vía SSH a tu servidor (lamentablemente no voy a explicar esto aquí, ya que es otro tema y sería hacer este tutorial bastante largo -no seas perezoso, googléale y encuentras rápido cómo conectarte vía SSH a tu servidor).
    Una vez que accediste a tu servidor vía SSH con PuTTY (por ejemplo), te aseguras que composer esté instalado, y para ello simplemente tecleas: composer. Si aparece información sobre composer, ya la hiciste. Si el sistema te indica que no se reconoce el comando, entonces lo instalas siguiendo estas instrucciones en caso que tengas un servidor Linux (si tienes Windows, le googleas para ver cómo hacerlo).
    Ya que tienes composer en tu servidor, entonces accedes a la carpeta raíz del website o del proyecto donde estés trabajando. Una vez ahí, instalas el SDK de PHP tecleando: composer require zohocrm/php-sdk
  3. Ahora hay que armar el tema de la persistencia. Con el fin de que el token que generemos (que es nuestra llave para hacer peticiones a la API) tenga presencia siempre, sin tener que andar generando el token cada rato, tenemos que crear una forma en que el token se haga persistente. Con este fin van las siguientes instrucciones. La documentación oficial indica que existen 3 métodos para armar la persistencia. Yo tenía toda la intención de utilizar el 1er método, que es utilizar una base de datos. Lamentablemente el servidor donde estoy trabajando me permite crear bases de datos que siempre llevan como prefijo una cadena ya establecida que no puedo cambiar, y como la documentación oficial indica que para armar este tema de la persistencia mediante base de datos forzosamente ésta debe llamarse zohooauth, pues simplemente no puedo armar la persistencia vía base de datos, porque mi base de datos forzosamente se llamaría miprefijo_zohooauth, y esto no sirve. Por tanto, aquí vamos a ir por la opción de persistencia por archivo.
    Entonces, ahora hay que crear un archivo PHP llamado como quieras, por ejemplo get-access-token.php, que para no perdernos, lo guardamos dentro de la carpeta vendor que se creó en nuestro servidor automáticamente al instalar el SDK. En este archivo vamos a crear unas variables y un array tal como sigue:
     $ZOHO_API_url_redirect        = 'https://midominio.comzoho-api-v2/oauth2callback/index.php';
     $ZOHO_API_client_id           = '1000.ABCDE';
     $ZOHO_API_client_secret       = 'abcdefghij';
     $ZOHO_API_account_email       = 'email@midominio.com';
     $ZOHO_API_grant_token         = '';
     $ZOHO_API_refreshToken        = '';
      
     $configuration = array(
      'client_id'              => $ZOHO_API_client_id,
      'client_secret'          => $ZOHO_API_client_secret,
      'redirect_uri'           => $ZOHO_API_url_redirect,
      'currentUserEmail'       => $ZOHO_API_account_email,
      'apiVersion'             => 'v2',
      'applicationLogFilePath' => '/home/miuser/public_html/zoho-api-v2/',
      'sandbox'                => false,
      'token_persistence_path' => '/home/miuser/public_html/zoho-api-v2/'
     );
      
    Van notas sobre estas variables y el array:
    • Sobre las variables:
      1. $ZOHO_API_url_redirect. Aquí ponemos la URL callback mencionada antes
      2. $ZOHO_API_client_id. Aquí ponemos el ID del cliente que se nos dio al generarlo en accounts.zoho.com/developerconsole
      3. $ZOHO_API_client_secret. Aquí ponemos el secreto del cliente que se nos dio al generarlo en accounts.zoho.com/developerconsole
      4. $ZOHO_API_account_email. Este es el email del usuario con el que accedemos a Zoho
      5. $ZOHO_API_grant_token. El contenido de esta variable lo vemos más adelante.
      6. $ZOHO_API_refreshToken. El contenido de esta variable lo vemos más adelante.
    • Sobre el array:
      1. applicationLogFilePath. Aquí ponemos la ruta de la carpeta donde se guardará el LOG de nuestra app (la carpeta puede ser la que nos guste). Ojo, poner sólo la ruta de carpetas sin el nombre del archivo LOG. El archivo log lo creamos nosotros y debe llamarse forzosamente ZCRMClientLibrary.log
      2. sandbox. Inicialmente tuve la intención de poner modo sandbox a TRUE, pero luego leí por ahí que a alguien no le funcionó, así que decidí dejarlo en FALSE.
      3. token_persistence_path. Aquí ponemos la ruta de la carpeta donde se guardará el token (la carpeta puede ser la que nos guste). Ojo, poner sólo la ruta de carpetas sin el nombre del archivo donde se guardará el token. El archivo en cuestión lo creamos nosotros y debe llamarse forzosamente zcrm_oauthtokens.txt
  4. Accedemos nuevamente a accounts.zoho.com/developerconsole y damos clic en los 3 puntitos verticales que están en el extremo derecho de nuestro recién creado ID de cliente, y seleccionamos la opción Cliente propio. En el campo Ámbito ponemos los ámbitos (scopes) de la API a los cuales queremos tener acceso, pero siempre incluyendo por defecto el llamado aaaserver.profile.READ. Por ejemplo, si queremos tener acceso a todos los ámbitos, ponemos: aaaserver.profile.READ,ZohoCRM.users.ALL,ZohoCRM.modules.ALL,ZohoCRM.settings.all
    Como se ve, los ámbitos se separan por una coma y no hay espacios presentes (si no separas con comas y/o pones espacios, la cosa no funciona). Los ámbitos disponibles los puedes encontrar por por aquí. (Para no andar con prisas, elegir 10 minutos en el campo Vencimiento).
    Al terminar con esto, el sistema te dará un code. Copias ese code y lo guardas como valor de la variable $ZOHO_API_grant_token mencionada antes.
    Para hacer lo siguiente tienes 10 minutos (que son los que configuramos antes en accounts.zoho.com/developerconsole). No hay prisa, entonces ahora hay que hacer una petición cURL en PHP dentro del archivo que creamos antes (get-access-token.php):
     $sesion_curl = curl_init();
     $url = 'https://accounts.zoho.com/oauth/v2/token?code='.$ZOHO_API_grant_token.'&redirect_uri='.$ZOHO_API_url_redirect.'&client_id='.$ZOHO_API_client_id.'&client_secret='.$ZOHO_API_client_secret.'&grant_type=authorization_code';
     curl_setopt ($sesion_curl, CURLOPT_URL, $url);
     curl_setopt ($sesion_curl, CURLOPT_SSL_VERIFYPEER, TRUE);
     curl_setopt ($sesion_curl, CURLOPT_RETURNTRANSFER, TRUE);
     curl_setopt ($sesion_curl, CURLOPT_CUSTOMREQUEST, 'POST');
     $resultado = curl_exec ($sesion_curl);
     print_r($resultado);
     curl_close($sesion_curl);
      
    Si todo salió bien (y por tu bien ojalá sea así, porque no voy a estar ahí en caso contrario), en pantalla se imprime un jSON con una key llamada refresh_token. Copias el valor de ese key (parecido a 1000.a1b2c3d.d3c3ba1) y lo guardas como valor de la variable $ZOHO_API_refreshToken mencionada antes.
    Ahora elimina o comenta todas las líneas relacionadas con la petición cURL.
  5. Ahora hay que generar el famoso token que nos permitirá conectarnos a la API y poder finalmente acceder a los registros de nuestro CRM Zoho.
    En nuestro archivo get-access-token.php ponemos lo siguiente (recordar que nuestro archivo debe estar dentro de la carpeta vendor que se creó al instalar el SDK, y si no está ahí, entonces modificar el path correcto para el archivo autoload.php):
     require_once __DIR__ . '/autoload.php';
     use zcrmsdk\crm\crud\ZCRMInventoryLineItem;
     use zcrmsdk\crm\crud\ZCRMJunctionRecord;
     use zcrmsdk\crm\crud\ZCRMNote;
     use zcrmsdk\crm\crud\ZCRMRecord;
     use zcrmsdk\crm\crud\ZCRMTax;
     use zcrmsdk\crm\setup\restclient\ZCRMRestClient;
     use zcrmsdk\crm\setup\users\ZCRMUser;
     use zcrmsdk\crm\exception\ZCRMException;
     use zcrmsdk\oauth\ZohoOAuth;
     use zcrmsdk\oauth\exception\ZohoOAuthException;
     use zcrmsdk\oauth\utility\ZohoOAuthConstants;
     $configuration = array(
      'client_id'              => $ZOHO_API_client_id,
      'client_secret'          => $ZOHO_API_client_secret,
      'redirect_uri'           => $ZOHO_API_url_redirect,
      'currentUserEmail'       => $ZOHO_API_account_email,
      'apiVersion'             => 'v2',
      'applicationLogFilePath' => '/home/miuser/public_html/zoho-api-v2/',
      'sandbox'                => false,
      'token_persistence_path' => '/home/miuser/public_html/zoho-api-v2/'
     );
     ZCRMRestClient::initialize($configuration);
     $oAuthClient = ZohoOAuth::getClientInstance();
     $userIdentifier = $ZOHO_API_account_email;
     $oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($ZOHO_API_refreshToken,$userIdentifier);
      
    Si todo salió bien (y más te vale que así sea), en pantalla no aparece nada ni se genera ningun error_log dentro del servidor, y el archivo zcrm_oauthtokens.txt pasa de pesar 0 bytes, a pesar aproximadamente 496 bytes, lo que indica que logramos nuestro objetivo y en ese archivo se guarda el token tan codiciado.

Listo, ya es todo, con esto ya tenemos conexión persistente a la API v2 de Zoho y desde ya podemos gestionar nuestros registros en Zoho. Francamente ahora estoy bastante cansado para armar otro tutorial sobre cómo hacer peticiones GET, POST, UPDATE, etc., a la API. Así que si quieres que arme este otro tutorial, avísame con un comentario, y si tampoco quieres cansarte en hacer ese comentario, no importa, igual lo voya a armar, pero ahora no, más tarde y cuando tenga tiempo.



SOLUCIÓN a problemas en Motorola actualizado a Android 10

 En esta serie de videos se encuentra la solución a cómo hacer downgrade a la versión de Android, de la 10 a la 9, con el fin de deshacerno...