--- title: "Empezando con la documentación de la API" slug: "getting-started-with-api-documentation" updated: 2026-09-29T08:31:46Z published: 2026-09-29T08:32:35Z canonical: "docs.document360.com/getting-started-with-api-documentation" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # Empezando con la documentación de la API Esta guía te guía para publicar tu primera API en Document360, desde la subida de tu archivo de especificaciones a un portal interactivo para desarrolladores en vivo. Al final de este artículo tendrás: - Una referencia de API generada a partir de tu especificación OpenAPI - Tus endpoints son visibles y navegables por los desarrolladores - La consola interactiva Try It! lista para pruebas en tiempo real de la API NOTA La documentación de la API está disponible en todos los planes de pago. Cada plan de pago incluye un espacio de trabajo de la API. Se pueden adquirir espacios de trabajo adicionales como complementos. --- ## Requisitos previos Antes de empezar, asegúrate de tener: - **Una suscripción a Document360**. - **Un archivo de especificación de API** en uno de estos formatos: OpenAPI 3.2, OpenAPI 3.1, OpenAPI 3.0, OpenAPI 2.0 o Postman Collection, ya sea como archivo local (JSON, YML o YML) o alojado en una URL de la que importarás. - **Acceso al portal de la base de conocimiento** con permisos para crear contenido. NOTA Si aún no tienes un archivo de especificaciones, aún puedes seguir esta guía usando el archivo API de la tienda de mascotas que proporciona Document360. Se te pedirá que lo uses durante la configuración. --- ## Navega al espacio de trabajo de documentación de la API 1. Inicia sesión en Document360 y abre tu proyecto en el portal de la Base de conocimientos. 2. En la barra de navegación izquierda, haz clic **en documentación** `{ }`de la API . Esto abre el espacio de trabajo dedicado de la API, separado de tu base de conocimiento estándar. 3. En la barra de navegación superior, haz clic en el **desplegable Crear** y selecciona **Nueva API.** Esto abre la ventana de referencia de Nueva API. ![The API documentation workspace in the Knowledge base portal with the Create dropdown open showing the New API option.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/API%20doc%20from%20portal.png) NOTA Puedes crear un máximo de 3 referencias API dentro de cada espacio de trabajo de API. --- ## Elige cómo importar tu especificación Document360 soporta dos formas de importar tu archivo de especificaciones: **la subida de archivos** y **la importación de URLs**. El flujo CI/CD no es un método de importación separado; es una forma de automatizar cualquiera de estos dos métodos para que tu documentación se actualice automáticamente cada vez que cambia tu especificación. | Método | Cuándo usarlo | Cómo funciona | | --- | --- | --- | | Carga de archivo | Tienes el archivo de especificaciones localmente como JSON, YAML o YML. | Sube el archivo directamente. Es mejor para empezar rápido o para actualizaciones poco frecuentes. | | Importación de URL | Tu especificación está alojada en una URL pública o interna estable. | Apunta Document360 a la URL. Puedes resincronizar manualmente desde la misma URL cada vez que cambie la especificación. | | Flujo CI/CD | Quieres que la documentación se actualice automáticamente en cada cambio de especificación. | Automatiza la subida de archivos o la importación de URLs a través de la CLI d360 en tu pipeline. Requiere Node.js. | --- ## Sube tu especificación ### Sube un archivo 1. En la ventana de referencia de la nueva API, selecciona la opción **de definición de la API de Subir** . 2. Haz clic **en Subir desde mi dispositivo** o arrastra y suelta tu archivo. Formatos compatibles: JSON, YAML, YML. 3. Document360 analiza el archivo y genera automáticamente la referencia de la API. Si se detectan advertencias, aparece una sección de Alertas y Advertencias — amplíala para revisarlas. Puedes ver los detalles completos más adelante en la sección de Registros. 4. Haz clic **en Nueva referencia de API** para continuar. ![The New API reference window with the Upload API definition option and the upload area.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/ways%20to%20add%20api.png) ### Importar desde una URL 1. En la ventana de referencia de la nueva API, selecciona la opción **Crear desde URL** y haz clic **en Siguiente**. 2. Introduce la URL que apunta a tu archivo de especificación de OpenAPI en el campo URL. 3. Document360 recoge y procesa la especificación. Si se detectan advertencias, estarán disponibles en la sección de Registros tras la importación. 4. Haz clic **en Añadir referencia API** para continuar. ### Utilizar el flujo CI/CD NOTA Esta opción requiere que Node.js se instale en tu sistema. 1. En la ventana de referencia de la nueva API, selecciona la opción **CI/CD Flow** . 2. Copia el comando CLI completo que aparece en la ventana. 3. En el comando copiado, sustituye el `--path` valor por el camino completo hacia tu archivo de especificación local o una URL válida que apunte a él. Por ejemplo: ``` --path=/Users/yourname/projects/api/openapi.yaml ``` O una URL: ``` --path=https://example.com/api/openapi.yaml ``` 1. Pega el comando actualizado en tu terminal y pulsa Enter. Document360 sube tu especificación y genera la documentación de la API. NOTA La primera línea del comando CLI (`npm install d360 -g`) instala la herramienta CLI de Document360. Solo necesitas ejecutarlo una vez. Si ya está instalado, puedes saltarte esa línea. Si regeneras tu clave API, debes actualizar el `--apiKey` valor en tu comando CLI antes de ejecutarlo de nuevo. La clave antigua dejará de ser válida. #### ¿No hay archivo de especificaciones? Usa la API de ejemplo de la tienda de animales Si no tienes un archivo de especificaciones listo, **selecciona Probar archivo de ejemplo de la API de la tienda de mascotas** cuando te lo pidan. Document360 creará automáticamente una referencia de API de ejemplo en modo borrador. Puedes explorarla y luego reemplazarla por tu propia especificación más adelante. --- ## Revisar alertas y advertencias Tras subir tu especificación, Document360 te muestra un resumen de cuántas categorías y artículos se crearon, junto con cualquier alerta o advertencia detectada en tu archivo. - **Las alertas y advertencias** significan que la especificación fue importada, pero algunos elementos pueden no mostrarse como se espera. Puedes revisar todos los detalles en la sección de Registros: ve a tu referencia de API, haz clic en el icono Más `(⋯)` y selecciona Registros. - **Los errores** significan que la importación falló. La causa más común es un formato de archivo no compatible o una URL inválida. Reemplaza el archivo o corrige la URL y vuelve a intentarlo. ## ![The import summary showing created categories and articles with the Alerts and Warnings section.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/view%20logs.png) ## Publica tu referencia de API Después de que tu especificación haya sido procesada correctamente: 1. Una ventana de confirmación muestra el número de categorías y artículos creados. Haz clic **en Publicar** para poner la referencia de la API activa. 2. Si quieres revisar el contenido antes de publicarlo, haz clic **en Cerrar**. Tu referencia de API se guarda en modo borrador y se ve en el panel de Categorías y Artículos. ![The confirmation window showing the number of categories and articles created, with the Publish button.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/review%20api%20and%20publish.png) NOTA El modo borrador es útil si quieres añadir contenido personalizado a artículos de endpoint individuales antes de hacerlos públicos. Cualquier contenido personalizado que añadas se conservará cuando regeneres o vuelvas a sincronizar tu documentación. --- ## Configura la autenticación para Try It! La consola Try It! permite a los desarrolladores probar tus endpoints API directamente desde la documentación. Para que funcione correctamente, el método de autenticación debe estar definido en tu especificación y configurado en Document360. Document360 soporta los siguientes métodos de autenticación: | Método | Cómo funciona | | --- | --- | | Autenticación básica | El nombre de usuario y la contraseña se transmiten en la cabecera de la solicitud. | | Ficha portadora | Un token generado tras iniciar sesión pasaba en la cabecera de Autorización. | | Clave API | Una clave única pasaba en las cabeceras de las solicitudes. | | OAuth2 | Soporta código de autorización, PKCE, credenciales de cliente y flujos implícitos. | | OpenID Connect | Extiende OAuth2 para añadir la verificación de identidad del usuario. | NOTA La consola Try It! soporta múltiples esquemas de seguridad simultáneamente, permitiendo probar endpoints que requieren métodos de autenticación combinados. ### OAuth2 y OpenID Connect: configuración adicional Al usar OAuth2 o OpenID Connect, se requieren dos ajustes: - **Redirigir URI** — Configura esto en tu proveedor OAuth como `domain/oauth`. Por ejemplo: `https://apidocs.yourdomain.com/oauth`. - **Renovación silenciosa** — Document360 actualiza automáticamente el token de autorización en segundo plano durante las sesiones activas de Prueba!, por lo que los usuarios no necesitan volver a autenticarse manualmente. NOTA Si el botón Pruébalo! no es visible en tu base de conocimientos, comprueba que tanto la variable servidor como la URL del servidor estén correctamente definidas en tu archivo de especificación de la API. Sin esto, la función Pruébalo! no funcionará. --- ## Establecer acceso y privacidad del lector Controla quién puede ver tu referencia de API publicada configurando la configuración de acceso del lector. | Ambientación | Qué significa | | --- | --- | | Soldado | Solo los usuarios pueden ver la referencia de la API. Úsalos para APIs internas o solo para socios. | | Público | Cualquiera puede acceder a la referencia de la API sin autenticación. | | Mixta | Algunas secciones son públicas, otras están restringidas a los usuarios. | Para configurar el acceso del lector, navega a **Configuración** > **Usuarios y Permisos** > **Acceso al lector** en el portal de la Base de Conocimiento y localiza el espacio de trabajo de documentación de tu API. IMPORTANTE Visitar `/apidocs` antes de que se publiquen los artículos de endpoint devolverá un error 404: aún no hay contenido que mostrar. Esto también se aplica si has añadido un enlace `/apidocs` de navegación en tu sitio de la Knowledge Base. Publica al menos un artículo endpoint antes de hacer accesible tu referencia API para los lectores. Application Programming Interface - A set of defined rules and protocols that allows one software application to communicate with and request functionality from another. APIs are the backbone of modern integrations. When Document360 connects to Slack, Intercom, or Google Analytics, it does so through their APIs. Document360 also provides its own REST API, enabling teams to programmatically manage articles, categories, and reader accounts from external systems.