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.

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.

Seus endpoints e comandos atuais ainda funcionam, mas estão obsoletos.

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:

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 submitv2), --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

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": "<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=<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:

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
}

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:

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 failedmarca, 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

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.

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=<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"

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.

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

Depois:

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

Atualize suas bandeiras:

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

Depois:

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

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.