La API REST Notiondesk permite que tu propio código gestione tus centros de ayuda. Puedes listar tus centros de ayuda, leer sus artículos, colecciones y el registro de cambios, gestionar las redirecciones de página, modificar la configuración y la imagen de marca, obtener análisis y comentarios de los lectores, y activar sincronizaciones desde Notion.
Este artículo explica qué puede hacer la API Notiondesk, quién puede usarla y cómo realizar su primera solicitud en pocos minutos.
Qué puedes hacer con la API Notiondesk
| Tarea | Ejemplo | Guía |
|---|---|---|
| Consulta tus centros de ayuda | Enumera todos los centros de ayuda de tu espacio de trabajo y sus idiomas. | Consulta tus centros de ayuda |
| Leer contenido | Exporta todos los artículos como Markdown o lista las entradas de tu registro de cambios. | Lee artículos, colecciones y entradas del registro de cambios. |
| Publicar cambios en Notion | Sincroniza tu centro de ayuda desde una canalización de CI después de editar Notion. | Activar la sincronización de Notion |
| Gestionar redirecciones | Importar cientos de redirecciones después de migrar desde otro centro de ayuda | Gestionar redirecciones de página |
| Cambiar de idioma | Añade un idioma o activa la traducción automática. | Gestionar idiomas y traducción automática |
| Cambiar configuración | Actualizar los títulos SEO, llms.txt, el formulario de contacto o el registro de cambios. | Actualizar la configuración del centro de ayuda |
| Cambio de marca | Aplica los colores y el tema de tu marca a varios centros de ayuda. | Personaliza la imagen de marca y los temas. |
| Gestionar integraciones | Configura Google Analytics, Plausible, Intercom o Crisp. | Gestionar integraciones |
| Análisis de extracción | Envía visitantes, búsquedas y artículos principales a tu herramienta de BI. | Obtenga análisis del centro de ayuda |
| Leer comentarios | Envía cada mañana las reacciones negativas a los artículos a Slack. | Exportar comentarios de los lectores |
Para obtener scripts listos para usar, consulte Automatizar tareas comunes del centro de ayuda con la API Notiondesk .
¿Quién puede usar la API Notiondesk?
- Plan: El acceso a la API está incluido en los planes Enterprise.
- Creación de claves: Los propietarios y administradores del espacio de trabajo crean las claves API en el panel de control.
- Permisos: Una clave o una aplicación nunca puede hacer más de lo que la persona que la creó puede hacer en tu espacio de trabajo. Consulta Autenticación con la API Notiondesk mediante claves de API .
Realiza tu primera solicitud a la API Notiondesk
1. Crea una clave API.
En tu panel de control de Notiondesk, abre Configuración , luego Desarrolladores > Claves API y haz clic en Crear clave . Asígnale una etiqueta, selecciona el ámbito de lectura y copia la clave cuando aparezca. La clave comienza con nd_wsk_ y se muestra solo una vez.
Guárdalo en una variable de entorno:
2. Enumera tus centros de ayuda
La respuesta enumera todos los centros de ayuda de tu espacio de trabajo:
3. Enumera los artículos de un centro de ayuda.
¡Eso es! Estás leyendo tu centro de ayuda desde el código.
Conceptos básicos de la API
export NOTIONDESK_API_KEY="nd_wsk_..."curl "<https://api.notiondesk.so/sites>" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"object": "list",
"data": [
{
"id": "c74781f6-1aea-4e17-ab23-bbb8b4d174b6",
"full_domain": "help.example.com",
"enabled": true,
"default_locale": "en",
"locales": ["en", "fr"]
}
],
"has_more": false,
"next_cursor": null
}curl "<https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=10>" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"| Tema | Qué debes saber |
|---|---|
| URL base | https://api.notiondesk.so |
| Autenticación | Authorization: Bearer <key or access token>. Consulte las claves de API y OAuth. |
| Alcances | read, write, sync y admin. Cada ruta requiere uno |
| Control de versiones | Encabezado opcional nd-version |
| Formato | Cuerpos de solicitud y respuesta JSON con nombres de campo en formato snake_case. |
| Paginación | Basado en cursores: page_size (1 a 100, valor predeterminado 20) y cursor. Consulte las solicitudes de paginación y versión. |
| Errores | Un sobre JSON con un code legible por máquina. Consulte Manejo de errores, límites de velocidad y reintentos. |
¿API o MCP de Workspace?
Notiondesk ofrece dos maneras de operar sus centros de ayuda fuera del panel de control. Se accede a las mismas funciones a través de diferentes puertas.
| API REST Notiondesk | MCP de espacio de trabajo | |
|---|---|---|
| ¿Quién lo llama? | Tu código: scripts, pipelines de CI, herramientas internas, aplicaciones de socios | Un asistente de IA como Claude, ChatGPT, Cursor o VS Code |
| Cómo se inicia sesión | Una clave API del espacio de trabajo o un token de acceso OAuth. | OAuth, a través de su cliente de IA |
| Lo mejor para | Automatización repetible y determinista | Trabajo de conversación: "encuentra los artículos que no les gustan a los lectores y sugiere mejoras". |
Punto final de la API Notiondesk
| Método | Camino | Alcance | Guía |
|---|---|---|---|
GET | /sites | read | Centros de ayuda |
GET | /sites/{site_id} | read | Centros de ayuda |
GET | /sites/{site_id}/sync-status | read | Centros de ayuda |
GET | /sites/{site_id}/articles | read | Contenido |
GET | /sites/{site_id}/articles/{article_id} | read | Contenido |
GET | /sites/{site_id}/categories | read | Contenido |
GET | /sites/{site_id}/categories/{category_id} | read | Contenido |
GET | /sites/{site_id}/changelog | read | Contenido |
POST | /sites/{site_id}/sync | sync | Sincronizaciones |
POST | /sites/{site_id}/articles/{article_id}/sync | sync | Sincronizaciones |
POST | /sites/{site_id}/categories/{category_id}/sync | sync | Sincronizaciones |
PATCH | /sites/{site_id}/settings/auto-sync | sync | Sincronizaciones |
GET | /sites/{site_id}/page-redirects | read | Redirecciones |
POST | /sites/{site_id}/page-redirects | write | Redirecciones |
PATCH | /sites/{site_id}/page-redirects/{redirect_id} | write | Redirecciones |
DELETE | /sites/{site_id}/page-redirects/{redirect_id} | admin | Redirecciones |
PATCH | /sites/{site_id}/settings/supported-languages | write | Idiomas |
PATCH | /sites/{site_id}/settings/auto-translate | write | Idiomas |
PATCH | /sites/{site_id}/settings/content | write | Ajustes |
PATCH | /sites/{site_id}/settings/ai-optimization | write | Ajustes |
PATCH | /sites/{site_id}/settings/contact-form | write | Ajustes |
PATCH | /sites/{site_id}/settings/changelog | write | Ajustes |
GET | /sites/{site_id}/settings/customize | read | Herrada |
PATCH | /sites/{site_id}/settings/customize | admin | Herrada |
GET | /sites/{site_id}/themes | read | Herrada |
GET | /sites/{site_id}/integrations | read | Integraciones |
PATCH | /sites/{site_id}/integrations/{type} | admin | Integraciones |
POST | /sites/{site_id}/integrations/{type}/disable | admin | Integraciones |
GET | /sites/{site_id}/analytics/{report} | read | Analítica |
GET | /sites/{site_id}/feedback | read | Comentario |
Preguntas frecuentes
¿Puedo crear o editar artículos con la API Notiondesk?
No. Los artículos, las colecciones y las entradas del registro de cambios se escriben en Notion, y cada sincronización sobrescribe lo que almacena Notiondesk. Edita la página de Notion con el editor de Notion o la API de Notion y, a continuación, activa la sincronización para publicar el cambio.
¿Una sola clave API sirve para todos mis centros de ayuda?
Sí. Una clave API de espacio de trabajo funciona para todos los centros de ayuda en su espacio de trabajo. Cada solicitud especifica el centro de ayuda en su ruta, por ejemplo, /sites/{site_id}/articles.
¿Dónde puedo encontrar el site_id de un centro de ayuda?
site_id de un centro de ayuda?Llama a GET /sites para ver la lista de centros de ayuda con su id. También es el identificador que aparece después de /s/ en la barra de direcciones de tu panel de control.