En el siguiente vídeo os voy a contar como podemos crear un token con el API de Zoho y cómo trabajar con él desde Postman.
Una vez que ya tenemos hecho ese trabajo es muy sencillo que cada uno, con su lenguaje de programación favorito, lo haga funcionar en su entorno.
Para mi, Zoho CRM, ha sido un muy grato descubrimiento gracias a un cliente, y posiblemente empiece a formar parte de nuestros desarrollos futuros, dada la calidad de su API.
Resumen del vídeo
Al integrar Zoho CRM con otros sistemas, por ejemplo para que cada pedido de WooCommerce se registre en el CRM, lo que más cuesta al principio es la conexión inicial con la API. En este tutorial os enseño paso a paso cómo crear un token en la API de Zoho CRM y probarlo con Postman, usando cuentas gratuitas de ambos servicios. Una vez que lo tengáis funcionando en Postman, podréis trasladarlo a vuestro lenguaje; nosotros lo usamos en PHP y .NET. La cuenta gratuita de Zoho es suficiente para desarrollo y ofrece un número limitado de créditos diarios de API.
Los tres tokens de la API de Zoho CRM
Zoho utiliza OAuth 2.0 y conviene entender que intervienen tres tokens distintos:
- Código de autorización (grant token): se genera en la consola y caduca a los 10 minutos. Solo sirve para obtener el siguiente.
- Refresh token (el «token renovador»): no caduca mientras no eliminéis el cliente. Debéis guardarlo de forma segura, por ejemplo en vuestra base de datos.
- Access token (el «token de trabajo»): se obtiene a partir del refresh token, dura una hora y es el que se envía en cada petición.
Paso a paso para obtener el token
- En la consola de API de Zoho, cread un cliente de tipo Self Client, pensado para integraciones servidor a servidor donde nadie introduce usuario y clave. Obtendréis el Client ID y el Client Secret.
- Generad el código de autorización indicando el scope. Ojo aquí: para acceder a los datos debe ser ZohoCRM.modules.ALL, no el de ajustes (settings). En el vídeo cometí ese error y la consulta de contactos fallaba por falta de permisos.
- En Postman, haced una petición POST al endpoint de tokens de Zoho con el cuerpo en formato x-www-form-urlencoded y los parámetros code, client_id, client_secret, redirect_uri (vuestra web, aunque no se use) y grant_type=authorization_code. Hacedlo antes de que pasen los 10 minutos. La respuesta incluye el refresh token.
- Para trabajar, haced otra petición POST con grant_type=refresh_token, el refresh token, el client_id y el client_secret. Obtendréis un access token válido durante una hora.
Consultar contactos y buscar por campos
Para leer datos se usan peticiones GET a la URL del módulo (Contacts, Leads, Quotes…) añadiendo la cabecera Authorization con el prefijo Zoho-oauthtoken, un espacio y el access token. La respuesta llega en JSON. Cambiando el nombre del módulo en la URL accedéis a posibles clientes, presupuestos, etc.
Para buscar, se usa el endpoint search con un parámetro criteria, por ejemplo por ID o por cualquier otro campo como el teléfono. Si no hay resultados, Zoho devuelve un estado 204 No Content.
Consejos para producción
- Zoho limita cuántos tokens se pueden generar en poco tiempo y, al superar el máximo de refresh tokens, borra los más antiguos. Reutilizad el access token mientras sea válido: yo guardo la hora de generación y solo pido uno nuevo si han pasado más de unos 50 minutos.
- En procesos masivos (cientos de peticiones), usad el mismo token en lugar de generar uno por llamada.
- Si un refresh token se ve comprometido, eliminad el cliente en la consola y repetid el proceso.
La documentación de la API REST de Zoho incluye ejemplos en varios lenguajes y permite insertar, actualizar, relacionar o eliminar registros de todos los módulos.