--- title: "Migración a importación y resincronización de referencias API asíncronas" slug: "migrate-to-async-api-reference-import-resync" updated: 2026-11-03T09:00:02Z published: 2026-11-03T09:00:02Z canonical: "docs.document360.com/migrate-to-async-api-reference-import-resync" --- > ## 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. # 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. ¡IMPORTANTE! En la API de Cliente V3, `force_import` ahora se `false` activa por defecto en todas las rutas de importación y resincronización, incluidas las síncronas obsoletas. Si tus llamadas V3 `force_import`omiten , una especificación que antes importaba a pesar de errores o advertencias ahora se rechaza, incluso antes de migrar. [Consulta Decide cómo manejar los hallazgos](/docs/es/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). --- ## Averigua qué necesitas para migrar Empieza con la integración que usas hoy. Cada fila enlaza con la sección que necesitas. | Si usas | Qué hacer | Ir a | | --- | --- | --- | | API del cliente V3 (`/v3/projects/{projectId}/api-references`) | Sustituye las llamadas de importación y resincronización, y añade sondeos | [Migrar una integración con la API de cliente V3](/docs/es/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v3-integration) | | Customer API v2 (`/v2/APIReferences`) | Sustituye las llamadas de importación y resincronización, y añade sondeos | [Migrar una integración de la API de cliente v2](/docs/es/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | Las rutas CI/CD (`/v2/apidocs/…`) llamadas directamente | Sustituye las rutas y añade sondeos | [Migrar una integración de la API de cliente v2](/docs/es/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | `d360 apiref import` o `d360 apiref resync` | Actualiza la CLI y cambia a `d360 apiref submit` | [Migrar las canalizaciones CLI y CI/CD del d360](/docs/es/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | `d360 apidocs` o `d360 apidocs:resync` | Actualiza la CLI y cambia a `d360 apidocs:submit` | [Migrar las canalizaciones CLI y CI/CD del d360](/docs/es/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | Solo el portal de la base de conocimiento | Nada. La importación y resincronización del portal no se ven afectadas. | | Tus endpoints y comandos actuales siguen funcionando, pero están obsoletos. NOTA Los antiguos endpoints síncronos y comandos CLI serán eliminados antes de finales de marzo de 2027. Planifica tu migración antes de esa ventana. --- ## 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: | Integración | Default | Qué cambió | | --- | --- | --- | | API del cliente V3 | `force_import: false` | El valor por defecto solía ser `true`. Esto se aplica tanto a las nuevas como a las rutas obsoletas de la V3. | | API del cliente v2 | `forceImport=false` | Nada. El predeterminado ya `false`era. | | `d360` CLI | `--force-import` y `--force` se van a menos que los apruebes | Nada. | 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 submit`v2), `--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 | Funcionamiento | Antiguo (obsoleto) | Nuevo | | --- | --- | --- | | Importación | `POST /v3/projects/{projectId}/api-references` | `POST /v3/projects/{projectId}/api-references/imports` | | Resincronización | `PUT /v3/projects/{projectId}/api-references/{apiReferenceId}` | `POST /v3/projects/{projectId}/api-references/{apiReferenceId}/resyncs` | | Lee el resultado | En la respuesta | `GET /v3/projects/{projectId}/operations/{operationId}` | ### 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": "" }' ``` 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=" ``` 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: | Campo | Importación | Resincronización | Notas | | --- | --- | --- | --- | | `url` | Opcional | Opcional | Una URL de especificación públicamente accesible | | `file` | Opcional (multiparte) | Opcional (multiparte) | El archivo de especificaciones, JSON o YAML | | `content` | Obsoleto | Obsoleto | Úsalo `file` en su lugar | | `workspace_id` | Obligatorio | No utilizado | Espacio de trabajo objetivo | | `publish_articles` | Opcional | Opcional | Publica los artículos generados | | `user_id` | Obligatorio con `publish_articles` | Obligatorio con `publish_articles` | El miembro del equipo que publica | | `force_import` | Opcional, por defecto `false` | Opcional, por defecto `false` | [Ver Decide cómo manejar los hallazgos](/docs/es/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings) | 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 } ``` NOTA Si tu integración se `data.id` lee o `data.status` desde la respuesta de envío, actualízala. Ambas están `null` en respuesta `202` porque aún no se ha importado nada. Obtienes el ID de referencia de la API del resultado de la operación en el Paso 4. ### 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: | Estado | Final | Significado | | --- | --- | --- | | `queued` | No | Aceptado y esperando a un trabajador | | `running` | No | Proceso | | `succeeded` | Sí | Importado o resincronizado con éxito | | `failed` | Sí | No aplicado. Comproba `message`, `errors`, y `result` | 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 `failed`marca, 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 | Funcionamiento | Antiguo (obsoleto) | Nuevo | | --- | --- | --- | | Importación | `POST /v2/APIReferences` | `POST /v2/APIReferences/jobs` | | Resincronización | `PUT /v2/APIReferences` | `PUT /v2/APIReferences/jobs` | | Lee el resultado | En la respuesta | `GET /v2/APIReferences/jobs/{backgroundTaskId}` | 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. | Funcionamiento | Antiguo (obsoleto) | Nuevo | | --- | --- | --- | | Importación | `POST /v2/apidocs/import/{userId}` | `POST /v2/apidocs/jobs/import/{userId}` | | Resincronización | `POST /v2/apidocs/{apiDefinitionId}/resync/{userId}` | `POST /v2/apidocs/jobs/{apiDefinitionId}/resync/{userId}` | | Lee el resultado | En la respuesta | `GET /v2/apidocs/jobs/{backgroundTaskId}` | ### 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=" \ -F "userId=" \ -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=" \ -F "projectVersionId=" \ -F "userId=" \ -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:resync``apidocs``apiref resync``apiref 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. | | Comandos V3 (`apiref`, `operations`) | comandos v2 (`apidocs`, `apidocs:submit`, `apidocs:status`) | | --- | --- | --- | | Credencial | Una clave API V3 que comienza por `d360_sk_`, creada en **Configuración** > **portal de la base de conocimiento** > **claves API** | La clave CI/CD API del proyecto (una GUID) | | Enviado como | `X-API-Key` Encabezado | `api_token` | | También necesita | ID de proyecto (`--project-id` o `d360 config set-project-id`), más el ID del espacio de trabajo (importación) o ID de referencia de API (resincronización) | ID de usuario (`--userId`), más el ID del espacio de trabajo (`--versionId`, import) o ID de referencia de API (`--apiReferenceId`, resync). No hay ID de proyecto. | | Permisos | **Actualizar artículos** para enviar, **ver la configuración del proyecto** para encuestar. Una clave que falte, cualquiera puede enviar pero no leer el resultado, o al revés. | La misma clave se usa para enviar y estado | 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 --url https://api.example.com/openapi.json d360 apiref resync --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 --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 --file ./openapi.json --wait # Submit now and poll separately, for example from another pipeline stage id=$(d360 apiref submit --workspace-id --file ./openapi.json \ --filter operation_id -o tsv) d360 operations wait "$id" ``` Actualiza tus banderas: | | Antiguo | Nuevo | | --- | --- | --- | | Importación o resincronización | Dos comandos | Un comando: `--workspace-id` importa, `--api-reference-id` resincroniza | | Fuente de especificaciones | Importar: `--url` o `--content`. Resincronizar: `--url` | `--url` o `--file` para ambos | | Publicar después de la importación | `--publish-articles` | `--publish-articles` con `--user-id` (obligatorio) | | Advertencias | | `--force-import` para continuar con advertencias pasadas (desactivado por defecto) | | Resultado | En la respuesta | `--wait`, o `d360 operations wait <operation-id>` | 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 --versionId \ --path ./openapi.json d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json ``` Después: ``` # Import (prints the task ID on its own line) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json # Resync (passing --apiReferenceId makes it a resync) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json # Wait for the job to finish d360 apidocs:status --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 | Lo que ves | Por qué ocurre | Qué hacer | | --- | --- | --- | | Resultados `403` de encuestas tras una presentación exitosa | Tu clave o rol puede actualizar los artículos pero no puede ver la configuración del proyecto | Concede a la integración ambos permisos | | Presentar declaraciones `409 Conflict` | Otra importación o resincronización ya está ejecutándose en el proyecto. Solo uno puede ejecutarse a la vez. | Consulta la tarea en ejecución que aparece en la respuesta y luego vuelve a intentarlo | | Volver a enviar devuelve el mismo ID de operación | Enviaste una solicitud idéntica mientras la primera aún estaba en marcha | Encuesta la operación devuelta. No se inicia ninguna segunda importación. | | Una importación o resincronización V3 que antes funcionaba ahora se rechaza | `force_import` ahora por defecto está `false` en todas las rutas de la V3, incluidas las obsoletas | Corrige los hallazgos, o establece `force_import: true` deliberadamente. Ver [Decide cómo manejar los hallazgos](/docs/es/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). | | Una resincronización falla con *"Esta actualización se eliminará permanentemente..."* | La resincronización eliminaría los endpoints | Revisa los endpoints listados y luego vuelve a enviar con `force_import: true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`) o `--force` (`apidocs:submit`) para confirmar | | Una entrega tiene tiempo de espera o devolución `5xx` | La solicitud puede que haya sido aceptada o no | No lo intentes de nuevo de inmediato. Un reintento puede iniciar una segunda importación. Comprueba si hay una operación en ejecución con `GET /v3/projects/{projectId}/operations?status=running`, o consulta el ID de la operación si lo tienes. | 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. 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.