---
title: "Integración CI/CD"
slug: "ci-cd-integration"
updated: 2026-07-03T09:19:02Z
published: 2026-07-03T09:19:02Z
canonical: "docs.document360.com/ci-cd-integration"
---

> ## 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.

# Integración CI/CD

El flujo CI/CD te permite mantener la documentación de tu API sincronizada automáticamente con tu archivo de especificaciones. En lugar de subir manualmente una nueva especificación cada vez que cambia tu API, integras la CLI de Document360 (`d360`) en tu pipeline existente. Cuando cambia tu especificación, la tubería se ejecuta y tu documentación se actualiza automáticamente.

---

## Requisitos

Antes de configurar el flujo CI/CD, asegúrese de lo siguiente:

- La última versión de **Node.js** está instalada en el sistema que ejecuta la pipeline.
- Tienes disponible tu **clave API de Document360**, ID de **usuario** y **ID de referencia de API** .
- Tu archivo de especificaciones es accesible ya sea como una ruta local o como una URL alojada desde el entorno de la pipeline.

NOTA

Si no estás familiarizado con Node.js instalación, consulta la [documentación oficial Node.js](https://nodejs.org/en/download) para las instrucciones de configuración.

### Encontrar tu clave de API, ID de usuario e ID de referencia API

Document360 no proporciona pantallas de búsqueda independientes separadas para estos valores. En su lugar, los tres están pre-rellenados para ti dentro de un comando CLI listo para ejecutar, disponible en dos lugares:

- **Al crear una nueva referencia:** En la ventana de referencia de la Nueva API, seleccione el botón de radio **CI/CD Flow** .
- **Para una referencia existente:** Abre la referencia, haz clic **en Editar referencia API** y luego selecciona **Mostrar detalles** en el banner *"También puedes actualizar y resincronizar la Referencia API usando nuestro paquete D360 npm".*

Cualquiera de las dos opciones muestra el comando completo `apidocs:resync` con `--userId`, `--apiReferenceId`, y `--apiKey` ya rellenado.

¡IMPORTANTE!

El token API que se encuentra en **Configuración** > **portal de la base de conocimiento** > **tokens API** es para la API de cliente (pública) de Document360 y no puede usarse con el flujo CI/CD d360. Usa siempre el `--apiKey` valor del comando CLI precompletado arriba.

---

## Instalación de la CLI de Document360

La herramienta CLI de Document360 se distribuye como un paquete npm llamado `d360`. Instálalo globalmente:

```bash
npm install d360 -g
```

NOTA

Solo necesitas ejecutar este comando de instalación una vez. Si la CLI ya está instalada en el sistema, sáltate este paso.

---

## Configuración inicial: creación de una nueva referencia de API mediante CLI

Si configuras CI/CD para una nueva referencia de API, puedes generar la importación inicial directamente desde la CLI.

1. En el portal de la Base de conocimiento, navega a **la documentación** `{ }` de la API en la barra de navegación de la izquierda.
2. Haz clic en el desplegable **Crear** y selecciona **Nueva API.**
3. En la ventana de referencia de la Nueva API, seleccione el botón de radio **CI/CD Flow** .
4. Copia el comando completo de la CLI que aparece en la ventana.
5. Sustituye el `--path` valor en el comando copiado por la ruta hacia tu archivo de especificaciones.

**Archivo local:**

```bash
--path=/Users/yourname/projects/api/openapi.yaml
```

**URL alojada:**

```bash
--path=https://example.com/api/openapi.yaml
```

1. Pega el comando actualizado en tu terminal y pulsa Enter.

Document360 sube el archivo de especificaciones y genera la referencia de la API.

---

## Resincronización de una referencia de API existente

Una vez creada una referencia de API, usa el `apidocs:resync` comando para actualizarla cuando cambie tu especificación. Este es el comando que ejecutarás en tu pipeline CI/CD.

```bash
d360 apidocs:resync \
  --apiKey=YOUR_API_KEY \
  --userId=YOUR_USER_ID \
  --apiReferenceId=YOUR_API_REFERENCE_ID \
  --path=PATH_TO_SPEC_FILE
```

Sustituye los valores provisionales:

| Parámetro | Qué poner aquí |
| --- | --- |
| `--apiKey` | Tu clave API de Document360 |
| `--userId` | Tu ID de usuario de Document360 |
| `--apiReferenceId` | El ID de la referencia de la API a actualizar |
| `--path` | Ruta completa hacia tu archivo de especificaciones, o una URL que apunte a él |

NOTA

Cualquier contenido personalizado que hayas añadido a artículos de endpoint individuales se conservará cuando se realice una resincronización. Solo se actualiza el contenido generado por especificaciones.

### Manejo de múltiples archivos de especificaciones (monorepo)

La CLI no ofrece una opción por lotes — `--path` acepta un único archivo de especificación o URL.

Para mantener varios servicios sincronizados desde un mismo repositorio, ejecuta un comando separado `apidocs:resync` para cada servicio, asignando a cada uno su propio `--apiReferenceId` y `--path`.

IMPORTANTE

Siempre aprueba `--path` explícitamente en un monorepo. Si se omite, la CLI selecciona automáticamente el primer archivo de especificaciones que encuentra, que puede que no sea el que pretendes.

### Detección de fallos en tu pipeline

Actualmente, la CLI no utiliza su código de salida para indicar si una importación o resincronización ha tenido éxito. Un resincronización fallida — por ejemplo, "¡Resincronización fallida! Encontramos N alertas" o un error de API — se imprime en la consola, pero el proceso sigue saliendo con código `0`. Como resultado, el paso de la tubería parecerá pasar incluso cuando la especificación no se ha actualizado.

Para detectar fallos de forma fiable, inspecciona la salida de la consola del comando en busca de mensajes de fallo y falla tú mismo el paso si se encuentra uno, en lugar de depender del código de salida.

### Validación sin publicar

No hay bandera `--dry-run` . Para validar un archivo de especificaciones sin hacer ningún cambio en la referencia de tu API, usa el `apidocs:validate` comando:

```bash
d360 apidocs:validate --apiKey=YOUR_API_KEY --path=PATH_TO_SPEC_FILE
```

Esto informa de cualquier error o advertencia en la especificación sin publicar ni actualizar la referencia. Nótese que `apidocs:validate` toma solo `--apiKey` y `--path` — no requiere `--userId` ni `--apiReferenceId`. Ejecutarlo como paso previo `apidocs:resync` es una buena forma de detectar problemas de especificaciones temprano en una pipeline.

---

## Gestión de tu clave API en CI

Tu clave API es una credencial secreta. No lo codifiques directamente en los archivos de configuración de tu pipeline ni lo commitas en control de versiones.

Guárdalo como variable de entorno o secreto en tu plataforma de CI y haz referencia en el comando:

```bash
d360 apidocs:resync \
  --apiKey=$DOCUMENT360_API_KEY \
  --userId=$DOCUMENT360_USER_ID \
  --apiReferenceId=$API_REFERENCE_ID \
  --path=./openapi.yaml
```

¡IMPORTANTE!

Si regeneras tu clave API en el portal Document360, la clave antigua se vuelve inválida inmediatamente. Actualiza el secreto en tu plataforma CI antes de la siguiente ejecución del pipeline, o tu resincronización fallará.

---

## Ejemplos de oleoductos

### Acciones en GitHub

Crea `.github/workflows/api-docs.yml`:

```yaml
name: Sync API docs to Document360
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
jobs:
  resync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm install d360 -g
      - name: Resync to Document360
        shell: bash
        run: |
          set +e
          d360 apidocs:resync \
            --apiKey="${{ secrets.DOCUMENT360_API_KEY }}" \
            --userId="${{ secrets.DOCUMENT360_USER_ID }}" \
            --apiReferenceId="${{ secrets.API_REFERENCE_ID }}" \
            --path=./openapi.yaml \
            --force 2>&1 | tee resync.out
          grep -qi "Resync Successful" resync.out \
            || { echo "::error::Document360 resync failed"; exit 1; }
```

Almacenar `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, y `API_REFERENCE_ID` como secretos del repositorio, usando los valores del comando CLI precompletado.

### GitLab CI

Añadir lo siguiente a:`.gitlab-ci.yml`

```yaml
stages:
  - sync

sync-api-docs:
  stage: sync
  image: node:lts
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes: [openapi.yaml]
  script:
    - npm install d360 -g
    - |
      set +e
      d360 apidocs:resync \
        --apiKey="$DOCUMENT360_API_KEY" \
        --userId="$DOCUMENT360_USER_ID" \
        --apiReferenceId="$API_REFERENCE_ID" \
        --path=./openapi.yaml \
        --force 2>&1 | tee resync.out
      grep -qi "Resync Successful" resync.out || { echo "Document360 resync failed"; exit 1; }
```

Almacena `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, y `API_REFERENCE_ID` como variables enmascaradas de CI/CD en **Configuración** > **CI/** CD **> Variables**.

NOTA

GitLab no puede enmascarar valores que contengan guiones, por lo que el ID de usuario y el ID de referencia de API se almacenarán sin enmascarar.

---

## Soporte de Webhook en CI/CD

Los Webhooks definidos en tu especificación OpenAPI 3.1 están totalmente soportados en operaciones de resincronización CI/CD. Cuando se ejecuta una resincronización, las definiciones de webhook se actualizan junto con el resto del contenido de la especificación.

---

## Enlaces útiles

- [Paquete D360 npm](https://www.npmjs.com/package/d360)
- [Código fuente de d360](https://github.com/document360/d360)