Migración a importación y resincronización de referencias API asíncronas

Si importas o resincronizas API a través de la API del Cliente o la d360 CLI, necesitas mover tu integración a los nuevos endpoints y comandos asíncronos antes de que se eliminen los antiguos. Después de migrar, los archivos de especificaciones grandes se importan sin timeouts ni errores de memoria, y tu pipeline obtiene un resultado claro de aprobado o fallo para cada importación.

Esta guía te guía en la migración para la API del cliente v3, la API del cliente v2 y la d360 línea de crédito.

Averigua qué necesitas para migrar

Empieza con la integración que usas hoy. Cada fila enlaza con la sección que necesitas.

Tus endpoints y comandos actuales siguen funcionando, pero están obsoletos.

Antes de que empieces

Confirma lo siguiente para que tu primera llamada asincrónica funcione:

1. Tu clave o rol de API V3 tiene ambos permisos. Enviar necesita Actualizar artículos. Leer el resultado necesita Ver configuración del proyecto. Con solo uno de ellos, puedes enviar pero no leer el resultado, o al revés. En v2, se usa la misma clave API de CI/CD o token API para enviar y leer el resultado.

2. Conoces la URL de tu base regional.

   Región	Base URL
   UE	https://apihub.document360.io
   EE. UU.	https://apihub.us.document360.io
   Canadá	https://apihub.ca.document360.io
   Alojamiento privado	https://apihub.<your-hosting-name>.document360.io

3. Tu especificación está dentro de los límites de tamaño. Una especificación puede tener hasta 25 MB, subida o obtenida desde una URL. La solicitud de subida puede llegar a 26 MB. Una captura de URL que no se completa en 100 segundos falla.

4. Has decidido cómo manejar los hallazgos. Mira la siguiente sección.

Decide cómo manejar los hallazgos

Cuando la importación forzada está desactivada, tu importación o resincronización se rechaza si la especificación:

• Tiene algún error o advertencia.
• No tiene servers entrada.

La importación forzada está desactivada por defecto en las tres integraciones:

Cuando se rechaza una especificación, tienes dos opciones:

• Corregir la especificación. Esta es la opción recomendada. Los hallazgos pueden afectar a la documentación generada. Por ejemplo, una propiedad tipada bool en lugar de boolean se importa sin un tipo.
• Forzar la importación. Enviar "force_import": true (V3), forceImport=true (apiref submitv2), --force-import () o --force (apidocs:submit). Trata esto como una anulación deliberada, no como un valor por defecto.

Si tus scripts V3 dependían del antiguo predeterminado, ahora se rechazan, independientemente de si los has migrado o no. Arregla la especificación o añade force_import: true.

La misma confirmación se aplica a una resincronización que eliminaría endpoints. Sin ella, la operación falla con una advertencia como "Esta actualización eliminará permanentemente 19 endpoint(s). Pass force_import=true para confirmar" y lista los endpoints en result.deleted_endpoints. Nada se elimina hasta que confirmes.

Cómo cambia tu integración

Hoy, tu llamada espera hasta que se procesa toda la especificación y devuelve el resultado. Después de migrar, tu integración funciona en tres pasos:

1. Envía la importación o la resincronización. Recibes 202 Accepted un ID de operación enseguida.
2. Consulta el endpoint de estado con ese ID hasta que la operación alcance un estado final.
3. Lee el resultado, errores, advertencias y el nuevo ID de referencia de la API desde la respuesta final.

Lo que se importa no cambia. La misma especificación produce la misma referencia de API. Solo cuando obtienes el resultado y donde lees cambian los errores y advertencias.

Un importado típico termina en unos segundos o menos de un minuto. Nunca trates la 202 respuesta como un éxito.

Las muestras de JSON en esta guía están abreviadas a los campos que importan.

Migrar una integración con la API de cliente V3

Autentica con la X-API-Key: d360_sk_… cabecera, o con un token portador con el customerApi telescopio.

Paso 1: Sustituir los extremos

Paso 2: Enviar la importación o resincronizar

Para importar desde una URL:

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \
  -H "X-API-Key: $D360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://api.example.com/openapi.json",
        "workspace_id": "<workspace-id>"
      }'

Para importar desde un archivo, envíe multipart/form-data:

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \
  -H "X-API-Key: $D360_API_KEY" \
  -F "file=@openapi.json;type=application/json" \
  -F "workspace_id=<workspace-id>"

Para resincronizar una referencia de API existente:

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/$API_REFERENCE_ID/resyncs" \
  -H "X-API-Key: $D360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.example.com/openapi.json" }'

Una resincronización no toma workspace_id. Utiliza el espacio de trabajo de la referencia de la API existente.

Utiliza estos campos de solicitud:

Suministra exactamente uno de url, file, o content.

La respuesta es 202 Accepted. Guarda el operation_id campo o la Operation-Location cabecera. Ambos identifican la operación que encuestas a continuación.

Operation-Location: https://apihub.document360.io/v3/projects/{projectId}/operations/{operationId}

{
  "data": {
    "id": null,
    "status": null,
    "operation_id": "4da2313e-b2da-440f-b4be-a1632901f2eb",
    "operation_status": "queued"
  },
  "success": true
}

Paso 3: Encuesta hasta que termine la operación

curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \
  -H "X-API-Key: $D360_API_KEY"

Mientras la operación es queued o running, la respuesta incluye un Retry-After: 5 encabezado. Espera tantos segundos entre encuestas. Detiene la sondeación cuando el estado sea definitivo:

Limita tu encuesta con un tiempo muerto. Veinte minutos es generoso para la mayoría de las especificaciones. Si una operación deja de avanzar, un organismo de control de antecedentes la failedmarca, así que tu encuesta siempre llega a un estado final.

Paso 4: Lee el resultado

Cuando la operación tenga éxito, guarda result.api_definition_id. Este es el ID de referencia de API que usas en llamadas posteriores de resincronización, publicación y eliminación.

{
  "data": {
    "id": "4da2313e-b2da-440f-b4be-a1632901f2eb",
    "operation_type": "import-api-reference",
    "status": "succeeded",
    "message": null,
    "result": {
      "api_definition_id": "f9af5181-ee76-489d-b6c9-306e9eb6d60a",
      "is_success": true,
      "articles_created": 19,
      "categories_created": 3,
      "errors": null,
      "warnings": null,
      "is_server_available": true,
      "show_spec_file_warning": false,
      "deleted_endpoints": null
    },
    "errors": null,
    "created_at": "2026-10-05T10:02:25.33Z",
    "updated_at": "2026-10-05T10:02:30.866Z",
    "completed_at": "2026-10-05T10:02:30.866Z"
  },
  "success": true
}

Si tu especificación tiene hallazgos y force_import es false, la operación termina como failed y lista los hallazgos en result.errors y result.warnings. Cada uno pointer es un puntero JSON a tu especificación, por lo que puedes ir directamente a la línea para corregir. El camino en esta muestra es ilustrativo.

{
  "data": {
    "status": "failed",
    "message": "The operation failed.",
    "result": {
      "is_success": false,
      "errors": [
        {
          "message": "Invalid schema type identifier: bool",
          "pointer": "#/paths/~1orders/get/responses/200/content/application~1json/schema/properties/active/type"
        }
      ],
      "warnings": []
    }
  }
}

Si el trabajo no podía ejecutarse, por ejemplo porque la URL no podía ser obtenida, message y errors[0].message se explica la razón:

{
  "data": {
    "status": "failed",
    "message": "This operation can't be completed. Please ensure that you have given a valid specification URL.",
    "result": null,
    "errors": [
      { "code": "OPERATION_FAILED", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL." }
    ]
  }
}

Ejemplo: Gatear un paso de pipeline en el resultado de importación

Este script envía una importación, espera un estado final y sale con un código distinto de cero en caso de fallo:

#!/usr/bin/env bash
set -euo pipefail

BASE="https://apihub.document360.io"
H=(-H "X-API-Key: $D360_API_KEY")

# 1. Submit and capture the status URL from the Operation-Location header
OP_URL=$(curl -sS -D - -o /dev/null -X POST \
  "$BASE/v3/projects/$PROJECT_ID/api-references/imports" "${H[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"$SPEC_URL\",\"workspace_id\":\"$WORKSPACE_ID\"}" \
  | awk 'tolower($1)=="operation-location:" {print $2}' | tr -d '\r')

[ -n "$OP_URL" ] || { echo "Submission was not accepted" >&2; exit 1; }

# 2. Poll until a final status (capped at 20 minutes)
for _ in $(seq 1 240); do
  BODY=$(curl -sS "$OP_URL" "${H[@]}")
  STATUS=$(echo "$BODY" | jq -r '.data.status')
  case "$STATUS" in
    queued|running) sleep 5 ;;
    succeeded)      echo "$BODY" | jq '.data.result'; exit 0 ;;
    *)              echo "$BODY" | jq '.data.message, .data.result.errors, .data.result.warnings' >&2; exit 1 ;;
  esac
done
echo "Timed out waiting for the operation" >&2
exit 1

Migrar una integración de la API de cliente v2

Autenticar con la api_token cabecera. Los extremos asíncronos v2 toman los mismos multipart/form-data campos que los síncronos, incluyendo el requerido forceImport.

Paso 1: Sustituir los extremos

Si llamas directamente a las rutas CI/CD con una clave API CI/CD, sustituye estas en su lugar. Los d360 apidocs comandos usan las mismas rutas.

Paso 2: Enviar la importación o resincronizar

Para importar:

curl -i -X POST "https://apihub.document360.io/v2/APIReferences/jobs" \
  -H "api_token: $D360_API_TOKEN" \
  -F "url=https://api.example.com/openapi.json" \
  -F "projectVersionId=<workspace-id>" \
  -F "userId=<user-id>" \
  -F "forceImport=false"

Para resincronizar:

curl -i -X PUT "https://apihub.document360.io/v2/APIReferences/jobs" \
  -H "api_token: $D360_API_TOKEN" \
  -F "url=https://api.example.com/openapi.json" \
  -F "apiReferenceId=<api-reference-id>" \
  -F "projectVersionId=<workspace-id>" \
  -F "userId=<user-id>" \
  -F "forceImport=false"

La respuesta es 202 Accepted. Salvo background_task_id para las encuestas.

{
  "data": {
    "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d",
    "is_processing": true,
    "alerts": [{ "message": "Accepted for processing. Poll /v2/apireferences/jobs/c02535d8-… for the result." }]
  },
  "success": true
}

Paso 3: Encuesta hasta que termine el trabajo

curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \
  -H "api_token: $D360_API_TOKEN"

Sigue encuestando hasta data.is_processing que sea false.

Paso 4: Lee el resultado

La respuesta final lleva el resultado. Salvo api_reference_id para las llamadas posteriores.

{
  "data": {
    "api_reference_id": "b8e74ec5-7de3-4d4b-8cbc-b2945f7aeb56",
    "articles_created": 19,
    "categories_created": 3,
    "errors": [],
    "alerts": [],
    "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d",
    "is_processing": false
  },
  "success": true
}

Lee los hallazgos de data.errors, y las advertencias de data.alerts. Para una resincronización, data.deleted_endpoints enumera los endpoints que fueron eliminados, con los method, path, article_id, y title de cada uno.

Migrar las canalizaciones CLI y CI/CD del d360

La CLI tiene dos familias de comandos: V3 (apiref) y v2 ().apidocs Mantente dentro de tu familia actual cuando migres. Sustituye los comandos V3 por comandos V3 y los comandos v2 por comandos v2.

Paso 1: Actualizar la CLI

Los nuevos comandos requieren la versión 3.0.7 o posterior.

npm install -g d360@latest
d360 --version

Los comandos antiguos (, , , ) están marcados [DEPRECATED] en --help. Dejan de funcionar cuando se eliminan los endpoints que llaman.d360 apidocs:validate no está obsoleto. apidocs:resyncapidocsapiref resyncapiref import

Paso 2: Comprueba que usas la credencial correcta

Ambas familias leen el mismo D360_API_KEY nombre de variable, pero cada una espera una credencial diferente. Usar la equivocada es el error de configuración más común. La CLI te avisa cuando detecta la credencial incorrecta.

La CLI no tiene inicio de sesión interactivo. Toma la clave API de la primera fuente que se establece: una bandera de comandos, una variable de entorno (D360_API_KEY, D360_PROJECT_ID, D360_BASE_URL), luego la configuración guardada (d360 init, o d360 config set-key y d360 config set-project-id). En una canalización, almacena la clave en tu almacenamiento secreto de CI y pásala como variable de entorno. Usa la URL base de tu región.

Paso 3: Sustituye tus comandos

Si usas comandos V3

Reemplaza ambos apiref import y apiref resync por apiref submit. El ID que pasas decide la operación: --workspace-id importa, --api-reference-id resincroniza.

Antes:

d360 apiref import --workspace-id <workspace-id> --url https://api.example.com/openapi.json
d360 apiref resync --api-reference-id <api-reference-id> --url https://api.example.com/openapi.json

Después:

# Import a new API reference and wait for the result
d360 apiref submit --workspace-id <workspace-id> --url https://api.example.com/openapi.json --wait

# Resync an existing API reference from a local file and wait
d360 apiref submit --api-reference-id <api-reference-id> --file ./openapi.json --wait

# Submit now and poll separately, for example from another pipeline stage
id=$(d360 apiref submit --workspace-id <workspace-id> --file ./openapi.json \
       --filter operation_id -o tsv)
d360 operations wait "$id"

Actualiza tus banderas:

La --filter bandera toma un camino hacia los datos de respuesta. Usa operation_id, no data.operation_id. La -o tsv opción imprime el ID sin usar.

--wait y d360 operations wait salen 0 cuando la operación tiene éxito. Salen 1 cuando falla o se agota el presupuesto de espera de 20 minutos. Un tiempo de espera presupuestario deja de esperar, pero no cancela la operación.

Si usas comandos v2 (apidocs)

Estos son los comandos que se muestran para CI/CD en los paneles de referencia Añadir API y Editar API del portal. Sustituye ambos apidocs y apidocs:resync por apidocs:submit, y luego lee el resultado con apidocs:status. Los nombres de las banderas permanecen igual (camelCase), y mantienes la clave CI/CD.

Antes:

d360 apidocs --apiKey "$D360_CICD_KEY" --userId <user-id> --versionId <workspace-id> \
  --path ./openapi.json

d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId <user-id> \
  --apiReferenceId <api-reference-id> --path ./openapi.json

Después:

# Import (prints the task ID on its own line)
d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId <user-id> --versionId <workspace-id> \
  --path ./openapi.json

# Resync (passing --apiReferenceId makes it a resync)
d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId <user-id> \
  --apiReferenceId <api-reference-id> --path ./openapi.json

# Wait for the job to finish
d360 apidocs:status <task-id> --apiKey "$D360_CICD_KEY" --wait

apidocs:submit acepta las mismas banderas que el comando antiguo apidocs : --apiKey, --userId, --versionId, --apiReferenceId, --path, --force, , --publish, , y --apihubUrl. Imprime un ID de tarea y sale.

apidocs:status solo toma --apiKey, plus --apihubUrl para regiones fuera de la UE. Siempre bloquea tu pipeline en --wait. Sin él, el comando informa una vez y sale 0 incluso si el trabajo sigue en funcionamiento. Con --wait, hace sondeos hasta que el trabajo termina, imprime los resultados (errores, alertas y cualquier endpoint eliminado por una resincronización) y sale 1 si el trabajo no ha tenido éxito.

Si una resincronización eliminara los endpoints, se detiene y los lista. Reejecuta con --force para confirmar.

Paso 4: Actualiza tu pipeline

Utiliza uno de estos pasos de GitHub Actions como punto de partida. En ambos, el paso falla cuando falla el trabajo, y los hallazgos se imprimen en el registro.

V3:

- name: Publish API reference (V3)
  env:
    D360_API_KEY: ${{ secrets.D360_API_KEY }}          # a d360_sk_ key
    D360_PROJECT_ID: ${{ vars.D360_PROJECT_ID }}
  run: |
    npm install -g d360@latest
    d360 apiref submit --api-reference-id "${{ vars.D360_API_REFERENCE_ID }}" \
      --file ./openapi.json --wait

v2 (apidocs):

- name: Publish API reference (v2)
  env:
    D360_CICD_KEY: ${{ secrets.D360_CICD_KEY }}         # the project's CI/CD key
  run: |
    npm install -g d360@latest
    task=$(d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId "${{ vars.D360_USER_ID }}" \
             --apiReferenceId "${{ vars.D360_API_REFERENCE_ID }}" --path ./openapi.json)
    d360 apidocs:status "$task" --apiKey "$D360_CICD_KEY" --wait

Soluciona los problemas comunes después de migrar

La CLI sigue la misma regla de reintento. No vuelve a intentar una envío después de una 5xx conexión perdida. Solo vuelve a intentar una 429, que es rechazada antes de que empiece cualquier trabajo.

Verifica tu migración

Tu migración se completa cuando:

• Cada llamada de importación y resincronización utiliza un endpoint o comando asincrónico.
• Tu integración lee el resultado del endpoint de estado, no de la 202 respuesta.
• En la V3, tu integración usa operation_id en lugar de data.id y data.status desde la respuesta de envío.
• Tu integración se 409 Conflict gestiona esperando a la tarea en ejecución y reintentándolo.
• Has elegido cómo manejar los hallazgos: fijar la especificación o fijar force_import: true deliberadamente.
• Tu clave o rol de API puede tanto enviar como leer operaciones.
• Tu CLI está en la versión 3.0.7 o posterior, y cada familia usa su propia credencial: una d360_sk_ clave para apiref, y la clave CI/CD para apidocs.
• Tu pipeline falla el paso cuando falla la importación o resincronización.
• Has completado la migración antes de que los antiguos endpoints y comandos sean eliminados a finales de marzo de 2027.