Guía del administrador para la API de Zendesk

¿Qué es la API de Zendesk?

Una API, o interfaz de programación de aplicaciones, es una herramienta para aplicaciones de software. Se puede pensar como un restaurante, donde el mesero lleva los platos de la cocina a la mesa. La API funciona de manera similar: lleva los datos de un punto a otro. En la API, el plato se llama un recurso, y el mesero que lo lleva se llama un extremo. Piense en un plato específico que podría pedir en un restaurante. Algunos extremos traen una colección de elementos como un plato de degustación. Un ejemplo de esto en la API sería el extremo Lista de usuarios. Devuelve una lista de todos los usuarios de su cuenta de Zendesk Support. Algunos extremos como el extremo Mostrar usuario están más enfocados y solo devuelven una cosa.

La API también se puede usar para hacer cambios en distintas cosas en Zendesk. Imagínese que le dice al mesero cómo desea que se cocine su carne. Entonces, se puede decir que el chef hace cambios en la carne para que quede a su gusto. La API es un recurso poderoso que muchos de nuestros clientes usan para hacer importaciones masivas de recursos, crear aplicaciones, enviar datos a fuentes externas y mucho más.

La mayoría de la documentación de referencia para la API de Zendesk se encuentra en la sección de referencia para la API del portal para desarrolladores de Zendesk. En la documentación de referencia se describen todos los extremos que están disponibles. También, para comenzar, puede usar la guía para desarrolladores de Zendesk. Aunque la documentación es exhaustiva, en este artículo explicaremos cómo decodificar y utilizar la API.

¿Por qué usar la API?

Ahora que ya sabe de qué se trata la API, posiblemente se está preguntando “¿Cómo me afecta?” En pocas palabras, la API se puede usar para agregar funcionalidad que no está disponible en la interfaz de usuario (ya sea de forma nativa o a nivel de un plan en particular) mucho más rápido que si se intentara hacerlo todo manualmente.

Para las cuentas que tienen actualmente los planes Essential o Team, la API proporciona un método directo para exportar datos sin necesidad de subir de categoría al plan Professional (que permite exportaciones de datos automatizadas). De manera similar, la API se puede usar para obtener datos de tickets para los informes. La API puede devolver toda la información relacionada con un ticket, de manera que la salida de la API se puede usar para pasar los datos a una aplicación de informes de terceros.

La capacidad de actualizar rápidamente varios registros es otra ventaja de usar la API. Por ejemplo, mientras que en la interfaz de agente solo se puede crear una organización a la vez, con la API se pueden crear hasta 100 organizaciones a la vez. De igual manera, las restricciones sobre cuántos elementos se pueden actualizar a la vez son más altas con la API. La interfaz permite editar 60 tickets a la vez, mientras que la API permite editar hasta 100 tickets.

Otras tareas comunes:

• Crear tickets
• Migrar datos de tickets a Zendesk desde otro sistema
• Editar usuarios de forma masiva
• Hacer búsquedas en los registros
• Y mucho más

Ahora que ya hicimos un resumen de por qué conviene usar la API, veamos cómo se hace una solicitud de API.

Formato

La API de Zendesk devuelve datos usando un formato ligero llamado JSON. Consulte Working with JSON en el Centro de ayuda de Zendesk. Para ver los datos formateados en un navegador web, hay que instalar una extensión de visualizador de JSON para Chrome o Firefox.

JSON se ve así:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
  ]
}

Un extremo típico se ve así:

subdomain.zendesk.com/api/v2/users/me.json

Los extremos pueden realizar las siguientes acciones:

• GET: obtener elementos 
• POST: crear elementos que no existían anteriormente
• PUT: actualizar elementos existentes
• DELETE: eliminar elementos

En un navegador, solo es posible hacer solicitudes GET. Las otras acciones se pueden realizar usando herramientas como cURL o Postman.

cURL

En la documentación de referencia se usa cURL en todos los ejemplos de los extremos. cURL es una herramienta de línea de comando que permite probar los comandos de API sin un navegador. Si desea más información, consulte Installing and Using cURL en el Centro de ayuda de Zendesk. Se puede usar cURL para cualquiera de los cuatro tipos de llamadas. Viene ya instalado en Mac, pero hay que instalarlo en Windows. Si desea ver las instrucciones, consulte Installing cURL en el Centro de ayuda de Zendesk.

Estado de las solicitudes

Por cada solicitud de API que se realiza, se recibe una respuesta que indica si funcionó o no. Si no funcionó, la respuesta proporcionará explicaciones breves de por qué no funcionó la solicitud. A estas respuestas se les conoce como códigos de estado. Los siguientes son algunos de los códigos básicos:

• 200: la solicitud se realizó correctamente
• 400: la solicitud no tuvo éxito
• 409: error de fusión o restricción, vuelva a intentar la llamada
• 422: entidad no procesable
• 429: se excedió el límite de velocidad
• 500: advertencia o estado temporal, contacte a soporte si continúa

Consulte Response Format en los documentos de la API si desea más detalles sobre los códigos de estado.

Práctica

Ahora que ya hemos descrito los aspectos básicos de una API, veamos cómo podemos usarla para hacer búsquedas en los tickets.

Digamos que yo soy un usuario de un plan de nivel Team y he estado usando etiquetas para hacer seguimiento de cuándo los tickets se derivan a los distintos niveles de soporte. Las etiquetas que agrego son derivación_uno y derivación_dos.

A continuación, deseo generar un informe de cada ticket de mi sistema que alguna vez haya alcanzado ambas derivaciones. Intenté crear una vista para devolver estos tickets, pero no satisfacía mis necesidades porque no se mostraban los tickets archivados. ¿Qué hago ahora?

Respuesta: Utilizo la API para obtener los tickets.

Para ello, recomendamos consultar Search API endpoint (extremo de la API de búsqueda). Este extremo no filtra los tickets archivados, de manera que se puede usar para devolver una lista de todos los tickets que incluyan las dos etiquetas. De manera similar, la API de búsqueda es una llamada GET sencilla, así que se puede usar directamente en el navegador, si se ha iniciado sesión en Zendesk Support en otra pestaña del navegador. El formato del extremo de búsqueda es como sigue:

subdomain.zendesk.com/api/v2/search.json?query={search_string}

Importante: No olvide reemplazar "subdominio" con el subdominio de su cuenta.

La API de búsqueda es muy flexible y en la consulta se puede usar cualquier cosa que se describa en Tipos de búsquedas en Zendesk. En nuestro ejemplo, como solo estamos buscando etiquetas, el único parámetro que usaremos en la cadena de búsqueda es "etiquetas". Para buscar varias etiquetas, lo único que hay que hacer es agregar una coma entre las etiquetas después del parámetro "tags". La llamada debería ser como sigue:

https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two

Para autenticar la solicitud, es necesario ser un agente o un administrador y haber iniciado sesión en Zendesk Support en otra pestaña del navegador.

Si esta llamada se ejecuta en el navegador, se devolverá una lista de tickets con las dos etiquetas. A continuación, se puede guardar la salida de JSON para usarla en el futuro.

¡Felicitaciones! ¡Ya llegamos al final! La API es una herramienta poderosa que tiene una variedad de usos. Ahora puede comenzar a explorar más a fondo la documentación de referencia y la documentación para desarrolladores de Zendesk.