Como importar e exportar artigos no Zendesk Guide: Guia completo de 2026

Se você já tentou mover conteúdo para dentro ou para fora do Zendesk Guide, provavelmente esbarrou na mesma parede que todo mundo: não há um botão de exportação integrado. O Zendesk não fornece uma ferramenta nativa para exportar em massa seus artigos da central de ajuda, o que deixa muitas equipes correndo atrás de soluções alternativas quando precisam migrar, fazer backup ou reestruturar sua base de conhecimento.

As boas notícias? Você tem opções. Várias delas, na verdade. Se você se sente à vontade para escrever scripts em Python ou prefere uma interface de apontar e clicar, existe um método que funcionará para sua equipe. Neste guia, vamos percorrer todas as abordagens disponíveis para importar e exportar artigos do Zendesk Guide, desde a API do Help Center até aplicativos de terceiros e serviços profissionais de migração.

Entendendo a estrutura de conteúdo do Zendesk Guide

Antes de começar a mover o conteúdo, você precisa entender como o Zendesk o organiza. Ao contrário de um sistema de pastas simples, o Zendesk Guide usa uma hierarquia de três camadas:

• Categorias são os contêineres de nível superior
• Seções ficam dentro das categorias e contêm seus artigos
• Artigos são as peças de conteúdo reais

Essa estrutura é importante porque você não pode simplesmente importar um monte de artigos e classificá-los mais tarde. Você precisa de categorias e seções no lugar primeiro. Se você estiver migrando de outra plataforma, precisará mapear sua estrutura existente para este modelo de três camadas.

Há também uma camada opcional chamada segmentos de usuário, que controlam quem pode ver qual conteúdo. Se você tiver seções restritas (como documentação interna ou artigos exclusivos para VIPs), precisará configurar esses segmentos antes de criar as seções que os utilizam.

Resumindo? Planejar sua estrutura antes de começar a importar economizará horas de trabalho de limpeza mais tarde.

Método 1: Usando a API do Help Center

A API do Zendesk Help Center é a opção mais poderosa e flexível para importar e exportar conteúdo. É também a abordagem que o Zendesk recomenda oficialmente quando você precisa mover grandes quantidades de dados.

O que você vai precisar

Antes de começar com o método da API, certifique-se de que você tem:

• Uma conta Zendesk com acesso à API habilitado
• Um token de API ou credenciais OAuth para autenticação
• Familiaridade básica com APIs REST (ou um desenvolvedor em sua equipe)
• Python (recomendado) ou outra linguagem para scripting

Exportando conteúdo via API

Para exportar seus artigos existentes, você usará o endpoint List Articles:

GET /api/v2/help_center/articles

A API suporta paginação baseada em cursor (preferencial) e paginação de deslocamento. Para grandes centrais de ajuda, a paginação por cursor é mais confiável. Você pode ativá-la adicionando ?page[size]=100 às suas solicitações.

O Zendesk fornece um exemplo de script em Python que explica como fazer backup de toda a sua base de conhecimento. O script lida com a paginação automaticamente e salva cada artigo como um arquivo HTML.

Tenha em mente que a API segue os mesmos limites de taxa da API do Zendesk Support. Se você estiver exportando milhares de artigos, precisará incluir o tratamento de limite de taxa.

Importando conteúdo via API

A importação é mais complexa porque você precisa criar o conteúdo na ordem certa:

1. Importe os autores como usuários do Zendesk primeiro. Defina sua função como "agente" e registre os IDs de usuário retornados pela API.

2. Crie categorias usando o endpoint Create Category. Registre os IDs de categoria para a próxima etapa.

3. Crie segmentos de usuário (opcional) se precisar de acesso restrito. Registre os IDs de segmento.

4. Crie seções dentro de suas categorias, atribuindo o category_id e user_segment_id apropriados.

5. Crie artigos dentro de suas seções, definindo o author_id e section_id para cada um.

6. Carregue anexos separadamente se seus artigos contiverem imagens embutidas que não estão hospedadas publicamente.

Veja como é uma solicitação básica de criação de artigo:

POST /api/v2/help_center/sections/{section_id}/articles
{
  "article": {
    "title": "Guia de Introdução",
    "body": "<p>Bem-vindo ao nosso produto...</p>",
    "author_id": 9873843,
    "locale": "en-us"
  }
}

A API retorna o novo ID do artigo, que você pode usar para associar anexos ou criar traduções.

Quando usar a abordagem da API

O método da API é melhor para:

• Equipes técnicas com recursos de desenvolvimento
• Migrações em larga escala (milhares de artigos)
• Backups automatizados regulares
• Migrações complexas que exigem transformação de dados

Provavelmente é um exagero se você só precisa mover uma dúzia de artigos uma vez.

Método 2: Aplicativos e ferramentas de terceiros

Se escrever scripts em Python não é a sua praia, vários aplicativos no Zendesk Marketplace podem lidar com importações e exportações com uma interface visual.

Help Center Import da Zenplates

O aplicativo Help Center Import da Zenplates é uma compra única de US$ 99,00 que lhe dá uma interface visual para importar conteúdo em massa. Ele suporta:

• Até 500 categorias por importação
• Até 500 seções por importação
• Até 1.000 artigos por importação
• Até 1.000 comentários de artigos por importação

O fluxo de trabalho é simples. Você começa criando linhas em uma tabela interativa, seja manualmente, importando um arquivo CSV ou puxando de outra base de conhecimento pública do Zendesk. Você pode editar campos diretamente na tabela, atualizar linhas em massa e obter feedback visual imediato se algum valor de campo for inválido.

Depois que seus dados estiverem corretos, você os revisa no aplicativo (classificando e filtrando conforme necessário) e, em seguida, clica em Importar. Um indicador de progresso mostra o status e, quando terminar, você recebe um relatório de conclusão com todos os IDs de registro recém-criados.

Limitações a serem conhecidas:

• Anexos de artigos não são importados (apenas conteúdo)
• Referências de links e imagens dentro dos artigos não são modificadas
• O conteúdo é importado apenas para sua marca principal
• Você precisará revisar as imagens embutidas após a importação

Para equipes que movem conteúdo de outra plataforma via CSV, este aplicativo elimina a maior parte da complexidade técnica.

kBackup

kBackup é um aplicativo gratuito de Felix Stubner que se concentra especificamente em backups. É leve, não requer instalação e funciona com um único clique.

Aqui está o que ele faz:

• Exporta o conteúdo do seu Help Center como arquivos HTML nomeados [ArticleId].html
• Verifica se o usuário existe em seu domínio antes de executar (recurso de segurança)
• Funciona mesmo se você usar o mapeamento de host (ele usa o subdomínio original do Zendesk)
• Operação de leitura apenas completamente segura

O aplicativo é particularmente útil se você precisar criar cópias offline do seu conteúdo para fluxos de trabalho de tradução ou backups periódicos. No entanto, é apenas para exportação. Se você precisar importar conteúdo de volta para o Zendesk, precisará de outra ferramenta.

Observação: O aplicativo foi atualizado pela última vez em 2017, então, embora ainda funcione, não é mantido ativamente.

Quando usar aplicativos de terceiros

Os aplicativos são ideais quando:

• Você quer uma interface visual em vez de escrever código
• Sua migração é de tamanho médio (centenas de itens, não milhares)
• Você precisa importar de CSV ou outra instância do Zendesk
• Você prefere um custo único em vez de taxas de serviço contínuas

Método 3: Copiar e colar manualmente e exportar o tema

Às vezes, a abordagem mais simples é a melhor. Se você só precisa mover alguns artigos, copiar e colar manualmente pode ser mais rápido do que configurar APIs ou comprar aplicativos.

Quando o manual faz sentido

A migração manual funciona bem quando:

• Você está migrando menos de 20-30 artigos
• É uma movimentação única em que o tempo de configuração excede o tempo de cópia
• O conteúdo precisa de edição pesada durante a migração de qualquer maneira

Exportando código de tema

Se você precisar fazer backup ou migrar seu tema do Help Center (o HTML, CSS e JavaScript que controla a aparência), o Zendesk fornece ferramentas integradas para isso.

Nos planos Guide Professional ou Enterprise, você pode importar e exportar seu tema e arquivo de manifesto diretamente da interface de administração. Isso lhe dá um arquivo ZIP contendo todo o código do seu tema.

Para planos de nível inferior, você precisará copiar e colar manualmente o código em um editor de texto. Não há acesso à API para código de tema nesses planos.

Limitações da abordagem manual

• Demorado para grandes volumes de conteúdo
• Nenhuma maneira de preservar metadados (autor, data de criação, etc.)
• Imagens e anexos devem ser tratados separadamente
• Nenhuma operação em massa possível

Melhores práticas para uma migração bem-sucedida

Independentemente do método que você escolher, seguir estas práticas evitará dores de cabeça:

Planeje sua estrutura primeiro

Mapeie sua hierarquia de categorias e seções antes de começar a importar. É muito mais fácil acertar a estrutura de antemão do que reorganizar centenas de artigos mais tarde.

Teste em um sandbox

Se você tiver acesso a um ambiente sandbox do Zendesk, execute sua importação lá primeiro. Isso permite que você detecte problemas de formatação, links quebrados e problemas de permissão antes de tocar em sua central de ajuda ativa.

Lide com imagens e anexos com cuidado

A maioria dos métodos de importação não lida automaticamente com imagens embutidas ou anexos de arquivos. Normalmente, você precisará:

• Hospedar imagens em um servidor público (como AWS S3) antes da importação, ou
• Carregar anexos separadamente após importar artigos, ou
• Usar a API para carregar anexos e atualizar o HTML do artigo com os novos URLs

Gerencie a atribuição de autores

Se você estiver importando artigos com autores específicos, esses usuários devem existir em sua conta do Zendesk antes de você importar. A API requer IDs de usuário válidos para atribuição de autores.

Configure redirecionamentos para SEO

Se você estiver migrando de outra plataforma e seus URLs de artigos forem alterados, configure redirecionamentos 301 para preservar suas classificações de pesquisa. Isso é especialmente importante se sua central de ajuda receber tráfego orgânico significativo.

Problemas comuns e solução de problemas

Mesmo com um planejamento cuidadoso, você pode encontrar alguns obstáculos. Veja como lidar com os mais comuns:

Limites de taxa da API

Se seu script atingir limites de taxa, implemente backoff exponencial em sua lógica de repetição. A API do Zendesk retorna um cabeçalho Retry-After informando quanto tempo esperar.

Formatação e limpeza de HTML

O conteúdo importado de outras plataformas geralmente traz HTML bagunçado. Considere executar seu conteúdo por meio de um limpador de HTML antes da importação ou planeje tempo para corrigir problemas de formatação posteriormente.

Erros de permissão do usuário

Se as importações falharem com erros de permissão, verifique se:

• O token da API tem as permissões corretas
• A conta de usuário tem privilégios de agente ou administrador
• Você está usando o subdomínio correto (especialmente para configurações de várias marcas)

Links de imagem quebrados após a migração

Se as imagens foram hospedadas em sua plataforma antiga, elas serão quebradas após a migração. Migre as imagens para um novo host e atualize os URLs ou use a API para carregá-las como anexos do Zendesk.

Uma abordagem melhor: Gerenciamento de conhecimento moderno com tecnologia de IA com eesel AI

Aqui está a questão sobre todos esses métodos de migração: eles são soluções alternativas para um problema fundamental. As centrais de ajuda tradicionais não foram projetadas para mover facilmente o conteúdo entre os sistemas. Cada plataforma prende você em seu próprio formato, sua própria estrutura, sua própria maneira de fazer as coisas.

Nós construímos o eesel AI para resolver isso na fonte. Em vez de forçá-lo a exportar, transformar e importar conteúdo, o eesel AI se conecta diretamente às ferramentas que você já usa. Ele aprende com sua central de ajuda existente, seus tickets de suporte anteriores, seus documentos do Confluence, seus arquivos do Google Drive. Nenhuma migração necessária.

Quando você conecta o eesel AI à sua conta Zendesk, ele começa imediatamente a aprender seu conteúdo e pode responder às perguntas dos clientes com base nesse conhecimento. Se você adicionar posteriormente uma integração com o Slack ou conectar seu workspace do Notion, o eesel AI também aprende com essas fontes. Tudo sem exportar um único artigo.

Isso significa:

• Chega de dores de cabeça com a migração quando você quiser adicionar um novo canal
• Chega de manter o mesmo conteúdo em vários lugares
• Chega de se preocupar com qual plataforma tem a cópia "mestre"

Seu conteúdo permanece onde está hoje. O eesel AI apenas o torna acessível por meio de um agente de IA que pode lidar com o suporte de linha de frente, redigir respostas para sua equipe ou responder a perguntas de funcionários no Slack.

Se você está cansado de lutar com arquivos CSV e scripts de API apenas para mover sua base de conhecimento, pode ser hora de tentar uma abordagem diferente. Você pode ver o eesel em ação e conectá-lo às suas ferramentas existentes em minutos, não em semanas.