--- title: "Solução de problemas de importação de API" slug: "troubleshooting-api-documentation-issues" updated: 2026-07-27T05:03:16Z published: 2026-07-27T05:03:16Z canonical: "docs.document360.com/troubleshooting-api-documentation-issues" stale: true --- > ## 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. # Solução de problemas de importação de API Este artigo é uma referência consolidada para todos os erros, avisos e comportamentos inesperados documentados na funcionalidade de documentação da API do Document360. Use-o para diagnosticar e resolver problemas com importações, autenticação, o recurso Try It!, renderização e o site da base de conhecimento. --- ## Erros de importação ### Formato inválido – Falha no upload do arquivo API **Quando ocorre:** Quando uma ou mais respostas no seu arquivo de especificação OpenAPI estiverem faltando a seção necessária `content` . **Por que isso acontece:** O Document360 aplica regras rigorosas de validação do OpenAPI. Embora um arquivo possa passar por validação em ferramentas como o Swagger Editor, o Document360 exige que todas as respostas definam explicitamente tanto o tipo de mídia (por exemplo, `application/json`) quanto uma referência de esquema sob um `content` bloco. Respostas vazias ou que referenciam um esquema diretamente sem um `content` wrapper causarão esse erro. **Como consertar:** 1. Abra seu arquivo de especificação OpenAPI em um editor de texto ou IDE. 2. Localize quaisquer definições de resposta que estejam vazias ou que façam referência a um esquema sem bloco `content` . **Incorreto:** ```   responses:     "200": {} ``` **Correto:** ```   responses:     "200":       description: OK       content:         application/json:           schema:             $ref: "#/components/schemas/YourSchema" ``` 1. Salve o arquivo e faça o upload novamente para o Document360. Se o problema persistir, entre em contato com a equipe [de suporte do Document360](https://document360.com/support/) . --- ### URL inválida **Quando ocorre:** Ao criar uma referência de API a partir de uma URL, a URL fornecida não pode ser buscada ou resolvida. **Por que isso acontece:** A URL pode estar malformada, inacessível a partir dos servidores do Document360 ou apontando para um recurso que não seja uma especificação válida da OpenAPI. **Como consertar:** Verifique se a URL se resolve corretamente em um navegador ou com `curl`. Certifique-se de que ele retorne um documento válido JSON ou YAML OpenAPI. Corrija a URL e tente novamente. --- ### Formato de arquivo não suportado **Quando ocorre:** Quando o arquivo enviado não é um formato suportado. **Como consertar:** Certifique-se de que seu arquivo seja um dos seguintes: JSON, YAML ou YML. O Document360 suporta OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 e Coleções Postman. --- ### Não foi possível adicionar referência de API – arquivo de especificação inválido **Mensagem de erro:** *"Não foi possível adicionar referência de API. Essa operação não pode ser concluída. Por favor, certifique-se de que forneceu um arquivo de especificação válido."* ![Screenshot showing the invalid API reference error](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/3_ScreenShot-Troubleshooting.png) **Quando ocorre:** Ao enviar um arquivo de especificação YAML que foi copiado ou exportado de um editor de texto enriquecido ou processador de texto. **Por que isso acontece:** O arquivo YAML enviado é malformado e não é um documento válido do OpenAPI 3.0 YAML. Isso ocorre comumente quando o arquivo foi copiado ou exportado de um editor de texto enriquecido, que introduz caracteres de formatação, como `\f0\fs24` barras inversas ou finais que quebram o formato YAML. 1. **Valide seu arquivo de especificações**: Abra seu arquivo YAML em uma ferramenta como o Swagger Editor ou um editor de código para verificar erros ou problemas de formatação. 2. **Procure caracteres de formatação indesejados: Verifique** caracteres como `\f0\fs24` barras `\` inversas ou posteriores (especialmente na descrição do endpoint) que possam ter sido introduzidos durante o copiar-colar de uma fonte em texto rico. Esses podem quebrar o formato YAML. 3. **Limpar o arquivo**: Use um editor de texto simples ou código para remover quaisquer caracteres de formatação especial. Evite usar processadores de texto ao editar ou salvar arquivos YAML. 4. **Refaça o upload do arquivo**: Depois de limpar o arquivo e garantir que é um YAML válido da OpenAPI 3.0, tente enviá-lo novamente. --- ### Resumo e tags não refletidos após a importação **Quando ocorre:** Após importar uma especificação, os artigos finais exibem títulos incorretos ou aparecem em pastas de categorias inesperadas. **Por que isso acontece:** Os `summary` campos e `tags` são definidos no nível do caminho na especificação, em vez de dentro do objeto de operação (`get`, `post`, `put`, ou `delete`). Além disso, o `tags` campo deve sempre ser escrito como um array, mesmo quando apenas uma tag é usada. **Como consertar:** 1. Abra seu arquivo de especificação OpenAPI em um editor de texto. 2. Mova os `summary` campos e `tags` dentro de cada objeto de operação e garanta `tags` que está escrito como um array. **Incorreto:** ```   /your-endpoint:     summary: My Endpoint     tags: My Category     get:       ... ``` **Correto:** ```   /your-endpoint:     get:       summary: My Endpoint       tags: ["My Category"]       ... ``` 1. Salve o arquivo e reimporte para o Document360. Os artigos importados usarão o `summary` valor como título do artigo, e pastas baseadas em tags serão criadas corretamente. Se o problema persistir, entre em contato com a equipe [de suporte do Document360](https://document360.com/support/) . --- ### Falha no upload com 400 Solicitação Ruim – arquivo de especificação grande demais **Quando ocorre:** Ao fazer upload de um arquivo válido de especificação YAML ou JSON OpenAPI, que contém endpoints com esquemas de resposta profundamente aninhados e múltiplos códigos de resposta por endpoint. **Por que isso acontece:** Embora o arquivo possa ser um YAML válido e passar por validadores externos como o Swagger Editor, o Document360 impõe um limite interno de tamanho de artigo. Quando um endpoint contém esquemas de resposta aninhados em oito ou mais níveis de profundidade em múltiplos códigos de resposta, o tamanho resultante dos dados excede esse limite e não pode ser processado ou armazenado. **Como consertar:** 1. Abra seu arquivo de especificação OpenAPI em um editor de texto ou IDE. 2. Para cada endpoint, mantenha **apenas um tipo de resposta 201**, **um tipo de resposta da série 400** e o **tipo de resposta padrão**. Remova todos os códigos de resposta adicionais. 3. Para endpoints onde a resposta 201 sozinha contém esquemas profundamente aninhados, mantenha **apenas o tipo de resposta 201** e remova completamente a série 400 e os tipos de resposta padrão. 4. Salve o arquivo modificado e faça o upload novamente para o Document360. > i️ **NOTA** Se a publicação falhar após um upload bem-sucedido, entre em contato com a equipe de suporte do Document360. Publicar pode exigir assistência no backend devido à limitação do tamanho do artigo. --- ### Descrições de tags de nível superior não renderizadas na documentação da API **Quando ocorre:** Descrições e metadados definidos em objetos de tag OpenAPI de nível superior não são exibidos na documentação gerada da API. **Por que isso acontece:** Quando um arquivo de especificação OpenAPI contém tags de nível superior usadas para agrupar operações de API, o Document360 converte essas tags em categorias tipo pasta durante a importação. Categorias de pasta são usadas apenas para organizar endpoints e não geram páginas de conteúdo independentes. Como resultado, qualquer descrição ou metadado definido dentro desses objetos de tag de nível superior não é renderizado. **Solução alternativa:** Adicione o contexto relevante diretamente às descrições individuais dos endpoints dentro da tag, para que as informações fiquem visíveis nas páginas geradas dos endpoints. --- ## Ainda está tendo problemas? Se os passos acima não resolverem seu problema, entre em contato diretamente com a equipe [de suporte do Document360](https://document360.com/support/) . --- ## FAQ **Posso filtrar os resultados da API por artigos criados ou modificados após uma certa data?** A API não suporta filtragem de artigos diretamente pelo tempo de criação ou modificação. Você pode usar o endpoint Gets all Article Versions, que inclui um carimbo de tempo Modified At nos metadados, e filtrar a resposta do seu lado. Use o ID do artigo para obter o conteúdo completo pelo endpoint de detalhes do artigo. **O Document360 suporta respostas dinâmicas ou baseadas em instâncias da API?** Não. O Document360 segue a especificação OpenAPI, que define uma estrutura estática consistente para objetos de requisição e resposta. Se sua API retorna respostas diferentes para o mesmo endpoint em diferentes instâncias, o Document360 não pode refletir essas variações dinamicamente. A abordagem recomendada é usar a mesma estrutura de esquema em todos os ambientes, ou publicar arquivos de especificação OpenAPI separados para cada ambiente. Para campos que variam ligeiramente entre as instâncias, use a propriedade OpenAPI `additionalProperties` . **Posso baixar artigos em PDF usando a API?** Atualmente, não há opção para baixar artigos em PDF pelos endpoints da API. **Os leitores podem acessar o site da base de conhecimento durante o tempo de inatividade do portal Document360?** Sim. As chamadas GET da API do Cliente rodam independentemente do portal Document360, para que os leitores possam continuar acessando o site durante manutenção programada ou indisponibilidade do portal. **Por que a URL do Try It! inclui tryit.document360.io?** Esse é um comportamento esperado. O `tryit.document360.io` subdomínio é usado internamente para rotear e processar solicitações de teste da API. Isso não afeta a funcionalidade — as solicitações retornam resultados corretos da sua API. **Por que estou recebendo erros ao fazer requisições de API a partir de um fluxo de trabalho automatizado ou pipeline CI/CD?** Isso pode ocorrer se o user_id incluído na solicitação da API pertencer a um usuário inativo ou a um usuário que não possui as permissões necessárias para a operação em andamento. **Exemplo:** Ao chamar endpoints de fork (como `/v2/Categories/{CategoryId}/fork`), um user_id obsoleto ou inválido retornará o erro enganoso "O método ou operação não é implementado." Isso não significa que o endpoint não seja suportado — significa que o user_id é inválido ou que o usuário não tem permissões. **Correção:** Certifique-se de que o user_id pertença a um usuário ativo do Document360 com os direitos de acesso necessários (por exemplo, permissões de edição no artigo ou categoria que está sendo bifurcado). Para casos de automação, recomenda-se usar uma conta de serviço dedicada. Você pode recuperar o user_id apropriado usando o endpoint da API Obter detalhes completos do usuário por id. **Por que a API retorna linguagens inesperadas no campo available_languages?** **Quando ocorre** Isso ocorre quando o `available_languages` campo na resposta da API inclui idiomas que atualmente não se espera que estejam disponíveis para o artigo. **Por que isso acontece** A API retorna todos os idiomas nos quais o artigo foi publicado pelo menos uma vez. Se uma versão traduzida do artigo foi publicada anteriormente, essa linguagem será incluída no `available_languages` campo, mesmo que não seja mais mantida ativamente. **Como consertar isso** 1. Navegue até o artigo no idioma correspondente. 2. Verifique se o artigo traduzido já foi publicado anteriormente. 3. Despublique o artigo traduzido se ele não estiver mais disponível. Após o artigo traduzido não ser publicado, a linguagem não será mais retornada no `available_languages` campo da resposta da API. **Por que a API retorna um slug diferente para artigos traduzidos?** **Quando ocorre** Isso ocorre quando o slug retornado para um artigo traduzido difere do slug usado na solicitação original da API. **Exemplo** - Slug solicitado: `add-subscription-activation-code` - Tradução retornada slug: `adding-your-subscription-with-your-activation-code` **Por que isso acontece** A URL do artigo traduzido foi modificada após sua criação inicial, e uma regra de redirecionamento foi configurada para a URL anterior. A API retorna o slug ativo atual associado ao artigo traduzido em vez do slug original. **Como consertar isso** 1. Navegue até **Configurações > Site da Base de Conhecimento > Regras de Redirecionamento de Artigos**. 2. Verifique se existe uma regra de redirecionamento para o artigo traduzido. 3. Revise a URL atual configurada para o artigo no respectivo idioma. 4. Se necessário, atualize a URL do artigo ou redirecione a configuração para alinhar com o slug esperado. A API sempre retornará a URL atualmente ativa do artigo traduzido. **Como posso recuperar apenas artigos publicados ao usar o endpoint da API "Obter lista de artigos dentro de uma versão do projeto"?** **Quando ocorre** Isso ocorre quando a **lista Get de artigos dentro de um endpoint API de versão de projeto** retorna artigos em múltiplos estados de publicação, e apenas artigos publicados são necessários. **Por que isso acontece** O endpoint retorna todos os artigos disponíveis dentro da versão especificada do projeto, independentemente do status de publicação. O estado de publicação de cada artigo é identificado pelo `status` campo na resposta da API. Valores de status suportados incluem: - `0` — Rascunho - `3` — Publicado Como o endpoint atualmente não suporta filtragem por status de publicação, tanto os artigos rascunhos quanto os publicados são retornados na resposta. **Como consertar isso** Para recuperar apenas artigos publicados: 1. Chame a **lista Get de artigos dentro de um endpoint da API da versão do projeto** . 2. Filtre a resposta para incluir apenas artigos onde `status = 3`. 3. Extraia os IDs dos artigos dos resultados filtrados. 4. Use os IDs de artigo filtrados com o endpoint **Gets an** Article API para recuperar o conteúdo dos artigos publicados. **Informações Adicionais** Atualmente, a **lista Get de artigos dentro de um endpoint da API de versão do projeto** não fornece um parâmetro de consulta ou de caminho para retornar apenas artigos publicados. Filtrar a resposta com base no `status` campo é o método recomendado para identificar e recuperar o conteúdo publicado. > O `isPublished` parâmetro existe em endpoints de recurso individual (Recebe um artigo, Obtém uma categoria), mas não em endpoints de lista. Não use `isPublished` para filtrar resultados da lista.