zendesk-guide-knowledge-base-api
eesel Team
Last edited 26 febrero 2026
{
"title": "API de la base de conocimientos de Zendesk Guide: La guía completa para desarrolladores para 2026",
"slug": "zendesk-guide-knowledge-base-api",
"locale": "es",
"date": "2026-02-25",
"updated": "2026-02-25",
"template": "default",
"excerpt": "Una guía técnica completa de la API del Centro de Ayuda de Zendesk con ejemplos de código funcional, patrones de autenticación y las mejores prácticas de integración para desarrolladores.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk API",
"Knowledge Base",
"Help Center API",
"Developer Guide",
"Customer Support"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "API de la base de conocimientos de Zendesk Guide: La guía completa para desarrolladores para 2026",
"description": "Una guía técnica completa de la API del Centro de Ayuda de Zendesk con ejemplos de código funcional, patrones de autenticación y las mejores prácticas de integración para desarrolladores.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-3923a02a-382e-4c4c-a4bb-d10f99180563",
"coverImageAlt": "Imagen del banner para la API de la base de conocimientos de Zendesk Guide: La guía completa para desarrolladores para 2026",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas Frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Qué método de autenticación debo usar para la API de la base de conocimientos de Zendesk Guide?",
"answer": "Para scripts del lado del servidor e integraciones de backend, use la autenticación de token de API. Es más sencillo de implementar y administrar. Para aplicaciones del lado del cliente o cuando necesite actuar en nombre de usuarios individuales, use OAuth 2.0. OAuth admite CORS, lo que lo hace adecuado para aplicaciones basadas en navegador."
},
{
"question": "¿Cómo manejo la paginación al obtener todos los artículos a través de la API de la base de conocimientos de Zendesk Guide?",
"answer": "Use la paginación basada en cursor agregando `?page[size]=100` a su solicitud. Siga la URL `links.next` en la respuesta hasta que `meta.has_more` sea falso. Este método es más rápido que la paginación de desplazamiento y no tiene un límite de 10,000 registros."
},
{
"question": "¿Cuáles son los límites de velocidad para la API de la base de conocimientos de Zendesk Guide?",
"answer": "Los límites de velocidad varían según el plan: Suite Team obtiene 200 solicitudes/minuto, Growth y Professional obtienen 400/minuto, Enterprise obtiene 700/minuto y Enterprise Plus obtiene 2,500/minuto. Si alcanza el límite, la API devuelve un estado 429 con un encabezado `Retry-After`."
},
{
"question": "¿Puedo usar la API de la base de conocimientos de Zendesk Guide para sincronizar contenido con sistemas de IA externos?",
"answer": "Sí. Puede extraer artículos a través de la API, convertir el contenido HTML a su formato preferido (Markdown, texto sin formato) y alimentarlo a bases de datos vectoriales o sistemas RAG. Alternativamente, las plataformas de integración como eesel AI pueden manejar esta sincronización automáticamente."
},
{
"question": "¿Cuál es la diferencia entre la API del Centro de Ayuda de Zendesk y la API de la base de conocimientos de Zendesk Guide?",
"answer": "Son lo mismo. 'API del Centro de Ayuda' es el nombre oficial en la documentación de Zendesk, mientras que 'API de la base de conocimientos de Guide' es un nombre alternativo común que enfatiza su conexión con el producto Zendesk Guide. Ambos se refieren a la API REST en `/api/v2/help_center/`."
}
],
"supportLink": null
}
}
---
Si está creando integraciones con Zendesk o buscando administrar programáticamente el contenido de su base de conocimientos, la [API del Centro de Ayuda de Zendesk](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) (a menudo llamada API de la base de conocimientos de Zendesk Guide) es su puerta de entrada. Ya sea que necesite sincronizar artículos con un sistema de búsqueda externo, crear una solución de copia de seguridad o alimentar contenido en una base de conocimientos de IA, esta API REST proporciona las herramientas para hacerlo.
Analicemos cómo funciona y cómo usarla de manera efectiva.
## ¿Qué es la API de la base de conocimientos de Zendesk Guide?
La [API del Centro de Ayuda de Zendesk](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/) es una API REST que le permite administrar programáticamente el contenido en su base de conocimientos de Zendesk Guide. Es parte del ecosistema de API más amplio de Zendesk y utiliza JSON tanto para las solicitudes como para las respuestas.
Esto es lo que puede hacer con ella:
- **Leer contenido**: obtenga artículos, secciones y categorías para uso externo
- **Escribir contenido**: cree, actualice y archive artículos programáticamente
- **Administrar traducciones**: gestione contenido multilingüe a escala
- **Buscar y filtrar**: encuentre contenido específico utilizando etiquetas, fechas y otros criterios
La API sigue las convenciones REST estándar. Su URL base se ve así: `https://{su-subdominio}.zendesk.com/api/v2/help_center/`, y todas las respuestas se filtran de acuerdo con los permisos del usuario que realiza la solicitud. Esto significa que los usuarios anónimos solo ven contenido público, mientras que los agentes pueden acceder a artículos internos según sus permisos.
## Primeros pasos con la autenticación
Antes de que pueda realizar cualquier llamada a la API, necesita autenticarse. Zendesk ofrece dos métodos principales: tokens de API y OAuth 2.0.
### Autenticación de token de API (recomendada para scripts del lado del servidor)
Los tokens de API son la forma más sencilla de comenzar. Los genera en su Centro de administración de Zendesk en **Aplicaciones e integraciones > API > API de Zendesk**.
| Atributo | Detalle |
|-----------|--------|
| Límite de tokens | 256 por cuenta (hasta 2,048 para cuentas más grandes) |
| Formato | `{dirección_de_correo_electrónico}/token:{token_de_api}` |
| Encabezado | `Authorization: Basic {credenciales_codificadas_en_base64}` |
Así es como se ve en la práctica:
```bash
curl https://su-dominio.zendesk.com/api/v2/help_center/articles.json \
-u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv
El indicador -u en cURL maneja automáticamente la codificación Base64 por usted. Si está construyendo el encabezado manualmente en el código, combine su correo electrónico y token con dos puntos, codifique el resultado en Base64 y agréguelo al encabezado de Autorización.
OAuth 2.0 (para aplicaciones orientadas al usuario)
Si está creando una aplicación del lado del cliente o necesita actuar en nombre de usuarios individuales, OAuth es la mejor opción. Utiliza tokens Bearer:
curl https://su-dominio.zendesk.com/api/v2/help_center/articles.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
La ventaja clave aquí es que OAuth admite CORS, lo que lo hace adecuado para aplicaciones basadas en navegador. Los tokens de API no admiten CORS y están limitados al uso del lado del servidor.
Nota de seguridad: Todas las conexiones deben usar TLS 1.2 o superior. Almacene sus tokens de forma segura y nunca los envíe al control de versiones.
Puntos finales y operaciones principales de la API
La API del Centro de Ayuda está organizada en torno a tres tipos de contenido principales: categorías, secciones y artículos. Piense en ello como una jerarquía: las categorías contienen secciones y las secciones contienen artículos.
Trabajar con artículos
El punto final de los artículos es donde pasará la mayor parte de su tiempo. Aquí están las operaciones clave:
Listar todos los artículos:
GET /api/v2/help_center/articles.json
Esto devuelve una lista paginada de artículos. Puede filtrar los resultados utilizando parámetros de consulta:
| Parámetro | Propósito | Ejemplo |
|---|---|---|
label_names | Filtrar por etiquetas | ?label_names=faq,billing |
sort_by | Campo de ordenación | ?sort_by=updated_at |
sort_order | Dirección de ordenación | ?sort_order=desc |
start_time | Exportación incremental | ?start_time=1704067200 |
Obtener un artículo específico:
GET /api/v2/help_center/articles/{article_id}.json
Crear un artículo:
POST /api/v2/help_center/sections/{section_id}/articles.json
Los campos obligatorios incluyen title (título), locale (localización) y permission_group_id (ID del grupo de permisos). También puede establecer campos opcionales como body (contenido HTML), author_id (ID del autor), label_names (nombres de etiquetas) y el estado draft (borrador).
Actualizar un artículo:
PUT /api/v2/help_center/articles/{article_id}.json
Archivar un artículo:
DELETE /api/v2/help_center/articles/{article_id}.json
Puntos finales de la jerarquía de contenido
| Punto final | Propósito |
|---|---|
GET /api/v2/help_center/categories.json | Listar todas las categorías |
GET /api/v2/help_center/categories/{id}/sections.json | Listar las secciones en una categoría |
GET /api/v2/help_center/sections.json | Listar todas las secciones |
GET /api/v2/help_center/sections/{id}/articles.json | Listar los artículos en una sección |
Carga lateral de datos relacionados
Una característica útil es la carga lateral, que le permite incluir datos relacionados en una sola solicitud. Agregue ?include=users,sections,categories a su solicitud de artículos, y la respuesta incluirá objetos completos para autores, secciones y categorías en lugar de solo ID.
Manejo eficiente de la paginación
La paginación es donde muchos desarrolladores se topan con su primer obstáculo. La API del Centro de Ayuda admite dos métodos de paginación, y elegir el correcto es importante.
Paginación basada en cursor (recomendada)
La paginación con cursor es el enfoque moderno y funciona significativamente mejor con grandes conjuntos de datos. Para usarla, agregue page[size] a su solicitud:
GET /api/v2/help_center/articles.json?page[size]=100
La respuesta incluye un objeto meta con un booleano has_more y un objeto links con URL next y prev:
{
"articles": [...],
"meta": {
"has_more": true
},
"links": {
"next": "https://.../articles.json?page[size]=100&page[after]=xxx",
"prev": null
}
}
Siga la URL next hasta que has_more sea falso. Aquí hay un ejemplo de Python:
import requests
from base64 import b64encode
def fetch_all_articles(subdomain, email, token):
base_url = f"https://{subdomain}.zendesk.com/api/v2/help_center/articles.json"
credentials = b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {credentials}"}
articles = []
url = f"{base_url}?page[size]=100"
while url:
response = requests.get(url, headers=headers)
data = response.json()
articles.extend(data["articles"])
url = data["links"]["next"] if data["meta"]["has_more"] else None
return articles
Paginación basada en desplazamiento (heredada)
La paginación de desplazamiento todavía funciona, pero tiene limitaciones. A partir de agosto de 2023, no puede recuperar más de 10,000 registros (100 páginas) utilizando este método. Si lo intenta, obtendrá un error 400 Bad Request.
GET /api/v2/help_center/articles.json?per_page=100&page=2
La respuesta incluye URL next_page y previous_page. Deténgase cuando next_page sea nulo.
En resumen: Use la paginación con cursor para las nuevas integraciones. Es más rápida, más confiable y no tiene límites estrictos.
Patrones de integración comunes
Ahora que comprende los conceptos básicos, veamos cómo los desarrolladores suelen usar esta API en producción.
Indexación de búsqueda externa
Un caso de uso común es indexar sus artículos de Zendesk en un motor de búsqueda externo como Elasticsearch o Algolia. El patrón se ve así:
- Obtenga todos los artículos utilizando la paginación con cursor
- Transforme el cuerpo HTML a texto sin formato (elimine las etiquetas)
- Indexe el ID del artículo, el título, el texto del cuerpo y la URL
- Configure una sincronización periódica utilizando el parámetro
start_timepara actualizaciones incrementales
La clave es preservar la URL del artículo original en su índice para que los resultados de búsqueda puedan vincularse a Zendesk.
Copia de seguridad y migración de contenido
Para los flujos de trabajo de copia de seguridad, es posible que desee exportar toda su base de conocimientos:
- Itere a través de todas las categorías
- Para cada categoría, obtenga sus secciones
- Para cada sección, obtenga sus artículos
- Guarde los objetos de artículo completos (incluido el cuerpo HTML) en su almacenamiento de copia de seguridad
Esto preserva su jerarquía de contenido y facilita la restauración.
Integración de sistemas de IA y RAG
Un caso de uso creciente es alimentar el contenido de Zendesk en sistemas de Generación Aumentada por Recuperación (RAG) para soporte impulsado por IA. El flujo de trabajo generalmente implica:
- Extraer artículos a través de la API
- Convertir HTML a Markdown o texto sin formato
- Dividir el contenido en fragmentos para el almacenamiento vectorial
- Preservar la URL original para las citas
Aquí es donde herramientas como eesel AI pueden ayudar. En lugar de construir canalizaciones ETL personalizadas, puede conectar su cuenta de Zendesk directamente y tener un agente de IA que responda preguntas utilizando el contenido de su base de conocimientos, completo con citas a los artículos originales.
Límites de velocidad y mejores prácticas
Comprender los límites de velocidad evita que su integración se tope con muros a escala.
Límites de solicitud por plan
| Plan | Límite de la API de Soporte/Centro de Ayuda |
|---|---|
| Suite Team | 200 solicitudes/minuto |
| Suite Growth | 400 solicitudes/minuto |
| Suite Professional | 400 solicitudes/minuto |
| Suite Enterprise | 700 solicitudes/minuto |
| Suite Enterprise Plus | 2,500 solicitudes/minuto |
Fuente: Documentación de los límites de velocidad de Zendesk
Manejo de errores de límite de velocidad
Cuando excede el límite, la API devuelve un código de estado 429 con un encabezado Retry-After que indica cuántos segundos esperar. Su código debería:
- Comprobar las respuestas 429
- Extraer el valor
Retry-After - Espere esa cantidad de segundos antes de volver a intentarlo
- Considere la posibilidad de implementar una retirada exponencial para los fallos repetidos
Aquí hay un simple decorador de reintento en Python:
import time
import requests
from functools import wraps
def with_rate_limit_retry(func):
@wraps(func)
def wrapper(*args, **kwargs):
max_retries = 3
for attempt in range(max_retries):
response = func(*args, **kwargs)
if response.status_code != 429:
return response
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
raise Exception("Rate limit exceeded after retries")
return wrapper
@with_rate_limit_retry
def api_call(url, headers):
return requests.get(url, headers=headers)
Consejos de rendimiento
- Use la paginación con cursor: es más rápida y no tiene un límite de 10,000 registros
- Habilite la carga lateral: obtenga datos relacionados en una solicitud en lugar de realizar varias llamadas
- Almacene en caché de forma agresiva: el contenido del artículo no cambia con tanta frecuencia
- Use exportaciones incrementales: el parámetro
start_timele permite obtener solo el contenido modificado
Enfoques alternativos a considerar
Construir una integración de API personalizada no siempre es la opción correcta. Aquí hay un marco rápido para decidir:
Use la API directamente cuando:
- Necesita un control completo sobre la transformación de datos
- Tiene recursos de ingeniería dedicados
- Su caso de uso es único o complejo
Use las funciones nativas de Zendesk cuando:
- Solo desea mostrar contenido externo en la búsqueda: use la búsqueda federada
- Necesita una gestión básica de contenido: use la interfaz de usuario integrada
Use una plataforma de integración cuando:
- Desea respuestas impulsadas por IA sin construir canalizaciones RAG
- Necesita una configuración rápida sin recursos de ingeniería
- Desea una sincronización continua sin gastos generales de mantenimiento
Aquí es donde encaja eesel AI. En lugar de escribir scripts personalizados para extraer, transformar y sincronizar su contenido de Zendesk, puede conectar su cuenta en minutos y obtener un compañero de equipo de IA que responda las preguntas de los clientes utilizando su base de conocimientos. Maneja la integración de la API, la indexación de contenido y la generación de respuestas, lo que le permite concentrarse en un trabajo de mayor valor.
Construya potentes integraciones de conocimiento con Zendesk
La API del Centro de Ayuda de Zendesk le brinda los componentes básicos para crear flujos de trabajo sofisticados de gestión del conocimiento. Ya sea que esté construyendo un índice de búsqueda personalizado, migrando contenido entre sistemas o alimentando artículos en plataformas de IA, comprender la autenticación, la paginación y los límites de velocidad lo prepara para el éxito.
Comience poco a poco: obtenga una lista de artículos, experimente con la paginación y luego construya integraciones más complejas. Y si se encuentra dedicando más tiempo a mantener las canalizaciones de datos que a resolver problemas comerciales, considere si una plataforma de integración podría ser una mejor opción.
Si está buscando mejorar su configuración de Zendesk con capacidades de IA, eesel AI ofrece una integración directa que convierte su base de conocimientos en un agente de soporte inteligente. No se requiere desarrollo de API personalizado.
Compartir esta entrada
Article by
