--- title: "Migração para importação e resincronização de referência de API assíncrona" slug: "migrate-to-async-api-reference-import-resync" updated: 2026-11-03T09:00:07Z published: 2026-11-03T09:00:07Z 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. # Migração para importação e resincronização de referência de API assíncrona Se você importar ou ressincronizar API pela API do Cliente ou pela `d360` CLI, é necessário mover sua integração para os novos endpoints e comandos assíncronos antes que os antigos sejam removidos. Depois que você migrar, arquivos grandes de especificação são importados sem timeouts ou erros de memória, e seu pipeline recebe um resultado claro de aprovação ou falha para cada importação. Este guia guia você pela migração para a API do Cliente V3, API do Cliente v2 e a `d360` linha de código. IMPORTANTE! Na API do Cliente V3, `force_import` agora o padrão é `false` usado em todas as rotas de importação e resincronização, incluindo as síncronas obsoletas. Se suas chamadas V3 omitirem `force_import`, uma especificação que antes importava apesar de erros ou avisos agora é recusada, mesmo antes de você migrar. [Veja Decida como lidar com as descobertas](/docs/pt/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). --- ## Descubra o que você precisa migrar Comece com a integração que você usa hoje. Cada linha faz link para a seção que você precisa. | Se você usar | O que fazer | Vá para | | --- | --- | --- | | API do cliente V3 (`/v3/projects/{projectId}/api-references`) | Substitua as chamadas de importação e ressincronização, e adicione o sondamento | [Migre uma integração com a API do Cliente V3](/docs/pt/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v3-integration) | | Customer API v2 (`/v2/APIReferences`) | Substitua as chamadas de importação e ressincronização, e adicione o sondamento | [Migre uma integração com a API do cliente v2](/docs/pt/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | Rotas CI/CD (`/v2/apidocs/…`) chamadas diretamente | Substitua as rotas e adicione votação | [Migre uma integração com a API do cliente v2](/docs/pt/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | `d360 apiref import` ou `d360 apiref resync` | Atualize o CLI e mude para `d360 apiref submit` | [Migre os pipelines de CLI e CI/CD do d360](/docs/pt/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | `d360 apidocs` ou `d360 apidocs:resync` | Atualize o CLI e mude para `d360 apidocs:submit` | [Migre os pipelines de CLI e CI/CD do d360](/docs/pt/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | Apenas o portal da base de conhecimento | Nada. Importação e ressincronização do portal não são afetadas. | | Seus endpoints e comandos atuais ainda funcionam, mas estão obsoletos. NOTA Os antigos endpoints síncronos e comandos CLI serão removidos até o final de março de 2027. Planeje sua migração antes dessa janela. --- ## Antes de começar Confirme o seguinte para que sua primeira chamada assíncrona funcione: 1. **Sua chave ou função API V3 tem ambas as permissões.** Submissão precisa **Atualizar artigos**. Ler o resultado precisa **Ver configurações do projeto**. Com apenas uma delas, você pode enviar, mas não ler o resultado, ou o contrário. Na v2, a mesma chave API CI/CD ou token API é usada para enviar e ler o resultado. 2. **Você conhece sua URL base regional.** | Região | Base URL | | --- | --- | | UE | `https://apihub.document360.io` | | EUA | `https://apihub.us.document360.io` | | Canadá | `https://apihub.ca.document360.io` | | Hospedagem privada | `https://apihub.<your-hosting-name>.document360.io` | 3. **Sua especificação está dentro dos limites de tamanho.** Uma especificação pode ter até 25 MB, enviada ou buscada a partir de uma URL. A solicitação de upload pode chegar a até 26 MB. Uma busca de URL que não é concluída em 100 segundos falha. 4. **Você decidiu como lidar com as descobertas.** Veja a próxima seção. ### Decida como lidar com as descobertas Quando a importação forçada está desativada, sua importação ou ressincronização é recusada se a especificação: - Tem algum erro ou aviso. - Não tem `servers` entrada. A importação forçada está desativada por padrão nas três integrações: | Integração | Padrão | O que mudou | | --- | --- | --- | | API do Cliente V3 | `force_import: false` | O padrão costumava ser `true`. Isso se aplica às rotas V3 novas e obsoletas. | | API do cliente v2 | `forceImport=false` | Nada. O padrão já `false`era. | | `d360` CLI | `--force-import` e `--force` estão fora a menos que você passe por eles | Nada. | Quando uma especificação é recusada, você tem duas opções: - **Corrija a especificação.** Esta é a opção recomendada. Os achados podem afetar a documentação gerada. Por exemplo, uma propriedade tipada `bool` em vez de `boolean` é importada sem um tipo. - **Forçar a importação.** Enviar `"force_import": true` (V3), `forceImport=true` (`apiref submit`v2), `--force-import` () ou `--force` (`apidocs:submit`). Trate isso como uma sobreposição deliberada, não um padrão. Se seus scripts V3 dependiam do padrão antigo, eles são recusados agora, independentemente de você ter migrado ou não. Corrija a especificação ou adicione `force_import: true`. A mesma confirmação se aplica a um ressincronização que removeria endpoints. Sem ela, a operação falha com um aviso como *"Esta atualização vai deletar permanentemente 19(s) endpoint(s). Passe force_import=true para confirmar"* e lista os endpoints em `result.deleted_endpoints`. Nada é deletado até que você confirme. --- ## Como sua integração muda Hoje, sua chamada espera até que toda a especificação seja processada e retorne o resultado. Após a migração, sua integração funciona em três etapas: 1. **Envie** a importação ou resincronização. Você recebe `202 Accepted` um ID de operação imediatamente. 2. **Questione** o endpoint de status com esse ID até que a operação atinja o status final. 3. **Leia** o resultado, erros, avisos e o novo ID de referência da API da resposta final. O que é importado não muda. A mesma especificação produz a mesma referência de API. Só *quando* você recebe o resultado e *onde* você lê erros e avisos mudam. Um importado típico termina em alguns segundos ou menos de um minuto. Nunca trate a `202` resposta como sucesso. Os exemplos de JSON neste guia são resumidos aos campos que importam. --- ## Migre uma integração com a API do Cliente V3 Autentique com o `X-API-Key: d360_sk_…` cabeçalho, ou um token portador com o `customerApi` escopo. ### Passo 1: Substituir os pontos finais | Operação | Antigo (obsoleto) | Novo | | --- | --- | --- | | Importação | `POST /v3/projects/{projectId}/api-references` | `POST /v3/projects/{projectId}/api-references/imports` | | Resincronização | `PUT /v3/projects/{projectId}/api-references/{apiReferenceId}` | `POST /v3/projects/{projectId}/api-references/{apiReferenceId}/resyncs` | | Leia o resultado | Na resposta | `GET /v3/projects/{projectId}/operations/{operationId}` | ### Passo 2: Submeta a importação ou resincronize Para importar de uma 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 de um arquivo, envie `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 ressincronizar uma referência 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" }' ``` Um resync não leva `workspace_id`. Ele usa o workspace da referência da API existente. Use estes campos de solicitação: | Campo | Importação | Resincronização | Notas | | --- | --- | --- | --- | | `url` | Opcional | Opcional | Uma URL de especificação publicamente acessível | | `file` | Opcional (multiparte) | Opcional (multiparte) | O arquivo de especificação, JSON ou YAML | | `content` | Descontinuado | Descontinuado | Use `file` em vez disso | | `workspace_id` | Obrigatório | Não utilizado | Espaço de trabalho alvo | | `publish_articles` | Opcional | Opcional | Publica os artigos gerados | | `user_id` | Exigido com `publish_articles` | Exigido com `publish_articles` | O membro da equipe que publica | | `force_import` | Opcional, padrão `false` | Opcional, padrão `false` | Veja [Decida como lidar com as descobertas](/docs/pt/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings) | Fornece exatamente um de `url`, `file`, ou `content`. A resposta é `202 Accepted`. Salve o `operation_id` campo ou o `Operation-Location` cabeçalho. Ambos identificam a operação que você interroga em seguida. ``` 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 Se sua integração for `data.id` lida ou `data.status` a partir da resposta enviada, atualize-a. Ambas estão `null` em resposta `202` porque nada foi importado ainda. Você recebe o ID de referência da API do resultado da operação no Passo 4. ### Passo 3: Consultar até o término da operação ``` curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \ -H "X-API-Key: $D360_API_KEY" ``` Enquanto a operação for `queued` ou `running`, a resposta inclui um `Retry-After: 5` cabeçalho. Espere tantos segundos entre as pesquisas. Pare de sondar quando o status for final: | Status | Final | Significado | | --- | --- | --- | | `queued` | Não | Aceito e esperando um trabalhador | | `running` | Não | Sendo processado | | `succeeded` | Sim | Importado ou ressincronizado com sucesso | | `failed` | Sim | Não aplicado. Verifique `message`, `errors`, e `result` | Limite sua enquete com um tempo de detenção. Vinte minutos é generoso para a maioria das especificações. Se uma operação parar de avançar, um órgão fiscal de antecedentes a `failed`marca, para que sua enquete sempre chegue ao status final. ### Passo 4: Leia o resultado Quando a operação for bem-sucedida, salve `result.api_definition_id`. Esse é o ID de referência da API que você usa em chamadas posteriores de resincronização, publicação e exclusão. ``` { "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 } ``` **Se sua especificação tiver achados** e `force_import` for `false`, a operação termina como `failed` e lista os achados em `result.errors` e `result.warnings`. Cada `pointer` um é um ponteiro JSON para sua especificação, então você pode ir direto para a linha para corrigir. O caminho neste exemplo é 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": [] } } } ``` **Se o trabalho não pôde ser executado**, por exemplo, porque a URL não pôde ser buscada, `message` e `errors[0].message` dê o motivo: ``` { "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." } ] } } ``` ### Exemplo: Gate de um passo de pipeline no resultado de importação Este script envia uma importação, aguarda um status final e sai com um código diferente de zero em caso de falha: ``` #!/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 ``` --- ## Migre uma integração com a API do cliente v2 Autenticar com o `api_token` cabeçalho. Os extremos assíncronos v2 ocupam os mesmos `multipart/form-data` campos que os síncronos, incluindo o necessário `forceImport`. ### Passo 1: Substituir os pontos finais | Operação | Antigo (obsoleto) | Novo | | --- | --- | --- | | Importação | `POST /v2/APIReferences` | `POST /v2/APIReferences/jobs` | | Resincronização | `PUT /v2/APIReferences` | `PUT /v2/APIReferences/jobs` | | Leia o resultado | Na resposta | `GET /v2/APIReferences/jobs/{backgroundTaskId}` | Se você chamar as rotas CI/CD diretamente com uma chave API CI/CD, substitua essas rotas. Os `d360 apidocs` comandos usam as mesmas rotas. | Operação | Antigo (obsoleto) | Novo | | --- | --- | --- | | Importação | `POST /v2/apidocs/import/{userId}` | `POST /v2/apidocs/jobs/import/{userId}` | | Resincronização | `POST /v2/apidocs/{apiDefinitionId}/resync/{userId}` | `POST /v2/apidocs/jobs/{apiDefinitionId}/resync/{userId}` | | Leia o resultado | Na resposta | `GET /v2/apidocs/jobs/{backgroundTaskId}` | ### Passo 2: Submeta a importação ou resincronize 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" ``` A resposta é `202 Accepted`. Exceto `background_task_id` para as pesquisas. ``` { "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 } ``` ### Passo 3: Enquete até o trabalho terminar ``` curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \ -H "api_token: $D360_API_TOKEN" ``` Continue pesquisando até `data.is_processing` que seja `false`. ### Passo 4: Leia o resultado A resposta final traz o resultado. Exceto `api_reference_id` por chamadas 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 } ``` Leia os achados de `data.errors`, e avisos de `data.alerts`. Para uma ressincronização, `data.deleted_endpoints` lista os endpoints que foram removidos, com os `method`, `path`, `article_id`, e `title` de cada um. --- ## Migre os pipelines de CLI e CI/CD do d360 A CLI possui duas famílias de comandos: V3 (`apiref`) e v2 ().`apidocs` Fique dentro da sua família atual ao migrar. Substitua os comandos V3 por comandos V3 e os comandos v2 por comandos v2. ### Passo 1: Atualize o CLI Os novos comandos exigem a versão **3.0.7** ou posterior. ``` npm install -g d360@latest d360 --version ``` Os comandos antigos (`apiref import`, `apiref resync`, `apidocs`, `apidocs:resync`) são marcados `[DEPRECATED]` em `--help`. Eles param de funcionar quando os endpoints que chamam são removidos. `d360 apidocs:validate` não está obsoleto. ### Passo 2: Verifique se você usa a credencial correta Ambas as famílias leem o mesmo `D360_API_KEY` nome de variável, mas cada uma espera uma credencial diferente. Usar a credencial errada é o erro de configuração mais comum. A CLI te avisa quando detecta a credencial errada. | | comandos v3 (`apiref`, `operations`) | comandos v2 (`apidocs`, `apidocs:submit`, `apidocs:status`) | | --- | --- | --- | | Credencial | Uma chave API V3 começando com `d360_sk_`, criada em **Configurações** > **portal da base de conhecimento** > **chaves API** | Chave CI/CD API do projeto (um GUID) | | Enviado como | `X-API-Key` cabeçalho | `api_token` | | Também precisa | ID do projeto (`--project-id` ou `d360 config set-project-id`), mais o ID do workspace (importação) ou ID de referência da API (resincronização) | ID de usuário (`--userId`), mais o ID do workspace (`--versionId`, import) ou ID de referência da API (`--apiReferenceId`, resync). Sem ID do projeto. | | Permissões | **Atualizar artigos** para enviar, **Visualizar as configurações do projeto** para pesquisar. Uma chave faltando, qualquer uma pode enviar mas não ler o resultado, ou o contrário. | A mesma chave é usada para enviar e status | A CLI não possui login interativo. Ela pega a chave da API da primeira fonte definida: um flag de comando, uma variável de ambiente (`D360_API_KEY`, `D360_PROJECT_ID`, `D360_BASE_URL`), depois a configuração salva (`d360 init`, ou `d360 config set-key` e `d360 config set-project-id`). Em um pipeline, armazene a chave no seu armazenamento secreto de CI e a passe como variável de ambiente. Use a URL base da sua região. ### Passo 3: Substitua seus comandos #### Se você usar comandos V3 Substitua ambos `apiref import` e `apiref resync` por `apiref submit`. O ID que você passar decide a operação: `--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 ``` Depois: ``` # 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" ``` Atualize suas bandeiras: | | Antigo | Novo | | --- | --- | --- | | Importação ou resincronização | Dois comandos | Um comando: `--workspace-id` importa, `--api-reference-id` resincroniza | | Fonte da especificação | Importar: `--url` ou `--content`. Resincronizar: `--url` | `--url` ou `--file` para ambos | | Publicar após a importação | `--publish-articles` | `--publish-articles` com `--user-id` (obrigatório) | | Avisos | | `--force-import` para continuar após avisos (desativado por padrão) | | Resultado | Na resposta | `--wait`, ou `d360 operations wait <operation-id>` | A `--filter` flag segue um caminho para os dados de resposta. Use `operation_id`, não `data.operation_id`. A `-o tsv` opção imprime o ID básico. `--wait` e `d360 operations wait` saem `0` quando a operação é bem-sucedida. Eles saem `1` quando falha ou quando o orçamento de espera de 20 minutos acaba. Um tempo limite do orçamento para de esperar, mas não cancela a operação. #### Se você usar comandos v2 (apidocs) Esses são os comandos mostrados para CI/CD nos painéis de **referência Adicionar API** e **Editar API** do portal. Substitua ambos `apidocs` e `apidocs:resync` por `apidocs:submit`, então leia o resultado com `apidocs:status`. Os nomes das bandeiras permanecem os mesmos (camelCase), e você mantém a chave 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 ``` Depois: ``` # 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` aceita as mesmas flags do comando antigo `apidocs` : `--apiKey`, `--userId`, `--versionId`, `--apiReferenceId`, `--path`, `--force`, , `--publish`, , e `--apihubUrl`. Ele imprime um ID de tarefa e sai. `apidocs:status` Aceita apenas `--apiKey`, plus `--apihubUrl` para regiões fora da UE. Sempre faça um gate no `--wait`seu pipeline em . Sem ele, o comando reporta uma vez e sai `0` mesmo que o trabalho ainda esteja rodando. Com `--wait`, ele faz polling até o job terminar, imprime os resultados (erros, alertas e quaisquer endpoints removidos por uma resincronização) e sai `1` se o job não tiver sucesso. Se uma resincronização apagasse endpoints, ele para e os lista. Execute novamente com `--force` para confirmar. ### Passo 4: Atualize seu pipeline Use um desses passos de Ações do GitHub como ponto de partida. Em ambos, o passo falha quando o trabalho falha, e os achados são impressos no log. 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 ``` --- ## Corrija problemas comuns depois que migrar | O que você vê | Por que isso acontece | O que fazer | | --- | --- | --- | | Resultados `403` de pesquisa após uma submissão bem-sucedida | Sua chave ou função pode atualizar artigos, mas não pode visualizar as configurações do projeto | Dê permissões para a integração | | Envie declarações `409 Conflict` | Outra importação ou resincronização já está rodando no projeto. Apenas uma pode rodar por vez. | Questione a tarefa em execução nomeada na resposta e tente novamente | | Reenviar retorna o mesmo ID de operação | Você enviou um pedido idêntico enquanto o primeiro ainda estava rodando | Consulte a operação devolvida. Nenhuma segunda importação é iniciada. | | Uma importação ou resincronização da V3 que antes funcionava agora é recusada | `force_import` agora o padrão é `false` em todas as rotas da V3, incluindo as obsoletas | Corrigir as descobertas, ou definir `force_import: true` deliberadamente. [Veja Decida como lidar com as descobertas](/docs/pt/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). | | Uma resincronização falha com *"Esta atualização vai deletar permanentemente..."* | A resincronização removeria os endpoints | Revise os endpoints listados, então reenvie com `force_import: true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`) ou `--force` (`apidocs:submit`) para confirmar | | Um prazo de entrega ou retorna `5xx` | O pedido pode ou não ter sido aceito | Não tente novamente imediatamente. Uma retentativa pode iniciar uma segunda importação. Verifique se há uma operação em execução com `GET /v3/projects/{projectId}/operations?status=running`, ou consulte o ID da operação, se você tiver. | A CLI segue a mesma regra de retentativa. Ela não tenta novamente uma submissão após um `5xx` ou uma conexão caída. Ela apenas tenta novamente um `429`, que é rejeitado antes de qualquer trabalho começar. --- ## Verifique sua migração Sua migração é concluída quando: - Cada chamada de importação e resincronização usa um endpoint ou comando assíncrono. - Sua integração lê o resultado do endpoint de status, não da `202` resposta. - Na V3, sua integração usa `operation_id` em vez de `data.id` e `data.status` a partir da resposta de envio. - Sua integração é `409 Conflict` feita esperando pela tarefa em execução e tentando novamente. - Você escolheu como lidar com as descobertas: corrigir a especificação ou definir `force_import: true` deliberadamente. - Sua chave de API ou função pode tanto submeter quanto ler operações. - Sua CLI está na versão 3.0.7 ou posterior, e cada família usa sua própria credencial: uma `d360_sk_` chave para `apiref`, e a chave CI/CD para `apidocs`. - Seu pipeline falha na etapa quando uma importação ou resincronização falha. - Você concluiu a migração antes que os antigos endpoints e comandos sejam removidos no final de março 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.