Cómo listar artículos de Zendesk Guide usando la API: una guía completa

Si está buscando acceder de forma programática al contenido de su centro de ayuda de Zendesk, ya sea para construir un índice de búsqueda personalizado, crear copias de seguridad o sincronizar artículos con otra plataforma, la API de Zendesk Guide es su herramienta ideal. Pero como muchas API REST, empezar puede resultar abrumador. Hay que averiguar la autenticación, manejar la paginación y elegir entre una variedad de puntos finales.

Esta guía le explica todo lo que necesita saber para listar y recuperar artículos de Zendesk Guide utilizando la API. Cubriremos la autenticación, la realización de sus primeras solicitudes, el manejo de la paginación para grandes bibliotecas de contenido y ejemplos de código del mundo real que puede adaptar a sus necesidades.

Lo que necesitará para empezar

Antes de sumergirse en las llamadas a la API, asegúrese de tener estos requisitos previos:

• Una cuenta de Zendesk con acceso de administrador o agente necesitará los permisos adecuados para generar tokens de API y acceder al contenido del centro de ayuda
• Un token de API generado desde su Centro de administración de Zendesk (lo cubriremos en el paso 1)
• Familiaridad básica con las API REST comprensión de los métodos HTTP (GET, POST), el formato JSON y los encabezados de las solicitudes
• Una herramienta para realizar solicitudes a la API esto podría ser cURL, Postman o un entorno de programación como Python o Node.js
• Conocimiento de los límites de velocidad de su plan Zendesk aplica diferentes límites de solicitud en función de su nivel de suscripción

Hablando de límites de velocidad, esto es con lo que está trabajando dependiendo de su plan:

Si excede estos límites, recibirá un error 429. La API sigue los límites de solicitudes por minuto de la API de soporte, y las solicitudes en una API no cuentan en contra del límite de velocidad de la otra.

Entendiendo la estructura de la API de Zendesk Guide

La API del Centro de Ayuda de Zendesk es una API REST que le permite interactuar con el contenido de su base de conocimientos de forma programática. Antes de realizar solicitudes, es útil entender cómo se organiza el contenido.

Zendesk Guide sigue una estructura jerárquica:

• Las Categorías son los contenedores de nivel superior para organizar el contenido
• Las Secciones viven dentro de las categorías y agrupan artículos relacionados
• Los Artículos son las piezas de contenido reales (temas de ayuda, FAQs, guías)

Cuando usted lista los artículos a través de la API, puede recuperar todos los artículos a través de su centro de ayuda, o filtrar por categorías o secciones específicas. La API devuelve respuestas JSON que contienen metadatos del artículo como el título, el contenido del cuerpo, la información del autor, el estado del borrador y más.

La autenticación utiliza la autenticación básica con su dirección de correo electrónico y un token de API. El formato es {email_address}/token:{api_token}, que se codifica en Base64 para el encabezado de autorización.

Una nota importante: las respuestas siempre se filtran de acuerdo con los permisos del usuario que realiza la solicitud. Así que si se está autenticando como un usuario final en lugar de un agente o administrador, solo verá los artículos que el usuario tiene permiso para ver.

Paso 1: configurar la autenticación de la API

Para empezar a utilizar la API, necesita un token de API. Aquí le explicamos cómo generar uno:

1. Inicie sesión en su cuenta de Zendesk como administrador
2. Navegue a Centro de administración → Canales → API
3. Haga clic en la pestaña Configuración
4. Active el Acceso al token si aún no lo está
5. Haga clic en el botón + para añadir un nuevo token
6. Dé a su token un nombre descriptivo (como "Script de exportación de artículos")
7. Copie el token inmediatamente Zendesk solo lo muestra una vez

Una vez que tenga su token, puede probar la autenticación con una simple solicitud cURL:

curl https://{your_subdomain}.zendesk.com/api/v2/help_center/articles \
  -v -u {your_email}/token:{your_api_token}

Reemplace {your_subdomain} con su subdominio de Zendesk, {your_email} con su correo electrónico de la cuenta, y {your_api_token} con el token que acaba de generar.

Si la autenticación tiene éxito, verá un código de estado 200 y una respuesta JSON con sus artículos. Si obtiene un error 401, compruebe que su token está activo y que su combinación de correo electrónico/token es correcta.

Problemas comunes de autenticación:

• 401 No autorizado El token está inactivo o el formato de correo electrónico/token es incorrecto
• 403 Prohibido El usuario no tiene permiso para acceder al recurso
• 404 No encontrado La URL del punto final es incorrecta

Paso 2: listar todos los artículos con una llamada básica a la API

Ahora que está autenticado, vamos a recuperar los artículos. El punto final principal para listar artículos es:

GET /api/v2/help_center/articles

Aquí hay un ejemplo completo de Python usando la librería requests:

import requests
from requests.auth import HTTPBasicAuth

subdomain = 'your_subdomain'
email = 'your_email@example.com'
api_token = 'your_api_token'

url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles'

response = requests.get(
    url,
    auth=HTTPBasicAuth(f'{email}/token', api_token),
    headers={'Content-Type': 'application/json'}
)

data = response.json()
articles = data['articles']

for article in articles:
    if not article['draft']:  # Skip drafts
        print(f"{article['id']}: {article['title']}")

La respuesta incluye un array articles donde cada objeto artículo contiene campos como:

Por defecto, este punto final devuelve 30 artículos por página. Si tiene más artículos, tendrá que manejar la paginación (cubierta en el paso 3).

Paso 3: manejar la paginación para grandes listas de artículos

La paginación es donde muchos desarrolladores se atascan. La API de Zendesk Guide soporta dos métodos de paginación: la paginación con cursor (recomendada) y la paginación por desplazamiento.

La paginación con cursor es el enfoque moderno y funciona siguiendo los enlaces "siguiente" en la respuesta de la API. Es más eficiente para grandes conjuntos de datos y no tiene las restricciones de límite de página de la paginación por desplazamiento.

Para utilizar la paginación con cursor, añada ?page[size]=100 a su solicitud (100 es el máximo). Aquí hay una implementación completa de Python que recupera TODOS los artículos a través de todas las páginas:

import requests
from requests.auth import HTTPBasicAuth

def get_all_articles(subdomain, email, api_token):
    articles = []
    url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'

    while url:
        response = requests.get(
            url,
            auth=HTTPBasicAuth(f'{email}/token', api_token),
            headers={'Content-Type': 'application/json'}
        )

        if response.status_code != 200:
            print(f"Error: {response.status_code}")
            break

        data = response.json()
        articles.extend(data['articles'])

        # Get the next page URL from the links object
        url = data.get('links', {}).get('next')

        print(f"Retrieved {len(articles)} articles so far...")

    return articles

all_articles = get_all_articles('your_subdomain', 'your_email', 'your_token')
print(f"Total articles: {len(all_articles)}")

La clave es comprobar data['links']['next']. Cuando llegue a la página final, este valor será null y su bucle terminará.

La paginación por desplazamiento es el método más antiguo y está limitado a un máximo de 100 páginas. Utiliza los parámetros per_page y page. Zendesk recomienda la paginación con cursor para las nuevas implementaciones.

Cuando pagine a través de grandes conjuntos de datos, tenga en cuenta los límites de velocidad. Si tiene miles de artículos, considere la posibilidad de añadir un pequeño retraso entre las solicitudes:

import time

time.sleep(0.5)  # 500ms delay

Paso 4: filtrar y ordenar artículos

La API ofrece varias formas de filtrar y ordenar sus listados de artículos.

Filtrado por etiquetas: Si utiliza etiquetas de artículo (disponibles en los planes Professional y Enterprise), puede filtrar por ellas:

GET /api/v2/help_center/articles?label_names=photos,camera

Esto devuelve solo los artículos que tienen TODAS las etiquetas especificadas. La coincidencia de etiquetas distingue entre mayúsculas y minúsculas.

Ordenación: Utilice los parámetros sort_by y sort_order para controlar el orden:

Ejemplo: /api/v2/help_center/articles?sort_by=updated_at&sort_order=desc

Exportaciones incrementales: Para sincronizar artículos con sistemas externos, utilice el punto final incremental con un parámetro start_time:

GET /api/v2/help_center/incremental/articles?start_time=1704067200

El start_time es una marca de tiempo de la época de Unix. Esto devuelve solo los artículos creados o actualizados desde ese momento.

Listado por categoría o sección: Para obtener artículos de una categoría específica:

GET /api/v2/help_center/categories/{category_id}/articles

O de una sección específica:

GET /api/v2/help_center/sections/{section_id}/articles

Carga lateral de datos relacionados: Para reducir las llamadas a la API, puede cargar lateralmente los recursos relacionados:

GET /api/v2/help_center/articles?include=users,sections,categories

Esto incluye los objetos completos de usuario, sección y categoría en la respuesta, por lo que no necesita realizar llamadas API separadas para esa información.

Casos de uso comunes y ejemplos de código

Aquí hay algunas implementaciones prácticas para escenarios comunes:

Exportar todos los artículos para la indexación de búsqueda: Este script exporta todos los artículos publicados a un archivo JSON, filtrando los borradores e incluyendo solo los campos esenciales:

import json
import requests
from requests.auth import HTTPBasicAuth

def export_articles_for_search(subdomain, email, api_token, output_file):
    articles = []
    url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'

    while url:
        response = requests.get(url, auth=HTTPBasicAuth(f'{email}/token', api_token))
        data = response.json()

        for article in data['articles']:
            if not article['draft']:
                articles.append({
                    'id': article['id'],
                    'title': article['title'],
                    'body': article['body'],
                    'url': article['html_url'],
                    'updated_at': article['updated_at']
                })

        url = data.get('links', {}).get('next')

    with open(output_file, 'w') as f:
        json.dump(articles, f, indent=2)

    print(f"Exported {len(articles)} articles to {output_file}")

Mejores prácticas de manejo de errores: Siempre maneje los posibles errores en sus llamadas a la API:

response = requests.get(url, auth=auth)

if response.status_code == 429:
    # Rate limit hit   wait and retry
    time.sleep(60)
    response = requests.get(url, auth=auth)
elif response.status_code == 401:
    print("Authentication failed   check your API token")
    sys.exit(1)
elif response.status_code != 200:
    print(f"API error: {response.status_code}")
    print(response.text)

Gestión del contenido de Zendesk Guide con eesel AI

Si bien la API de Zendesk Guide le brinda acceso programático al contenido de su centro de ayuda, eesel AI es donde entra en juego la gestión y el aprovechamiento eficaz de ese contenido.

En lugar de construir scripts personalizados para sincronizar artículos, nuestro agente de IA se conecta directamente a su Zendesk Guide y aprende del contenido de su centro de ayuda automáticamente. Esto significa:

• Configuración sin código conecte su cuenta de Zendesk y eesel AI importa sus artículos automáticamente
• Siempre actualizado cuando actualiza los artículos en Zendesk, eesel AI aprende los cambios
• Soporte multi-idioma funciona con artículos en cualquiera de los más de 80 idiomas que soporta Zendesk
• Respuestas inteligentes nuestra IA responde a las preguntas de los clientes utilizando el contenido de su centro de ayuda como fuente de verdad

Para los equipos que buscan construir soporte impulsado por IA sin la sobrecarga de ingeniería, eesel AI maneja la complejidad de sincronizar, indexar y recuperar el contenido del artículo correcto en el momento adecuado. Puede comenzar con AI Copilot para redactar respuestas para sus agentes, luego subir de nivel a la automatización completa de AI Agent a medida que gane confianza.

Empiece a construir con la API de Zendesk Guide hoy mismo

Ahora tiene todo lo que necesita para empezar a trabajar con la API de Zendesk Guide. Aquí tiene un breve resumen:

1. Genere un token de API desde su Centro de administración de Zendesk
2. Realice solicitudes autenticadas utilizando la autenticación básica con su correo electrónico y token
3. Maneje la paginación utilizando la paginación con cursor para grandes bibliotecas de artículos
4. Filtre y ordene utilizando los parámetros de consulta para obtener exactamente los datos que necesita

Para funciones más avanzadas como la creación o actualización de artículos, la gestión de traducciones o el trabajo con archivos adjuntos de artículos, consulte la documentación oficial de la API de Zendesk.

Y si está buscando hacer más con el contenido de su centro de ayuda, como impulsar las respuestas de la IA, construir una búsqueda personalizada o crear flujos de trabajo automatizados, considere cómo eesel AI puede ayudarle a llegar más rápido sin escribir código de integración personalizado.