Gestión de contenido de la API de Zendesk Guide: Una guía completa para desarrolladores

Gestionar el contenido del centro de ayuda a escala se vuelve tedioso cuando se hace manualmente. Ya sea que esté migrando artículos desde otra plataforma, sincronizando activos de su equipo de marketing u organizando contenido en varias marcas, la API de Zendesk Guide le brinda control programático sobre su base de conocimientos.

Esta guía lo guiará a través de todo lo que necesita saber sobre la gestión de contenido de la API de Zendesk Guide. Cubriremos la autenticación, los puntos de conexión centrales, los patrones de implementación prácticos y cuándo tiene sentido usar la API frente a alternativas como eesel AI.

Lo que necesitará

Antes de sumergirse, asegúrese de tener:

• Una cuenta de Zendesk con Guide habilitado (plan Suite Team o superior)
• Acceso de administrador para generar tokens de API
• Familiaridad básica con las API REST y JSON
• Su cliente HTTP preferido (cURL, Postman o un lenguaje de programación como Python)

Comprender la autenticación de la API de Zendesk Guide

La API de Zendesk Guide utiliza los mismos patrones de autenticación que otras API de Zendesk. Esto es lo que necesitará saber.

Autenticación de token de API (recomendada)

Los tokens de API son la forma más sencilla de autenticarse. Los generará en el Centro de administración en Aplicaciones e integraciones > API > API de Zendesk.

Detalles importantes:

• Formatee sus credenciales como {dirección_de_correo_electrónico}/token:{api_token}
• Codifique en Base64 toda la cadena para el encabezado de Autorización
• Puede tener hasta 256 tokens activos (2048 para cuentas heredadas)
• Los tokens pueden suplantar a cualquier usuario, incluidos los administradores, así que manténgalos seguros

Ejemplo de solicitud cURL:

curl https://{subdominio}.zendesk.com/api/v2/guide/medias \
  -v -u {dirección_de_correo_electrónico}/token:{api_token}

OAuth para aplicaciones de múltiples clientes

Si está creando una integración que se distribuirá a múltiples clientes de Zendesk, deberá usar OAuth en lugar de tokens de API. Los tokens de API regulares no funcionarán para las aplicaciones que necesitan autenticarse en diferentes instancias de Zendesk.

Límites de velocidad y SSL

La mayoría de los puntos de conexión permiten 700 solicitudes por minuto. Si alcanza el límite, obtendrá un código de estado 429. Todas las solicitudes deben usar HTTPS con TLS 1.2 o superior.

Puntos de conexión centrales de gestión de contenido

La API de Guide ofrece varios puntos de conexión para administrar diferentes tipos de contenido. Analicemos los más útiles.

API de Medios de Guide

La API de Medios de Guide gestiona las cargas de archivos y la gestión de medios para su centro de ayuda de Zendesk. Esto es esencial cuando desea agregar imágenes o archivos adjuntos a los artículos mediante programación.

El proceso de carga de 3 pasos:

1. Solicitar una URL de carga POST a /api/v2/guide/medias/upload_url con el tipo de contenido y el tamaño del archivo
2. Cargar el archivo PUT el archivo a la URL firmada devuelta en el paso 1
3. Crear el objeto multimedia POST a /api/v2/guide/medias con el ID de carga del activo

Los archivos pueden tener hasta 20 MB. La API utiliza identificadores basados en ULID, que se pueden ordenar a diferencia de los UUID tradicionales.

Ejemplo de Python:

import requests
import base64

auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}

upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
    json=upload_data,
    headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]

media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
    json=media_data,
    headers=headers
)

API de Etiquetas de Contenido

Las etiquetas de contenido le ayudan a organizar artículos y publicaciones. La API de Etiquetas de Contenido le permite crear, actualizar y administrar etiquetas mediante programación.

Capacidades clave:

• Crear y administrar etiquetas con solicitudes POST/PUT/DELETE
• Operaciones por lotes a través de /api/v2/guide/content_tags/jobs (eliminar o fusionar etiquetas)
• Filtrar etiquetas por prefijo de nombre
• Ordenar por ID o nombre en orden ascendente o descendente

Las operaciones por lotes son útiles para las tareas de limpieza, como fusionar etiquetas duplicadas o eliminar las obsoletas en toda su base de conocimientos.

API de Contenido Dinámico

Si admite varios idiomas, la API de Contenido Dinámico es esencial. Administra las variantes de contenido localizado utilizando marcadores de posición como {{dc.password_reset_instructions}}.

Cómo funciona:

• Cada elemento de contenido dinámico tiene una configuración regional predeterminada y múltiples variantes
• Las variantes contienen el texto traducido real
• Zendesk sirve automáticamente la variante correcta según la configuración regional del usuario
• Vuelve al valor predeterminado si no existe ninguna variante coincidente

Nota: El contenido dinámico requiere un plan Professional o superior.

API de Fuentes de Contenido Externo

La API de Fuentes de Contenido Externo habilita la búsqueda federada, lo que le permite extraer resultados de sistemas externos en la búsqueda de su centro de ayuda.

Casos de uso:

• Indexar contenido de un sistema de gestión del aprendizaje
• Incluir publicaciones de foros en los resultados de búsqueda
• Hacer que los problemas de Jira se puedan buscar desde el centro de ayuda

Esto requiere permisos de administrador del Centro de ayuda y funciona con el rastreador de Zendesk para indexar contenido externo.

Implementación práctica: Automatización de cargas de medios

Veamos un escenario del mundo real. Su equipo de marketing crea capturas de pantalla en Figma y las guarda en Google Drive. Desea que estos se agreguen automáticamente a su galería de medios de Zendesk para que los escritores puedan usarlos en los artículos.

Aquí hay una implementación completa de Python:

import requests
import base64
import time

class ZendeskMediaUploader:
    def __init__(self, subdomain, email, token):
        self.subdomain = subdomain
        self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
        self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
        self.headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }

    def upload_file(self, file_path, content_type):
        """Upload a file to Zendesk media gallery."""
        file_size = os.path.getsize(file_path)
        filename = os.path.basename(file_path)

        # Step 1: Get upload URL
        upload_data = {"content_type": content_type, "file_size": file_size}
        resp = requests.post(
            f"{self.base_url}/guide/medias/upload_url",
            json=upload_data,
            headers=self.headers
        )
        resp.raise_for_status()

        upload_info = resp.json()["upload_url"]

        # Step 2: Upload file to signed URL
        with open(file_path, "rb") as f:
            put_headers = {
                "Content-Disposition": upload_info["headers"]["Content-Disposition"],
                "Content-Type": content_type,
                "X-Amz-Server-Side-Encryption": "AES256"
            }
            put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
            put_resp.raise_for_status()

        # Step 3: Create media object
        media_data = {
            "asset_upload_id": upload_info["asset_upload_id"],
            "filename": filename
        }
        media_resp = requests.post(
            f"{self.base_url}/guide/medias",
            json=media_data,
            headers=self.headers
        )
        media_resp.raise_for_status()

        return media_resp.json()["media"]

Consejos para el manejo de errores:

• 401 No autorizado: Verifique su token y el formato del correo electrónico (debe incluir /token)
• 403 Prohibido: Verifique que tenga permisos de administrador de Guide
• 409 Conflicto: Reintente la solicitud (error transitorio)
• 429 Límite de velocidad: Implemente retroceso exponencial

Cuándo usar la API de Zendesk Guide frente a alternativas

La API no siempre es la opción correcta. Aquí es cómo decidirá.

Use la API cuando:

• Necesita migrar grandes cantidades de contenido desde otra plataforma
• Está creando una integración personalizada con sus herramientas existentes
• Desea automatizar tareas repetitivas (como el etiquetado masivo)
• Tiene recursos de desarrollador disponibles para el mantenimiento continuo

Considere las características nativas de Zendesk cuando:

• Solo necesita cargas manuales ocasionales
• Su equipo se siente cómodo trabajando en la interfaz de Zendesk
• La búsqueda federada satisface sus necesidades de contenido externo sin código

Considere las plataformas de integración cuando:

• Necesita una automatización simple sin código personalizado
• Su caso de uso se ajusta a los desencadenadores y acciones estándar
• Desea algo que se ejecute rápidamente sin tiempo de desarrollo

Considere eesel AI cuando:

Es posible que desee echar un vistazo a eesel AI si su objetivo es hacer que su base de conocimientos de Zendesk sea más inteligente sin crear integraciones personalizadas. En lugar de escribir scripts para sincronizar contenido, eesel se conecta directamente a Zendesk, Confluence, Google Docs y otras fuentes.

Aquí está la diferencia: la API de Guide le permite mover contenido a Zendesk mediante programación. eesel AI indexa su contenido donde vive y lo hace accesible a su equipo de soporte a través de un Agente de IA que funciona dentro de Zendesk. No migra nada. No escribe código. Conecta sus fuentes y la IA aprende de ellas.

Para los equipos sin desarrolladores dedicados, este puede ser un camino más rápido hacia el conocimiento unificado. Nuestros precios comienzan en $299/mes para el plan Team, que incluye hasta 3 bots y 1,000 interacciones de IA.

Mejores prácticas y solución de problemas

Seguridad

• Almacene los tokens de API en variables de entorno, nunca en su código
• Rote los tokens regularmente (Zendesk le permite tener hasta 256, por lo que puede crear nuevos antes de eliminar los antiguos)
• Use tokens separados para diferentes integraciones para que pueda revocar uno sin afectar a otros

Paginación

Los puntos de conexión de la lista devuelven resultados paginados. Use la paginación basada en cursor para conjuntos de datos grandes (es más confiable que la paginación de desplazamiento para cambiar los datos):

params = {"page[size]": 100}
while True:
    resp = requests.get(url, params=params, headers=headers)
    data = resp.json()

    # Process records
    for record in data["records"]:
        process(record)

    # Check for more pages
    if not data["meta"]["has_more"]:
        break
    params["page[after]"] = data["meta"]["after_cursor"]

Pruebas

• Pruebe en un entorno sandbox antes de ejecutarlo en producción
• Use la colección Postman de Zendesk para explorar los puntos de conexión
• Registre las respuestas de la API durante el desarrollo para comprender las condiciones de error

Errores comunes

• Olvidar el sufijo /token en la dirección de correo electrónico
• No codificar en Base64 las credenciales
• Alcanzar los límites de velocidad durante las operaciones masivas
• No manejar los conflictos 409 con lógica de reintento

Comience a administrar el contenido de Zendesk de manera más eficiente

La API de Zendesk Guide le brinda herramientas poderosas para la gestión de contenido a escala. Ya sea que esté automatizando las cargas de medios, organizando el contenido con etiquetas o creando soporte multilingüe, la API proporciona las primitivas que necesita.

Pero la creación de integraciones personalizadas no es el único camino. Si desea unificar sus fuentes de conocimiento sin escribir código, eesel AI ofrece una alternativa. Nuestro Agente de IA se conecta a Zendesk y aprende de su documentación existente dondequiera que viva, sin necesidad de migración.

La elección correcta depende de los recursos técnicos de su equipo y de sus necesidades específicas. Si tiene desarrolladores y requisitos únicos, la API de Guide es una base sólida. Si desea ponerse en marcha rápidamente con soporte impulsado por IA, explore lo que eesel AI puede hacer por su configuración de Zendesk.